fix(media): 修正转码媒资 id 解析与存量分集补登记

docs/plans/PROGRESS.md

@@ -25460,3 +25460,92 @@ $ mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test
 解读：P2 查询测试、worker 入队/失败回写测试和新增宽高比 smoke 全部通过。
 未启停服务、未执行数据库变更、未改前端/App/specs 或 P2 接口字段。
 
+## 2026-10-22 转码媒资 ID 精度与存量兜底
+
+- 分支：`feature/transcode-media-id-fix`
+- 基线：`develop` / `origin/develop` = `a35b02d`
+
+### 现场取证
+
+数据库只读查询确认：
+
+```text
+drama_episode.id             = 2113150431755636737
+drama_episode.video_asset_id = 2113150398670966786
+media_asset.id               = 2113150398670966786
+transcode_task.media_asset_id= 2113150398670966786
+```
+
+JS 精度复现：
+
+```text
+raw:              2113150398670966786
+Number(raw):      2113150398670966800
+serialized:       2113150398670966800
+same:             false
+```
+
+解读：错误来自前端 Number 转换后的 Snowflake ID 精度丢失；后端兜底仍需覆盖
+存量分集 video_asset_id 为空或误传分集/任务 ID 的情况。
+
+### TDD 红测
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=MediaServiceTranscodePipelineTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] 找不到符号: 类 EpisodeVideoSourcePort
+[INFO] BUILD FAILURE
+
+$ mvn -pl fruitshorts-admin-api -am \
+  -Dtest=EpisodeTranscodeAdminServiceTest,EpisodeTranscodeContractTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] String 无法转换为 Long
+[ERROR] 找不到符号: 方法 mediaAssetExists(Long)
+[INFO] BUILD FAILURE
+```
+
+解读：红测先锁定字符串契约和跨域分集来源端口，生产代码尚未实现。
+
+### 实现
+
+- `EpisodeVideoSourcePort` 由 content 域 `EpisodeService` 实现，可按分集 id 或
+  `video_asset_id` 找到分集来源，并回填 `video_asset_id`。
+- 手动转码先按 media_asset.id 锁定；未命中时通过端口找到分集，
+  按 video_url → source_url/objectKey 反查媒资。
+- 仍缺失但本地文件真实存在时自动补登记 `media_asset`，再调用原转码入队。
+- 聚合接口先按 video_url 解析媒资，失败才校验 `video_asset_id`；
+  episodeId/mediaAssetId/taskId 均显式转字符串。
+- 无媒资空态返回 `NO_MEDIA_ASSET` 和可读 errorMsg。
+
+### 定向测试
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=MediaServiceTranscodePipelineTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
+[INFO] BUILD SUCCESS
+
+$ mvn -pl fruitshorts-admin-api -am \
+  -Dtest=EpisodeTranscodeAdminServiceTest,EpisodeTranscodeContractTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
+[INFO] BUILD SUCCESS
+```
+
+### 最终门禁
+
+```text
+$ mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test
+[INFO] Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
+[INFO] Tests run: 37, Failures: 0, Errors: 0, Skipped: 0
+[INFO] BUILD SUCCESS
+
+$ mvn -pl fruitshorts-admin-api -am test
+[INFO] Tests run: 53, Failures: 0, Errors: 0, Skipped: 0
+[INFO] BUILD SUCCESS
+```
+
+解读：精度字符串、空态、video_url 反查命中、文件存在补登记及原有转码链全部通过。
+