Files
short-drama-agent-front/docs/api-contract-sync.md
T

120 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 接口数据同步说明
## 2026-10-17 候选拆解、质量规则与阶段续跑
依据同级后端 `dev@dc884f0f` 的正式路由、候选提交服务、质量策略 schema、人工修订服务与 Production Prepare 节点核对。本轮在前端项目根目录 `dev` 适配,保留工作区原有页面改动。
- 拆解启动默认显式传 `candidateOnly: true`;已有结果时使用候选模式。分组、模块、项目、剧本正文或生成模式变化都会撤销旧预览,启动与正式替换分开确认。
- 新增 `commit-candidate` 入口,只发送 `{ confirmed: true }`。资格读取最新原始 Checkpoint,不从历史回退结果拼接;确认后再读取当前版本,变化时停止提交。后端继续在事务内校验最新候选、剧本正文指纹、审核状态和下游资产,不接受客户端上传主体或分镜数据。
- 项目配置新增“质量规则”分类,对接 `quality-policy` GET/PUT。完整保留物理模式、三项动作许可、自定义规则和针对主体/资源的精确例外;切换表现方式不会自动放宽动作权限。保存与生成模型配置使用各自的接口和按钮。
- 拆解设置新增 `storyboard-quality-repair-plan`、`storyboard-quality-repair-candidates` 与 `storyboard-quality-repair`。人工编辑完整必需动作、阶段时长、手部证据及身体/道具资源证据;候选来源发送真实镜头指纹和 Checkpoint ID。修改草稿撤销旧确认,版本变化要求重新读取。保存仅产生新快照,之后仍需恢复拆解及候选正式提交,不显示为已入库。
- 指定 Production 续跑阶段的预检同步后端门禁:所有续跑均要求角色身份确认;首帧及视频提示词续跑要求主体参考图全部有效;视频提示词续跑额外要求全部已有有效首帧。`planned`/可生成不等同于已有有效资产,不影响默认从头运行时补齐上游的行为。
- 页面沿用现有公共弹窗、模块留白和固定底栏,动作与资源编辑字段提供可见标签;393px 窄屏按单列显示。
验证:本地 Chrome 使用 `localhost:4312` 读取真实后端 `localhost:3412`,完成候选分组预览、费用确认取消、真实修复清单空结果、多行质量规则和精确例外必填验证;在 393px 视口检查表单、正文滚动和底栏。已有项目没有待提交候选或质量阻断镜头,候选版本变化拦截、完整证据编辑、无效动作引用阻断和人工修订提交使用临时隔离验收页验证;该页面已删除,不向真实后端写入,不触发模型生成。
代码校验:lint、format:check、typecheck、56 个测试文件/429 项测试、生产构建和差异检查均通过。使用本机已安装 pnpm 的 `--pm-on-fail=ignore` 参数执行脚本,避免自动下载项目声明的另一版包管理器;没有修改依赖或锁文件。
核对日期:2026-09-10。依据同级后端仓库 `short-drama-agent` 的 `HEAD=f0321c2`、`src/api/routes` 及实际资产 DTO/service 实现。本轮仅修改前端,沿用已完成页面和正式路由。
| 接口范围 | 精简后的公开数据 | 前端处理 |
| --- | --- | --- |
| 项目列表/详情 | 项目业务字段、characters、world、episodes;不含 reviews、tasks | 删除旧类型依赖;审核读取共享 checkpoint 的明确 reviewPassed,不伪造审核记录;生产预检从每条工作流最新 checkpoint 检查运行状态 |
| 视觉风格及参考图 | 风格保留可编辑 Prompt、hardConstraints 和 images;图片去除生成 Prompt | 保留编辑、锁定、图片登记和启停;移除图片内部提示词展示 |
| 主体身份查询/保存/生成 | id、subjectId、description、generationPrompt、isLocked、时间 | 图片继续通过独立 GET 查询,不从身份对象读取 images |
| 身份图片查询/生成/切母版 | 明确 isAnchor,不含 enabled、prompt、rawJson | 母版识别和切换结果校验统一使用 isAnchor;辅助视角仍不可设母版 |
| 角色选角确认 | identityId、subjectId、isLocked、anchor | 验证主体、身份、图片归属和母版标记,不再访问嵌套 identity |
| 形态图库/图片/主图 | identity.anchorImageId;图片仅含资产字段 | 正常预览、生成和切主图;移除依赖历史 rawJson 的身份过期推断及批量重生,保留下游 readiness 过期定位 |
| 形态正式 Prompt | 正式形态业务字段和时间,不含 subject、images 关联 | 单独声明回执类型;生成后重读图库,避免将单体回执当作图库记录 |
| 视频 Prompt | shotId、status、videoPrompt、negativePrompt、updatedAt | 两个页面均按 shotId 校验回执;保留正文展示与导出 |
| 首帧资产 | source、状态、图片、主图标记、模型与时间;无内部 Prompt/任务信息 | 保留候选和主图;source=provider_variant 的模型输入变体不可设业务主首帧 |
| 视频资产/单任务刷新 | 状态、地址、时长、isPrimary、模型和时间;无 rawJson/Provider Task/Prompt | 播放与状态使用公开字段;未知质量不显示通过或自动校验中 |
| 视频就绪/项目状态 | stale_prompt、provider_input_recovery;公开失败分类、retryable 和输入恢复状态 | 补齐类型和中文原因,显示不可普通重试提示;不解析内部失败快照 |
| 视频生成规格 | 业务 keyframe 和实际 providerInputKeyframe | 类型区分两种用途,规格面板展示实际输入 ID;尺寸允许后端 null |
| 失败视频重试 | totalFailed、retryable、skipped、retried、failed、failures | 显示可重试和跳过数,保留部分失败,不将 HTTP 成功当作全部重试成功 |
| 拆解、导演设计、即时状态、质量 POST、串联生产、诊断 | 已核对现有页面使用的正式路由与返回业务切片 | 保留原入口、参数、费用确认与失败处理;不增加测试/探针生成入口 |
视频校验的新增运动、空间交互、道具结构及连接检查回执也已同步;专项未执行不显示通过,完整证据随结果导出。视频校验费用提示按一次请求可能调用多个模型说明。
## 质量数据边界
公开视频 DTO 不再带质量候选类型、历史校验和修复次数。后端自动质量链仍负责通过后晋升,前端以刷新后的 `isPrimary` 为准。普通手动设主入口要求本会话对此资产收到 PASS;修复要求本会话收到 FAIL。回执按项目、镜头、资产隔离,切页仍可查看,刷新浏览器后不伪造历史。重新校验会清除旧通过资格;失败的修复请求保留其依据的失败校验。次数上限由后端检查,错误原样呈现,不自动重试。
项目详情不再提供内部任务列表。公开 checkpoint 只能证明已记录工作流的状态,不能证明所有外部生成任务均已停止;保留现有的资产状态检查和操作确认。
## 回归验证范围
测试使用不包含旧内部字段的公开 DTO,覆盖页面加载、身份保存/选角、图片主图、Prompt 正式 ID、质量会话隔离、输入变体禁用、失败重试和缺失历史不误报过期。全部 API 使用模拟响应,不触发真实模型。此次不以自动化 DOM 测试代替浏览器视觉验收或真实后端联调。
## 2026-09-14 增量同步
核对后端 dev `c2142681b16798ae5ff865a2eb648a9f45221af2` 的路由、Production Plan/Status/State、主体生图及视频输入编译实现。历史文档中的 `f0321c2` 已无法通过 GitHub compare 解析,本轮以当前源码为准。
- 接入制作执行计划和真实制作状态,删除“串联不会生成首帧”和必须先有全部主图的旧限制。
- 补齐首帧质量回执、视频阻塞/进行中、dispatchCompleted;Provider 启动参数保持空对象。
- 人工阻塞与请求错误分开,允许其余 ready 主体部分成功;提交前重新预检,项目归属/活动任务校验保留。
- 批量生图默认包含过期主图,但新候选不会自动替换已有主图,页面明确提醒确认主图。
- 指定模型最终输入支持只读检查授权素材与实际首帧,通用规格改为明确未指定模型的展示。授权资产绑定管理和实验探针不在本轮新增范围。
- 浅色主画布统一白色,输入框使用浅灰,Tab 导航、辅助区和图库使用统一主题变量,首屏 theme-color 与应用一致。深色视频播放背景保留。
验证使用模拟 API,不调用真实生成模型。浏览器无法访问当前本地预览地址,尚未完成浏览器截图验收或真实后端联调。
## 2026-09-21 项目资产接口
- `POST /projects/:projectId/assets` 使用 multipart 的 `file`、`name`、`category`,浏览器负责生成 boundary,前端不手工设置 `Content-Type`。
- GET/PUT/DELETE 项目资产接口全部使用正式项目 ID 与资产 ID;编辑只修改名称和分类,不替换物理文件。
- 素材公开字段包含 `publicUrl`、类型、MIME、扩展名、大小、分类、元数据和时间;页面只读取 `metadata.originalName` 作为辅助搜索,不依赖内部存储路径。
- 视觉风格新增参考图可发送 `projectAssetId`,后端从所属项目素材解析 `imageUrl`;外部 `imageUrl` 入口继续兼容。资产关联关系不在公开风格图 DTO 中推断。
- 删除仍由后端执行引用保护;前端不先删风格记录,也不将失败响应显示为已删除。
## 2026-09-22 增量同步
- 新增形态图和镜头首帧的 POST 预览接口;请求体默认 `{}`,只读取后端当前生成配置与参考图规划,不产生模型任务。
- 首帧预览按 `referencePlan.selected`/`omitted` 展示 Provider 上限后的真实输入;不再从通用 `keyframe-spec` 推断最终选图。
- 形态提示词、形态图片及主体身份文本批处理均可发送可选 `module`;省略时保持全项目行为。
- 场景/道具身份母版使用 `/projects/:projectId/subject-identities/anchors/generate`,请求包含 `module`、`limit`、`concurrency`;成功项已由后端设为 Anchor 并锁定,不再由前端逐项补 PUT。
## 2026-10-10 串联生产增量同步
核对后端本地与远端 `dev@8acc22db66605b2094098eb3f25b4d1de0ef4a69`。本轮调整已有生产流程:
- `POST /projects/:projectId/production/start` 新增 `videoLimit` 和 `videoGenerationOptions`。高级串联生产默认视频候选最多一镜,限制值必须为正整数;默认安全模式仍在视频提示词阶段停止。
- 项目 `creative-profile.videoOptions` 被复制到本轮启动快照。确认后重新读取配置,视频参数变化也会撤销旧预检与确认,避免启动未经确认的参数。计划接口仍仅解析图片参数及图片/视频供应方,视频参数和数量上限由启动接口实际消费,不将计划表中的全项目计数描述为本批上限。
- 补齐首帧就绪项 `primaryQualityStatus` 和视频就绪汇总 `failedKeyframeQuality`。缺省状态不推断通过;已有 `failed_keyframe_quality` 问题显示沿用后端真实原因。
- 新增首帧编辑、候选质量恢复和人工空间目标绑定属于独立操作入口,本轮未新增这些页面功能。已有通用 JSON 规格展示和导出保留后端新增数据,不人工编造空间目标。
验证:`pnpm check`(45 个测试文件、357 项测试)及 `pnpm build` 通过;本地 Chrome 的 `localhost:4312` 读取真实后端 `localhost:3412`,生产预检成功,视频候选上限可编辑,修改后旧预检失效且启动禁用。真实生产状态返回 passed/failed 主首帧质量标记;当前项目视频参数来自实际配置。未启动图片、视频或视觉校验模型任务。测试输出存在 localhost:3000 连接拒绝日志,但全部测试通过;不据此宣称付费生产端到端验证。
## 2026-10-12 工作区与长任务反馈同步
后端契约基线:`dev@45c8678971f71210764ef816c4a712b1b302f429`;前端起点:`dev@83482a70c50d85d6481f41e69f4b53dfaa3f986a`。以路由与实际服务返回为准。
- 分镜和生产工作区接入单镜头 `motion-plan/preview`;项目级 `storyboard/motion-plan-duration-audit` 按需读取,并按正式镜头 ID 定位。时间轴结构预警与动作密度预警独立计数;实时审计、历史生成预警和人工建议分别展示,缺失历史记录不推断通过。预警不阻断生产,不自动调整时长。
- 接入 `spatial-target-bindings` GET/PUT 和 `gaze-readability/preview`,人工编辑支持方向性注视/精确目标、画内外、景深、区域及唯一性。完整替换写入仅包含允许的业务字段,不提交后端 evidence;空列表撤销人工覆盖需确认。
- 首帧主图和历史候选增加 `edit/preview` 与 `edit` 入口。参数变化撤销预览和费用确认;提交前重新核对源图及主图状态。主图编辑自动校验并在通过后尝试晋升;历史候选仅生成下一代候选,不能显示质量通过。编辑的 202 句柄复用 `keyframe-quality` 持久化观察,完成回执与批量质量统计分开。
- 分镜工具通过 GET `video-prompt` 自动读取已保存正文,只有用户明确生成才 POST。首帧手动晋升前重新读取 `quality-review`,认可当前持久化 passed/manual_accepted,移除只认可本会话结果的过期限制。视频手动晋升仍保留已有独立守卫。
- 临时成功、失败、警告使用同一 NMessage;同一时间的重复查询错误去重。项目操作过程由按钮 loading、操作入口旋转图标、资产状态及真实后台阶段反馈,不再显示固定全局 loading 消息。后台终态只通知一次,旧完成记录不重放。
- 常驻彩色提示框改为紧凑业务状态与恢复入口;重复阶段成功说明移除。批量部分失败根据后端真实统计显示 warning,成功的只读刷新不再额外提示成功。
- 页面模块和提示说明沿用全局间距;新时间轴、目标表单与编辑面板在窄屏自动单列。历史错误、业务预警和操作错误分别保留正确的查看或恢复入口。
验证不启动真实生图、视频或视觉校验。当前浏览器无法访问本地 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。真实后端读取及免费预检查不调用模型;保存、收费视觉校验、激活、版本冲突、首帧换图和草稿修改的流程使用隔离模拟场景验证,不写入业务数据或触发真实付费任务。