FruitServer/docs/plans/2026-10-22-media-transcode-output-api.md

转码产物查询接口

目标

• 媒体维度查询 rendition 与帧图产物。
• 分集维度聚合转码任务、rendition、帧图状态。
• /admin/dashboard/transcode 改为明确 VO，OpenAPI 不再出现匿名 Object。

设计

1. MediaTranscodeOutputService 统一读取媒体、任务、rendition 与 thumbnail。
2. rendition 按高度、视频码率、质量倒序，id 正序保证稳定。
3. thumbnail 优先读取 thumbnails.vtt，解析 cue 后分页；无记录返回 EMPTY， 记录失败返回 FAILED，不把缺产物当服务错误。
4. 分集聚合对不存在、无视频、无媒资、无任务返回明确 status 和空列表。
5. dashboard 使用强类型 queue/failed task VO，保留现有字段语义并补 total。

接口

• GET /admin/media/{id}/renditions
• GET /admin/media/{id}/thumbnails?pageIndex=1&pageSize=100
• GET /admin/episodes/{id}/transcode
• GET /admin/dashboard/transcode（响应类型由 Map 收敛为 VO）

缩略图响应内嵌 PageResult<MediaThumbnailFrameVO>，同时返回 sprite/VTT 元数据； 空产物 status 为 EMPTY，无绑定分集为 NO_EPISODE，损坏 VTT 为 INVALID。

TDD

• 先提交媒体有/无产物、不存在、VTT 解析与分页边界测试。
• 再提交接口、VO、聚合服务和 dashboard 类型收敛实现。
• 门禁：mvn -pl fruitshorts-module-media test。

红线

• 不改 /app 契约、specs、ReelShortWeb、Flutter。
• 不改 P1 入队与手动重转逻辑。
• 不启停服务，不操作真机。