test(media): 覆盖转码入队与重转幂等

2026-10-22 14:01:26 +08:00
1 parent cd51aabe7e
commit 7e6075a2e9
@@ -0,0 +1,37 @@
+# 后台转码链路打通
+
+## 现状取证
+
+- 上传完成时 `MediaService.complete` 已为视频调用 `TranscodeService.enqueue`。
+- 分集创建/替换视频地址时 `EpisodeService` 已调用
+  `EpisodeTranscodeBindingService.bind`，会复用并绑定同一媒体的未完成任务。
+- 转码失败原因已写入 `transcode_task.error_msg`，最终状态写入 `status`。
+- 缺口是后台手动触发/重转接口，以及对应幂等和链路测试。
+
+## 实现
+
+1. 保留上传完成和改片自动入队逻辑，补测试锁定行为。
+2. `TranscodeService` 增加手动触发：
+   - QUEUED/RUNNING 直接返回现有任务；
+   - FAILED 重置原任务为 QUEUED；
+   - SUCCESS 才创建新任务，紧接着重复触发会复用新 QUEUED 任务。
+3. 新增 `POST /admin/media/{id}/transcode`，校验媒资存在，复用 `episode:upload`。
+4. 返回任务 id 与状态，便于后台提示。
+
+## TDD 测试矩阵
+
+| 场景 | 断言 |
+| --- | --- |
+| 视频上传完成 | `MediaService.complete` 调用一次 `enqueue(assetId, 0, 0, sourceUrl)` |
+| 图片上传完成 | 不创建转码任务 |
+| 手动触发成功媒资 | 新建一个 QUEUED 任务，重复调用复用同一任务 |
+| 手动触发进行中媒资 | 直接返回 QUEUED/RUNNING 任务，不新增记录 |
+| 手动触发失败媒资 | 原任务重置为 QUEUED，保留任务 id |
+| 媒资不存在 | 返回既有 `DATA_NOT_FOUND`，控制器不产生 500 |
+| worker 最终失败 | 任务状态 FAILED，`error_msg` 保留 ffmpeg 原因 |
+
+## 验证
+
+- 先提交失败测试，再提交实现。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`
+- 不启停任何服务，不执行数据库变更，不改 Web/Flutter/specs/API 文档。
@@ -25205,3 +25205,54 @@ dramaTitle/episodeNumber/totalEpisodes 非空、越界页空 list 且 total 保
 `limit` 旧 List 兼容均通过；服务层断言 `selectPage`、稳定排序和两批 IN 查询。
 未启停服务、未操作真机、未修改客户端。

+## 2026-10-22 后台转码链路打通 P1
+
+- 分支：`feature/media-transcode-pipeline`
+- 基线：`develop` / `origin/develop` = `cd51aabe`
+- 隔离工作树：`/private/tmp/fruitserver-media-pipeline`
+- 计划：`docs/plans/2026-10-22-media-transcode-pipeline.md`
+
+### 现状取证
+
+- `/admin/media/upload/complete`：视频完成合并后会调用
+  `transcodeService.enqueue(assetId, 0L, 0L, sourceUrl)`；图片直接置 ready，不入队。
+- 分集创建/更新并保存 `videoUrl`：`EpisodeService` 调用
+  `EpisodeTranscodeBindingService.bind`，按 objectKey 找到 `media_asset`，
+  再把 `dramaId/episodeId/sourceUrl` 绑定到任务；未完成任务复用，不重复入队。
+- worker：`claimNext` 只认领 `episode_id > 0`；成功后回填媒资 HLS、分集播放地址与时长；
+  失败超过 3 次写 `FAILED + error_msg`。这些既有链路已由新增测试锁定。
+- 实际缺口：后台没有手动触发/重转接口，也没有其幂等测试。
+
+### TDD 红测
+
+先只提交测试，不写生产实现。定向命令：
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=MediaServiceTranscodePipelineTest,TranscodeServiceTriggerTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] ... MediaServiceTranscodePipelineTest.java:[13,32] 找不到符号
+  符号: 类 TranscodeTriggerRespVO
+[ERROR] ... TranscodeServiceTriggerTest.java:[15,32] 找不到符号
+  符号: 类 TranscodeTriggerRespVO
+[INFO] fruitshorts-transcode-worker ....................... FAILURE
+[INFO] BUILD FAILURE
+```
+
+解读：失败原因为预期的生产接口尚不存在，不是测试环境或既有代码编译问题。
+下一步再实现最小生产代码令红测转绿。
+
+控制器契约红测同样先失败在缺失的响应类型：
+
+```text
+$ mvn -pl fruitshorts-admin-api -am \
+  -Dtest=MediaTranscodeTriggerContractTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] MediaTranscodeTriggerContractTest.java:[11,32] 找不到符号
+  符号: 类 TranscodeTriggerRespVO
+[INFO] fruitshorts-admin-api .............................. FAILURE
+[INFO] BUILD FAILURE
+```
+
+解读：控制器测试已经先于实现落地，现有上传/分集链路未被破坏。
+