feat(metadata): field-level episode metadata, titleZh and refresh?full=1 (MD-1)

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

packages/contracts/src/api.ts

@@ -149,6 +149,12 @@ const FieldOverrideResult = z.object({
   lockedFields: z.array(z.string()),
 });
 const FieldParam = z.object({ id: Id, field: content.EntityMetadataField });
+const UnitFieldParam = z.object({ id: Id, field: content.UnitMetadataField });
+const UnitFieldOverrideResult = z.object({
+  contentUnitId: Id,
+  changedFields: z.array(z.string()),
+  lockedFields: z.array(z.string()),
+});
 
 /** 引擎 run id 不是 uuid(openworkflow 自有 id) */
 const EngineRunIdParam = z.object({ id: z.string().min(1).max(200) });
@@ -219,8 +225,10 @@ export const Api = {
       method: "post",
       path: "/media-entities/{id}/refresh",
       scope: "organize.execute",
-      summary: "刷新元数据（字段级；用户锁优先，不动路径）",
+      summary:
+        "刷新元数据（字段级；用户锁优先，不动路径）。标题 / 简介按设置 metadata.languages 回退；full=1 拉取全部季的每集信息",
       params: IdParam,
+      query: z.object({ full: z.enum(["0", "1", "true", "false"]).optional() }),
       response: TaskAccepted,
     }),
     setField: ep({
@@ -241,16 +249,35 @@ export const Api = {
       response: FieldOverrideResult,
     }),
   },
-  contentUnits: crud(
-    "/content-units",
-    "内容单元",
-    {
-      row: content.ContentUnit,
-      update: content.ContentUnitUpdate,
-      filters: { mediaEntityId: Id.optional(), seasonNumber: z.coerce.number().int().optional() },
-    },
-    R,
-  ),
+  contentUnits: {
+    ...crud(
+      "/content-units",
+      "内容单元",
+      {
+        row: content.ContentUnit,
+        update: content.ContentUnitUpdate,
+        filters: { mediaEntityId: Id.optional(), seasonNumber: z.coerce.number().int().optional() },
+      },
+      R,
+    ),
+    setField: ep({
+      method: "put",
+      path: "/content-units/{id}/fields/{field}",
+      scope: "organize.execute",
+      summary: "覆盖季 / 集字段并锁定（元数据刷新不再改写）",
+      params: UnitFieldParam,
+      body: content.FieldOverrideInput,
+      response: UnitFieldOverrideResult,
+    }),
+    clearField: ep({
+      method: "delete",
+      path: "/content-units/{id}/fields/{field}",
+      scope: "organize.execute",
+      summary: "取消季 / 集字段覆盖与锁定",
+      params: UnitFieldParam,
+      response: UnitFieldOverrideResult,
+    }),
+  },
   titleAliases: {
     ...crud(
       "/title-aliases",
@@ -2224,6 +2251,14 @@ export const Api = {
       query: search.TmdbMediaQuery,
       response: search.TmdbMediaDetail,
     }),
+    tmdbSeason: ep({
+      method: "get",
+      path: "/media/tmdb/tv/{id}/season/{season}",
+      scope: "read",
+      summary: "仅 TMDB 剧集的季详情与每集信息（标题 / 简介按语言回退链；走 TMDB 请求缓存）",
+      params: search.TmdbSeasonParams,
+      response: search.TmdbSeasonDetailView,
+    }),
   },
 
   // ── 浏览器(C1-E):站点浏览器会话、原站视图、人工接管;写动作需人工持有控制权(接管) ──