fix(media): 转码错误信息截断并上报进度

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

@@ -0,0 +1,29 @@
+# 转码错误截断与进度上报
+
+## 问题
+
+- ffmpeg 错误输出超过 `error_msg varchar(500)`，失败回写 UPDATE 再次失败，
+  任务停在 RUNNING/0。
+- worker 未解析 ffmpeg progress，前端只能看到 0。
+- 缺少 RUNNING 超时收口。
+
+## 修复
+
+1. SQL patch 将 transcode_task/media_thumbnail 的 error_msg 改为 TEXT，可重复执行。
+2. 新增统一错误消息截断，最多保留 500 字符并附总长度；即使补丁尚未执行，
+   也不会超过旧 varchar(500) 限制。
+3. ffmpeg 使用 `-progress` 临时文件，worker 节流为约 1 秒写 transcode_task.progress。
+4. rendition 阶段映射 0-90%，封面/缩略图 90-99%，成功后 100。
+5. 失败保留最后进度；RUNNING 超过 10 分钟无 updated_at 变化标记 FAILED。
+6. 手动重转复用最新任务，SUCCESS/FAILED/CANCELED 原地重置为 QUEUED、progress=0。
+7. 成功写 rendition 前替换同媒资旧产物，避免重复重转唯一键冲突。
+
+## 风险
+
+- 进度写入只允许 RUNNING 状态，避免覆盖已完成/失败状态。
+- 历史僵尸任务由 worker 下一轮自动收口，无需手工 SQL。
+
+## 验证
+
+- 错误截断、进度更新、僵尸重置、重复触发幂等测试。
+- `mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/PROGRESS.md

@@ -25549,3 +25549,79 @@ $ mvn -pl fruitshorts-admin-api -am test
 
 解读：精度字符串、空态、video_url 反查命中、文件存在补登记及原有转码链全部通过。
 
+## 2026-10-22 转码错误截断与进度上报
+
+- 分支：`feature/transcode-progress-fix`
+- 基线：`develop` / `origin/develop` = `f9bc6ee`
+- 计划：`docs/plans/2026-10-22-transcode-progress-fix.md`
+
+现场根因已确认：ffmpeg 错误信息超过 error_msg varchar(500)，回写失败使任务
+停留在 RUNNING/0；同时现有 runner 未解析 ffmpeg progress，缺少 RUNNING 超时自愈。
+
+### TDD 红测
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=TranscodeServiceTriggerTest,TranscodeWorkerTest,FfmpegTranscodeRunnerSmokeTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] TranscodeRequest 找不到 progressListener
+[ERROR] 找不到符号: 方法 updateProgress(Long,int)
+[ERROR] 找不到符号: 方法 recoverStaleRunningTasks()
+[INFO] BUILD FAILURE
+```
+
+解读：红测先锁定进度回调、进度落库和僵尸自愈接口，生产代码尚未实现。
+
+### 实现
+
+- error_msg 写库前统一截断为最多 500 字符，附 `truncated,total=...`；
+  即使数据库补丁尚未执行，也不会超过旧 varchar(500)。
+- ffmpeg 使用临时 `-progress` 文件，每 500ms 解析 out_time，
+  worker 最多每秒写一次 transcode_task.progress；只更新 RUNNING 状态。
+- rendition 阶段映射 0-90%，封面/缩略图 90-99%，成功事务置 100；
+  失败保留最后进度。
+- RUNNING 且 updated_at 超过 10 分钟未变化时自动标记 FAILED。
+- 手动重转复用最新任务，SUCCESS/FAILED/CANCELED 均原任务重置为 QUEUED、progress=0。
+- 成功写 rendition 前删除同媒资旧产物，避免重复重转唯一键冲突。
+- 聚合 VO 和任务 VO 增加 updatedAt，供前端展示最近更新时间。
+
+### SQL 补丁
+
+文件：`sql/patch-2026-10-22-transcode-error-msg.sql`
+
+PM 按项目现有 patch 方式执行（本任务未执行数据库变更），例如使用项目当前
+PostgreSQL 连接串：
+
+```text
+$ psql "$DB_URL" -f sql/patch-2026-10-22-transcode-error-msg.sql
+```
+
+脚本只将 `transcode_task.error_msg` 与 `media_thumbnail.error_msg`
+改为 TEXT，可重复执行。
+
+### 定向测试
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=TranscodeServiceTriggerTest,TranscodeWorkerTest,FfmpegTranscodeRunnerSmokeTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[INFO] Tests run: 16, 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: 39, 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
+```
+
+解读：真实 ffmpeg smoke 已有进度回调且达到 90% 阶段点；长错误截断、
+进度更新、僵尸任务收口、重复触发复用均通过。
+