Files
short-drama-agent-front/docs/api-contract-sync.md
T
GouJ 7a60db3ced feat: 同步动作与首帧编辑能力并统一工作区反馈
接入动作时间轴、密度审计、人工视线目标和后台首帧编辑;独立读取已保存提示词,并在首帧晋升前重新核对持久化质量状态。
统一 NMessage 结果反馈、局部 loading 和业务说明间距,保留真实长任务进度与部分失败语义。
验证:pnpm check(49 个文件、393 项测试)、pnpm build;当前环境无法完成 localhost 浏览器验收及真实后端联调。
2026-10-12 20:05:03 +08:00

92 lines
12 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-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 连接拒绝日志;不据此宣称真实后端或付费模型联调完成。