fix(media): 补齐分集转码绑定与产物回填

docs/plans/2026-10-22-transcode-binding-fix.md

@@ -0,0 +1,38 @@
+# 转码分集绑定与运行态修复
+
+## 已确认现场
+
+admin-api/app-api/worker 均运行旧包；worker 未运行；`media_thumbnail` 表缺失；
+新上传任务 drama_id/episode_id 为 0；旧 worker jar 缺 MediaThumbnail。
+
+## 代码修复
+
+1. 分集保存后按视频 URL 的 objectKey 查找 `media_asset`。
+2. media 域新增绑定服务：
+   - 将 dramaId/episodeId 回填到对应 `transcode_task`；
+   - QUeued/RUNNING/SUCCESS 任务复用，不重复入队；
+   - FAILED/CANCELED 或不存在时新建任务；
+   - 已成功但 episodeId=0 的 rendition 同步回填。
+3. `claimNext` 只认领 `episode_id > 0`，零绑定任务保留 QUEUED。
+4. 缩略图登记使用 REQUIRES_NEW 独立事务；生成或登记失败只记 warn/error_msg，
+   主任务仍 SUCCESS。
+5. 对 episode_id=0 且源文件不存在的明显测试垃圾标记 CANCELED，不删除。
+
+## 迁移与运行
+
+1. 确认 `media_thumbnail` 不存在后执行幂等 patch。
+2. `mvn -DskipTests package` 全量重建。
+3. 检查三个 jar 分别含：
+   - admin-api：MediaTranscodeProfile；
+   - app-api：PlayRespVO.thumbnailsUrl 对应新类；
+   - worker：MediaThumbnail / MediaThumbnailMapper。
+4. 重启 8080/8081/worker，日志写 `logs/*.log`。
+5. 冒烟 admin 配置、App 详情 thumbnailsUrl、worker 轮询。
+6. 上传真实视频，创建绑定分集，等待 worker 消费，验证任务、四档 HLS、
+   media_thumbnail、VTT 与 sprite HTTP 200。
+
+## 风险
+
+- 旧 QUEUED 中无法绑定且源文件不存在的测试任务将被取消并记录 id。
+- 真实视频端到端验证会写入运行数据库和媒资目录。
+- 不修改 Web/Flutter，不操作真机。