# 接口数据同步说明

核对日期：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，不调用真实生成模型。浏览器无法访问当前本地预览地址，尚未完成浏览器截图验收或真实后端联调。