feat(short-drama-agent-front): 接入人工动作修订与视频版本权限

This commit is contained in:
GJ committed 2026-10-14 13:44:02 +08:00
1 parent 7a60db3ced
commit fa76165960
38 files changed
+2003 -158

No files matched your search

+13
View File
@@ -89,3 +89,16 @@
验证不启动真实生图、视频或视觉校验。当前浏览器无法访问本地 localhost 服务,浏览器视觉验收与真实后端联调仍待在可访问的开发环境完成。
本轮校验:`pnpm check`(49 个文件、393 项测试)、`pnpm build` 和差异检查通过。新增回归覆盖切镜迟到响应、历史审计缺失、编辑预览失效、主图身份变化及后台候选编辑句柄。测试输出仍有已有 localhost:3000 连接拒绝日志;不据此宣称真实后端或付费模型联调完成。
## 2026-10-14 动作修订与候选权限同步
依据同级后端当前未提交 dev 的 `docs/api/public/motion-plan-revisions.md` 及正式路由、服务返回;不依赖旧建议文档推断契约。
- 视频 DTO 和质量链共用八个版本与权限字段。候选独立控制校验、修复与设主;过期终态优先于历史通过,两个空版本 ID 不自行判为过期。主视频优先显示 readiness 的具体原因。运行任务的过期计数与逐镜终态读取 metadata,完成后读取 result。
- 分镜动作面板和生产动作弹窗共用完整修订编辑器。编辑、免费预检查、保存、确认模型费用、启动视觉任务、读取任务、激活均为独立步骤;阶段、整体约束、主体引用和收尾等字段完整传递。
- 保存显式提交父版本(首次可为 null);校验提交当前主首帧 ID 和当前生效指针,使用服务端视觉模型,不传请求级模型选择参数;激活提交真实视觉任务 ID 和预期生效指针。
- 激活资格要求任务完成、通过且未失效,并核对镜头、修订、内容指纹、主首帧 ID 与图片地址、生效指针。修改草稿、保存新修订、主首帧或生效指针变化后撤销旧资格和费用确认。刷新后可恢复同镜头持久化任务;关闭弹窗或切换标签不重复启动任务。
- 激活后刷新版本、动作预览、视频资产、质量记录和项目 readiness,提示重新生成视频提示词,不自动发起生成。同步 409 保留顶层 code 与独立 details,撤销候选会话资格并刷新权限;后台 failed 任务独立展示 error 和 result.issues。
浏览器验收使用本地 Chrome 和 localhost。真实后端读取及免费预检查不调用模型;保存、收费视觉校验、激活、版本冲突、首帧换图和草稿修改的流程使用隔离模拟场景验证,不写入业务数据或触发真实付费任务。
+66
View File
@@ -0,0 +1,66 @@
# 动作规划版本与视频质量接口补充建议归档
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 | `shotId`、`activeRevisionId`、`motionPlanFingerprint`、`changed`、`videoPromptStale` |
修订记录建议包含 `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`。