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

## 目标

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 后续环境验收，
  本任务不启动服务、不改客户端。