7.9 KiB
动作规划版本与视频质量接口补充建议归档
2026-10-14 更新:后三项已由后端实现。以下保留 2026-10-13 的建议清单;实际接口以同级后端的 docs/api/public/motion-plan-revisions.md 为准,前端已按实际契约接入。
前端需要识别视频候选所使用的动作版本、展示当前生效动作规划,并完成安全的人工修订流程。以下内容供后端实施与接口评审使用;标记为“建议新增”的路径和字段尚未开放,最终命名由后端确认。所有路径均以 /api 为前缀,成功响应沿用 { data: ... }。
视频质量状态与候选版本字段
现有 GET /storyboard-shots/:shotId/videos/quality-status(含 ?detail=true)没有读取持久化的 qualityTerminalStatus=stale_motion_plan。旧版本候选停止处理后,查询仍可能返回 validating 或 repairing。项目任务聚合结果已经提供 staleMotionPlan 和 settled[shotId].status,但不能替代逐候选状态。
建议在质量查询的每个 chain 项补充以下字段,并在视频列表、主视频和刷新接口使用的 VideoAssetDto 中提供同一份候选版本摘要,使普通候选也可判断是否过期。
| 建议字段 | 类型 | 用途 |
|---|---|---|
motionPlanRevisionId |
string | null |
此视频生成时绑定的动作修订 ID;历史 AI 快照为 null |
currentMotionPlanRevisionId |
string | null |
此镜头当前生效的人工动作修订 ID |
motionPlanStale |
boolean |
后端根据绑定与当前版本判断,前端不解析内部快照 |
qualityTerminalStatus |
string | null |
暴露已持久化的质量终态,至少支持 stale_motion_plan;其余终态以实际持久化能力为准 |
staleReason |
string | null |
可直接展示的过期原因 |
canValidate、canRepair、canSetPrimary |
boolean |
后端依据版本、资产完成状态和质量证据计算的操作权限 |
顶层 status 增加 stale_motion_plan;最新候选已终止时优先返回此状态,不继续显示校验或修复中。保留历史 validationPassed 和问题证据,同时明确历史通过不能证明版本仍有效。逐候选字段必须覆盖整条链,不能只判断最新视频或当前主视频。
版本字段与终态保持各自含义:即使后来切回同一版本,曾因过期而终止的任务也不能隐式恢复。历史视频的绑定版本与当前版本均为 null 时,保持既有兼容规则,不一律判为过期。不要新增 ShotVideo.status 的 Provider 状态值来代替质量终态,也不要公开完整 rawJson。
建议在现有 readiness 的镜头项增加 primaryVideoStaleReasons: string[],为空数组表示没有原因。前端即可展示首帧、参考图、模型输入变体或动作版本变化的具体原因;当前仅有 primaryVideoStale 布尔值,只能展示概括说明。
人工动作规划的查询与修订接口
现有 POST /storyboard-shots/:shotId/motion-plan/revisions/preview 请求为 { motionPlan },时长从正式镜头读取。返回结构问题、时间轴与动作密度预警及内容指纹;requiresStartStateValidation=true、canActivate=false。结构合法不代表可直接激活。当前尚无公开的修订保存、历史查询与激活接口。
现有 GET /storyboard-shots/:shotId/motion-plan/preview 仍读取 rawJson.motionPlan。建议改为优先解析当前生效修订,沿用既有时间轴字段,同时增加 source: 'ai_original' | 'manual'、activeRevisionId: string | null、motionPlanFingerprint: string | null。仅在没有人工生效版本时读取历史 AI 快照;版本记录损坏或归属错误应明确报错,不静默回退。
| 建议新增接口 | 请求 | 返回核心字段 |
|---|---|---|
GET /storyboard-shots/:shotId/motion-plan/revisions |
无请求体 | shotId、originalRevisionId、activeRevisionId、revisions;未初始化的版本 ID 可为 null |
POST /storyboard-shots/:shotId/motion-plan/revisions |
motionPlan、parentRevisionId、reason |
新建修订;保存不激活,由服务端确定 source=manual、镜头时长和指纹 |
POST /storyboard-shots/:shotId/motion-plan/revisions/:revisionId/start-state-validation/start |
目标主首帧 ID及预期生效版本 ID | executionId、status;复用持久化任务查询,明确此操作调用模型,供前端确认费用 |
PUT /storyboard-shots/:shotId/motion-plan/revisions/:revisionId/active |
`expectedRevisionId: string | null`、有效的起点校验任务 ID |
修订记录建议包含 revisionId、shotId、source、parentRevisionId、reason、motionPlan、durationSeconds、fingerprint、createdAt、isActive。motionPlan 沿用 MotionPlanOutputSchema 的完整 beats 和 globalMotionConstraints,不另造简化编辑结构。
起点校验任务路径为建议方案,后端也可采用同等能力的现有任务接口。必须明确返回校验结论及其绑定的 revisionId、指纹、主首帧 ID,且激活前检查这些输入仍有效。预检查不调用模型;正式视觉校验的费用、模型参数和结果查询契约需要一并确认。现实性等其他激活门禁应由后端定义,不能由前端用预检查的 valid 推断。
保存、校验与激活均检查镜头和版本归属。激活在事务内执行版本并发检查,使旧视频提示词失效,并保留原始 AI 快照与所有历史候选。并发冲突建议返回 HTTP 409 及可识别错误码,附当前生效版本 ID,前端刷新后由用户重新确认。
手动设为主视频的版本检查
现有 PUT /storyboard-shots/:shotId/videos/:videoId/primary 经 videoAssetService.setPrimary 调用旧的 shotVideoRepository.setPrimary,尚未复用自动晋升的版本检查。仅禁用前端按钮不能防止页面打开后版本变化。
建议此接口在同一事务内重新读取镜头当前动作版本、候选绑定版本、持久化质量证据及终止事实,确认候选已完成、属于该镜头且允许晋升后再切换主视频。过期候选或已停止的质量候选必须拒绝;失败时不修改现有主视频。
请求可增加 expectedMotionPlanRevisionId: string | null,用于发现用户确认期间的版本变化;无论客户端是否提交,服务端都必须比较候选绑定版本和镜头当前版本。成功响应沿用视频 DTO,并包含上文的版本摘要。
建议错误返回 HTTP 409,提供可识别的 code(例如 MOTION_PLAN_STALE)、message、shotId、videoId、motionPlanRevisionId、currentMotionPlanRevisionId。错误包装沿用项目约定;前端据此撤销本次会话的通过资格、关闭切换确认并刷新资产。
联调验收
- 候选生成期间切换动作版本后,质量任务停止;任务汇总与逐候选状态一致,刷新页面后仍显示版本过期。
- 同一镜头包含新旧版本候选时,各候选独立显示版本与操作权限,历史通过不会使旧候选可晋升。
- 手动设主与动作版本切换并发时,旧候选不能替换当前主视频;拒绝请求不改变主视频。
- 动作预览、提示词生成、视频生成和校验使用同一生效版本,原始 AI 规划始终可追溯。
- 修订保存、起点校验与激活独立;结构合法但未经有效视觉校验的修订不能激活。
- 无人工修订的历史镜头正常读取和生产;旧任务缺少
staleMotionPlan时前端按零展示。
实现核对入口:后端 video-quality-status.service.ts、video-quality-execution.service.ts、motion-plan-detail-preview.service.ts、motion-plan-revision-preview.service.ts、motion-plan-revision.repository.ts、video-asset.service.ts、shot-video.repository.ts 和 storyboard.routes.ts、video.routes.ts。