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