FruitServer/docs/plans/2026-10-22-media-transcode-profile-sprite.md

转码档位配置、雪碧图与播放缩略图轴

目标

1. 后台可配置转码档位与雪碧图参数，worker 对之后的新任务在 30 秒内自动生效。
2. 转码成功后生成雪碧图与 VTT，登记到 media_thumbnail。
3. 播放接口与详情剧集返回 thumbnailsUrl，无产物时为 null。

配置模型

• sys_config.config_key = media.transcode.profile，值为 JSON。
• 配置包含总开关、分片秒数、码率阶梯与雪碧图参数。
• 缺省配置等价于现有 360p/480p/720p/1080p 四档。
• 后台 GET 缺省或历史配置非法时返回 yml 等价默认值；PUT 非法时返回统一 400，且不写库。
• worker 读取配置缓存 30 秒；缺省、解析失败或校验失败时回退 yml 默认阶梯。

权限取舍

现有权限点没有 media:transcode。本次两个接口复用最小可用的 episode:upload，避免新增权限点导致已有角色需要补授权；不新增菜单或权限 SQL。

数据与产物

• 新增 media_thumbnail，按 episode_id 唯一，记录 VTT、雪碧图前缀、采样参数、 尺寸、帧数、时长、状态、错误与总大小。
• 雪碧图目录固定在 transcoded/{taskId}/thumbnails/： thumbnails.vtt + sprite_001.jpg 等多张图。
• VTT cue 链接使用相对路径 sprite_XXX.jpg#xywh=x,y,w,h，同一 VTT 目录下可直接解析。
• 缩略图失败只把 media_thumbnail.status 置 FAILED 并记录错误；主 HLS 仍成功。

播放

• PlayRespVO 和 AppEpisodeVO 增加 thumbnailsUrl。
• 查询 media_thumbnail 仅读取 READY 产物；objectKey 经 MediaStorageService.toPublicUrl 后使用现有 PlaybackSigner 签名。
• 详情剧集列表批量查询缩略图，禁止 N+1。
• 不改变现有 HLS/原文件回落与 qualities 列表。

测试

• worker：配置解析、非法配置回退 yml、30 秒缓存、VTT 坐标、多雪碧图索引、 缩略图失败不阻断主转码。
• admin：GET 默认值、PUT 非法不落库、PUT 成功落库。
• playback：有 READY 缩略图返回签名 thumbnailsUrl，无产物返回 null。
• 门禁：mvn -pl fruitshorts-transcode-worker,fruitshorts-admin-api,fruitshorts-app-api -am test。

风险 / 边界

• 本次只对合并后的新转码任务生效，不回跑历史任务。
• 配置中的顶层 enabled 会持久化并返回；本单不改变既有队列消费开关语义， worker 仍以 worker-enabled 决定是否消费任务。
• 雪碧图生成依赖 ffmpeg tile 滤镜；真实产物由 worker 门禁和 PM 后续环境验收， 本任务不启动服务、不改客户端。