feat(file-manager): v2 backend gaps — TMDB candidate entities, min size, on-existing, naming source (W9-H)

- G1 createEntityFromTmdbCandidate (sources-identity service): entity + accepted
  manual external identity + season/episode units, idempotent per TMDB id;
  POST /files/entity-from-candidate and organize items with `external`
- G2 minSizeBytes for organize (excluded below_min_size) and identify
  (skipped + excludedBySize)
- G3 onExisting passed to planImport; dryRun marks each file
  (same/skip/replace/conflict); replace = explicit grant
- G4 naming template|keep; planImport namingMode/namingSource, frozen
  plan.naming {mode, templateSource, templateVersion}; targetSegments
- G5 identify prior-record hints, GET /files/record-sources, organize
  refreshMetadata, POST /files/scrape-batch (dedupe by entity)
- G8 GET /files/tree (parent, subdirs hasChildren, video/registered counts)
- G9 POST /files/suggest-name returns 501 until the naming engine lands

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/server/src/modules/file-manager/probe.ts

@@ -6,6 +6,8 @@ import type {
   FileProbeItem,
   FilesProbeRequest,
   FilesProbeResult,
+  FilesScrapeBatchRequest,
+  FilesScrapeBatchResult,
   FilesScrapeRequest,
   FilesScrapeResult,
 } from "@umt/contracts";
@@ -14,6 +16,7 @@ import type { Principal } from "../../http/auth.ts";
 import { FilesError, type FmDeps, jsonb, resolveIn } from "./common.ts";
 import { audit } from "./ledger.ts";
 import { kindOfName, mediaSummary } from "./list.ts";
+import { entitiesUnder } from "./records.ts";
 
 // probe:ffprobe 摘要;已登记资产写回 media_asset.media_info.probe,未登记只缓存 24h(DATA_DIR/cache/probe)。
 // scrape:只对已登记作品,等价 POST /media-entities/{id}/refresh(入队 refreshMetadata,字段锁优先、不动路径);
@@ -141,3 +144,77 @@ export async function scrape(
   await audit(d, principal, "scrape", { ...result });
   return result;
 }
+
+/**
+ * G5 批量刷新元数据:文件/目录归到其下已登记资产的作品,与显式作品合并去重,逐个入队 refreshMetadata。
+ * 只对有 active 资产的作品提交;其余进 skipped(前端汇总"已提交 n 个作品,锁定字段不变")。
+ */
+export async function scrapeBatch(
+  d: FmDeps,
+  principal: Principal | undefined,
+  body: FilesScrapeBatchRequest,
+): Promise<FilesScrapeBatchResult> {
+  const db = d.ctx.db;
+  const skipped: FilesScrapeBatchResult["skipped"] = [];
+  const ids = new Set(body.mediaEntityIds ?? []);
+  for (const it of body.items ?? []) {
+    const r = await resolveIn(d, it.root, it.path);
+    const found = r.def.libraryRootId
+      ? await entitiesUnder(db, r.def.libraryRootId, r.rel, !!r.lst?.isDirectory())
+      : [];
+    if (found.length === 0) skipped.push({ ref: `${it.root}:${it.path}`, reason: "no_entity" });
+    for (const id of found) ids.add(id);
+  }
+  if (ids.size === 0 && skipped.length === 0) throw new FilesError("bad_request", "需要 items 或 mediaEntityIds");
+  if (ids.size > 200) throw new FilesError("bad_request", `一次最多刷新 200 个作品(本次 ${ids.size})`);
+  const list = [...ids];
+  const ents = list.length
+    ? await db.selectFrom("media_entity").select(["id", "title", "field_locks"]).where("id", "in", list).execute()
+    : [];
+  const active = new Set(
+    list.length
+      ? (
+          await db
+            .selectFrom("media_asset")
+            .select(["media_entity_id"])
+            .where("media_entity_id", "in", list)
+            .where("status", "=", "active")
+            .execute()
+        ).map((a) => a.media_entity_id)
+      : [],
+  );
+  const locks = list.length
+    ? await db
+        .selectFrom("field_override")
+        .select(["media_entity_id", "field"])
+        .where("media_entity_id", "in", list)
+        .where("locked", "=", true)
+        .execute()
+    : [];
+  const submitted: FilesScrapeBatchResult["submitted"] = [];
+  for (const id of list) {
+    const e = ents.find((x) => x.id === id);
+    if (!e) {
+      skipped.push({ ref: id, reason: "not_found" });
+      continue;
+    }
+    if (!active.has(id)) {
+      skipped.push({ ref: id, reason: "not_registered" });
+      continue;
+    }
+    const { runId } = await d.ctx.engine.enqueue(
+      "refreshMetadata",
+      { mediaEntityId: id },
+      { idempotencyKey: `refreshMetadata:files-batch:${body.idempotencyKey}:${id}`, traceId: randomUUID() },
+    );
+    const lockedFields = [
+      ...new Set([...(e.field_locks ?? []), ...locks.filter((l) => l.media_entity_id === id).map((l) => l.field)]),
+    ].sort();
+    submitted.push({ mediaEntityId: id, title: e.title, taskId: runId, lockedFields });
+  }
+  await audit(d, principal, "scrape_batch", {
+    submitted: submitted.map((s) => s.mediaEntityId),
+    skipped,
+  });
+  return { submitted, skipped };
+}