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

转码分集绑定与运行态修复

已确认现场

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，不操作真机。