feat(contracts): file manager v2 backend gaps G1-G9 (W9-H)

- FilesOrganizeItem.external (TMDB candidate, xor mediaEntityId); request
  minSizeBytes / onExisting (skip|conflict|replace_with_verify) / naming
  (template|keep) / refreshMetadata
- FilesOrganizeGroup: per-file action/existing/skipReason, excluded[]
  (below_min_size), entity, naming{mode,templateSource,templateVersion},
  targetSegments, refreshTaskId
- identify: minSizeBytes, item size/skipped/records, excludedBySize
- new endpoints: entity-from-candidate, scrape-batch, tree, record-sources,
  suggest-name; FilesErrorReason not_implemented

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

packages/contracts/src/api.ts

@@ -1396,6 +1396,47 @@ export const Api = {
       query: files.FilesRecordsQuery,
       response: files.FilesRecordsResult,
     }),
+    // W9-H 文件管理 v2 后端缺口
+    entityFromCandidate: ep({
+      method: "post",
+      path: "/files/entity-from-candidate",
+      scope: "organize.execute",
+      summary: "按 TMDB 候选就地建本地作品 + 外部映射(accepted/manual)+ 季集单元;幂等",
+      body: files.FilesEntityFromCandidateRequest,
+      response: files.FilesEntityFromCandidateResult,
+    }),
+    scrapeBatch: ep({
+      method: "post",
+      path: "/files/scrape-batch",
+      scope: "organize.execute",
+      summary: "批量刷新元数据:按作品去重入队 refreshMetadata(锁定字段不变)",
+      body: files.FilesScrapeBatchRequest,
+      response: files.FilesScrapeBatchResult,
+    }),
+    tree: ep({
+      method: "get",
+      path: "/files/tree",
+      scope: "organize.read",
+      summary: "目录摘要:上一级、子目录(是否有下级)、视频/已登记计数(树与上一级用)",
+      query: files.FilesTreeQuery,
+      response: files.FilesTreeResult,
+    }),
+    recordSources: ep({
+      method: "get",
+      path: "/files/record-sources",
+      scope: "organize.read",
+      summary: "整理记录的源路径换算成登记目录 FileRef(重新整理用)",
+      query: files.FilesRecordSourcesQuery,
+      response: files.FilesRecordSourcesResult,
+    }),
+    suggestName: ep({
+      method: "post",
+      path: "/files/suggest-name",
+      scope: "organize.read",
+      summary: "按命名模板生成推荐名(命名引擎未就绪时 501)",
+      body: files.FilesSuggestNameRequest,
+      response: files.FilesSuggestNameResult,
+    }),
   },
 
   // ── 能力 ──