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

接口数据同步说明

核对日期：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 测试代替浏览器视觉验收或真实后端联调。