feat(cache): TMDB / 豆瓣 / Bangumi 接入统一元数据缓存与策略表

- 策略表「来源 × 资源类型」(metaCachePolicy):搜索 / 识别 7 天(空 1 天)、详情 / 季 / 剧集组 30 天(空 1 天)、
  榜单 / 热门 / 每日放送 6 小时(空 1 小时)、人物 / 图片 90 天;取值来自 storage.cacheTtl,
  追加 tmdbListHours / tmdbListEmptyHours / imageDays / metaDetailDays / metaMissDays,metaSearchDays 缺省改 7 天
- TMDB 客户端共享缓存端口加 fetch(带请求类别与空结果判定),服务端整条读取交给 MetadataCache;
  识别缓存、douban.request / bangumi.request、douban.subject / bangumi.subject、meta.subject_miss、discover.match 都走这一层
- 豆瓣 / bgm 条目只在「不存在」时记查无,网络失败 / 被拦不缓存(本进程冷却 30 分钟)
- 关注中作品(isEntityWatched 口径,含选中的剧集组)的 TMDB 条目写入 pinned、命中续期
- 各进程启动 LISTEN 失效通知并每分钟把命中计数写 cache_stat;GET /cache/regions 给元数据 region 带近 7 天命中统计

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei

apps/server/src/modules/sources-identity/runtime.ts

@@ -11,19 +11,13 @@ import {
   type SiteDefinition,
   type SiteRateLimiter,
   type TmdbClient,
+  type TmdbRequestKind,
   type TmdbSharedCache,
 } from "@umt/adapters";
 import { DEFAULT_SETTINGS, type SitesSettings } from "@umt/contracts";
 import { pgTokenBucketFor, type SiteRow, sql } from "@umt/db";
 import { egressKey, externalFetch, siteEgress, siteFetchFor } from "../../egress.ts";
-import {
-  CACHE_REGIONS,
-  renewTrackedTmdbDetail,
-  sharedCache,
-  type TmdbCachePolicy,
-  tmdbCachePolicy,
-  tmdbDetailRef,
-} from "../../shared-cache.ts";
+import { CACHE_REGIONS, metadataCache, type TmdbCachePolicy, tmdbCachePolicy, watchedPin } from "../../shared-cache.ts";
 import type { ServerContext } from "../types.ts";
 import { CloudflareGate, withClearance } from "./service/cloudflare.ts";
 import { failureSampleSink } from "./service/failure-sample.ts";
@@ -165,6 +159,8 @@ export class SourcesRuntime {
               ttlMs: policy.ttl * 1000,
               searchTtlMs: policy.searchTtl * 1000,
               emptyTtlMs: policy.emptyTtl * 1000,
+              listTtlMs: policy.listTtl * 1000,
+              imageTtlMs: policy.imageTtl * 1000,
             },
             sharedCache: tmdbSharedCache(this.ctx, policy),
           }
@@ -420,28 +416,34 @@ export class SourcesRuntime {
 }
 
 /**
- * TMDB 请求响应缓存:PG kv_cache region=tmdb.request;PG 出错按未命中 / 不写处理,不让 TMDB 请求失败。
- * 详情命中且属于追踪中的作品时续期(CACHE-2),续期失败只记 debug。
+ * TMDB 请求响应缓存:统一元数据缓存 region=tmdb.request(L1 进程内存 + L2 kv_cache,过期先用旧值后台刷新、同请求合并)。
+ * TTL 按请求类别取策略表(搜索 / 详情 / 列表 / 图片);关注中作品的条目写入 pinned、命中续期。
+ * PG 出错按未命中 / 不写处理,不让 TMDB 请求失败。get / set 保留给不走 fetch 的旧调用方。
  */
-function tmdbSharedCache(ctx: ServerContext, policy: TmdbCachePolicy): TmdbSharedCache {
-  const cache = sharedCache(ctx);
-  const warn = (err: unknown) =>
-    ctx.logger.warn({ err: { message: (err as Error).message } }, "TMDB 缓存读写失败，按未命中处理");
+export function tmdbSharedCache(ctx: ServerContext, policy: TmdbCachePolicy): TmdbSharedCache {
+  const cache = metadataCache(ctx);
+  const region = CACHE_REGIONS.tmdbRequest;
+  const ttlOf = (kind: TmdbRequestKind) =>
+    kind === "search"
+      ? { ttl: policy.searchTtl, emptyTtl: policy.emptyTtl }
+      : kind === "list"
+        ? { ttl: policy.listTtl, emptyTtl: policy.listEmptyTtl }
+        : kind === "image"
+          ? { ttl: policy.imageTtl, emptyTtl: policy.emptyTtl }
+          : { ttl: policy.ttl, emptyTtl: policy.emptyTtl };
   return {
-    get: async (key) => {
-      const v = await cache.get(CACHE_REGIONS.tmdbRequest, key).catch((e) => {
-        warn(e);
-        return null;
-      });
-      if (v !== null && tmdbDetailRef(key)) {
-        await renewTrackedTmdbDetail(ctx, key, policy.ttl).catch((e) =>
-          ctx.logger.debug({ err: { message: (e as Error).message } }, "TMDB 详情缓存续期失败"),
-        );
-      }
-      return v;
-    },
+    fetch: (req, load) =>
+      cache.fetch(
+        region,
+        req.key,
+        { ...ttlOf(req.kind), isEmpty: req.isEmpty, maxsize: policy.maxsize, pin: watchedPin(ctx, req.key) },
+        load,
+      ),
+    get: (key) => cache.get(region, key),
     set: (key, value, ttlMs) =>
-      cache.set(CACHE_REGIONS.tmdbRequest, key, value, { ttl: ttlMs / 1000, maxsize: policy.maxsize }).catch(warn),
+      cache
+        .set(region, key, value, { ttl: ttlMs / 1000, maxsize: policy.maxsize })
+        .catch((e) => ctx.logger.warn({ err: { message: (e as Error).message } }, "TMDB 缓存读写失败，按未命中处理")),
   };
 }