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

16 KiB
Raw Blame History

接口数据同步说明

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。真实后端读取及免费预检查不调用模型;保存、收费视觉校验、激活、版本冲突、首帧换图和草稿修改的流程使用隔离模拟场景验证,不写入业务数据或触发真实付费任务。