feat(subtitles): 补字幕第 1 步——上传字幕 / zip,识别语言与季集,配对写入视频同目录,历史与撤销

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

packages/contracts/src/api/subtitles.ts

@@ -0,0 +1,48 @@
+import { IdParam } from "../common.ts";
+import * as subtitles from "../subtitles.ts";
+import { ep } from "./shared.ts";
+
+export const subtitlesApi = {
+  subtitles: {
+    targets: ep({
+      method: "get",
+      path: "/subtitles/targets",
+      scope: "read",
+      summary: "作品可写字幕的视频（媒体库里的视频位置、季集、同目录已有字幕）",
+      query: subtitles.SubtitleTargetsQuery,
+      response: subtitles.SubtitleTargetsResponse,
+    }),
+    parse: ep({
+      method: "post",
+      path: "/subtitles/parse",
+      scope: "read",
+      summary: "解析上传的字幕 / zip：编码转 UTF-8、识别语言与季集，给出配对建议（不写文件）",
+      body: subtitles.SubtitleParseRequest,
+      response: subtitles.SubtitleParseResponse,
+    }),
+    apply: ep({
+      method: "post",
+      path: "/subtitles/apply",
+      scope: "organize.execute",
+      summary: "写入字幕：视频同目录、视频主干名 + 语言后缀；同名字幕先备份；登记为字幕资产并记历史",
+      body: subtitles.SubtitleApplyRequest,
+      response: subtitles.SubtitleApplyResult,
+    }),
+    writes: ep({
+      method: "get",
+      path: "/subtitles/writes",
+      scope: "read",
+      summary: "作品的补字幕历史",
+      query: subtitles.SubtitleWritesQuery,
+      response: subtitles.SubtitleWritesResponse,
+    }),
+    undo: ep({
+      method: "post",
+      path: "/subtitles/writes/{id}/undo",
+      scope: "organize.execute",
+      summary: "撤销一次写入：删掉写入的字幕，覆盖过的还原备份",
+      params: IdParam,
+      response: subtitles.SubtitleWriteView,
+    }),
+  },
+} as const;