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

40 KiB
Raw Blame History

接口数据同步说明

2026-11-01 图片预览、质量门禁与派生任务

本次只接入后端根目录 dev 的正式 /api 路由,依据 subject-form.routes.ts、subject-identity.routes.ts、production.routes.ts、storyboard.routes.ts 及相应 Service 核对。未接入 3413 隔离验收服务、脚本、测试专用路由或测试页面;测试夹具只用于 Vitest。

  • 身份图、独立选角候选和形态图共用只读预览确认。提交携带 expectedPreviewFingerprint;选角预览固定 viewType=primary,useAnchorReference=false,实际候选请求沿用正式选角接口。修改目标、参数或重新打开会清除确认,迟到响应不回填。只有 409 + IMAGE_PREVIEW_STALE 自动重读预览,之后仍须人工重新确认;不会自动重复生图。保留 Identity 的 {executionId,image} 与 Form/Casting 的直接图片回执区别。
  • 图库区分生成完成、最近审核与已采纳状态。新增正式 Form POST images/:imageId/validate 与显式有限预算 POST images/generate-quality,默认额外生成次数为 0。主图和母版确认披露可能发生的视觉审核费用,成功后只读刷新;质量失败、证据过期或请求冲突不乐观替换旧图。GET 图库仅查询,不触发模型或主图变更。
  • 身份与形态共用质量证据展示,按 requirementId/quantityId 关联原文、明确数量与实际观察;缺失、重复、不可观察及数量冲突不显示通过。原文与请求字段保持不变,内部编号收在高级详情。当前会话审核结果不冒充服务端长期有效的 Readiness。
  • 图片页新增 POST production/plan {stage:'subjectImages'} 只读检查,展示道具规格、已确认母版依赖顺序及质量问题入口。需准备资料时,经费用确认分别调用既有 generation-prompt 或 prop-structure-spec/generate 正式文字入口,不自动串联后续生图。未添加诊断脚本、测试路由或批量历史恢复入口。
  • 导演设计与画面状态任务增加服务端发现;刷新后恢复观察。failed 终态保留逐集部分成功、失败及 manualReviewRequired,不显示全部成功。订阅断线只重连/查询,离开页面关闭连接,不重提交生成。正式分镜审核和派生资产覆盖分别展示。
  • 复杂生图和图库处理复用 AppDrawer,固定标题与底栏,正文独立滚动,深浅主题复用现有变量。未提交或推送代码。

验证:类型检查、改动范围 Oxlint / Vue ESLint、全量 Vitest 和 Vite 构建;Chrome 复用 localhost:4312 标签,核对真实预览、参数变更清除确认、缺规格阻断、图库只读与费用确认入口、桌面和手机布局、深浅主题及固定底栏。没有执行真实付费生成/视觉审核、候选采纳或正式结果覆盖;这些写操作的成功/失败边界通过无费用自动化替身验证。

2026-10-28 剧本审核人工确认、延期验证与改写预检

按同级后端 dev@b26aa94e 的正式审核路由、人工确认事务、质量问题 Schema 和改写预检接入,前端仅修改根目录 dev。

  • “审核记录”按需读取 GET /projects/:id/reviews/latest、reviews/confirm-issues/preview 与现有 resume-rewrite/preview。最新审核和预检必须属于同项目、同审核编号;预检失败保留只读审核,异常结构、来源过期、活动任务及剩余列表缺失均不开放确认。只读查询可关闭、取消,切项目或卸载后的旧响应不回填。
  • 待审核项目首次进入直接定位“审核记录”;失败项目保留当前未通过审核时也定位此处。仅引导阅读,不自动弹出写入确认或启动改写;用户切换内容后,刷新不抢回标签。当前有效改写预检存在剧集、角色或世界观改写范围时提示先检查改写,否则引导人工核对。推荐延期仅在对应单选旁标注“建议”,仍默认保留待处理,不能把人工核对自动转换为接受。
  • 两种处理入口独立按实际内容显示:剩余待确认问题或不确定项为空时隐藏“人工确认”;真实改写预检的剧集、角色、世界观均不需改写时隐藏“改写预检”。两种操作并存时都保留;审核通过或预检缺失时不保留空入口。“刷新审核”始终保留。不能只按 confirmedRewriteEpisodes 判断改写是否存在;角色或世界观单独改写也必须正常显示。改写读取沿用公共校验方法,保存记录与当前审核预检不一致时隐藏旧范围并提示刷新。
  • 当前有效预检只强调一个主按钮:改写已就绪时突出“改写预检”,否则待人工处理时突出“人工确认”;刷新、读取失败、来源失效、活动任务及审核通过时均不强调处理入口。配色和入口显示不代替服务端操作权限或确认流程。
  • “人工确认”复用全屏 AppDrawer,按集分组核对错误、警告及不确定项,并提供当前正式正文和人工补充证据。人工补充仅提交已明确核对的 Error、逐字原文、真实集号及说明;首次打开和增加空行不立即报错。处理建议展示推荐原因、全部候选剧集及置信度;默认全部保留待处理,用户明确选择后才展开延期字段。低置信度或要求人工选集时集号留空,候选优先但可选择其它正式剧集;阶段和预填验证标准可编辑,延期不等于后续核验通过。
  • 完整原文桌面默认展开,手机按需展开;从问题点击原文入口会选择该集并定位核对区。窄屏操作保留完整名称并自然换行,长内容仅正文滚动,底栏保持可见。
  • POST reviews/confirm-issues 始终发送 confirmed: true、当前 reviewId 和 issueIndexes 数组;三种选择分别使用原始待确认列表或原始 uncertainty 数组索引,过滤、排序和多轮处理不重编号。提交前重新 GET 核对审核、保存记录、剩余项和正式正文;建议按当前剩余项生成,按完整原文映射回原始审核索引。接受与延期互斥,延期必须填写真实集号、拆解/分镜阶段与非空标准;请求使用 deferredUncertainties。来源变化后旧选择保留为只读草稿,禁止套用旧索引;同来源提交失败保留当前输入,409 只重读,不自动重试写入。
  • 确认成功后读取项目详情、当前保存记录、阶段状态和最新审核。尚未生成新 Review 时,已保存裁决优先读取本次预检绑定的保存记录;剩余问题仍可继续处理。只按服务端 finalized 表达本次审核是否完成,不按 remainingBlockers 推断通过,不自动调用改写模型。审核结果更新时清除旧人工回执;已完成审核仍能只读核对正式正文,旧任务的失败或待修订回执标为历史执行记录。
  • 审核页和创作任务弹窗共用改写范围确认入口。GET /projects/:id/resume-rewrite/preview 展示真实集数及角色/世界观范围;未就绪只读说明原因。明确确认费用后再次预检,保存记录或范围变化即撤销旧确认;只有同一有效范围才 POST resume-rewrite,请求体包含 confirmed: true。保留项目活动锁与真实任务句柄,网络不确定不自动重复提交。
  • 人工处理后可主动查看改写范围,先等待抽屉离场和焦点释放再打开预检。普通读取不锁定关闭,实际写入期间防止重复操作。运行、失败、完成和未知状态分别展示,不把历史通过或执行结束当作当前制作许可。

接口及页面测试隔离模型与数据库写入。Chrome 使用 localhost 验证,确认及改写启动的浏览器验收使用 /tmp 内存样例服务,不对正式审核发送裁决,不触发真实付费改写。未修改后端;Git 交付按用户明确要求提交并推送至 dev。

验证:82 个测试文件、626 项测试通过;静态检查、格式检查、类型检查及生产构建通过。复用本地 Chrome,桌面只读核对 cmvrk799a0000k6nd3udc1wow 的三项真实建议及原文,均保持待处理;隔离样例验证部分延期保存、原始索引请求、提交后重新读取审核与项目阶段、未选剧集阻止提交,以及 390×600 视口的长内容滚动与固定底栏。另验证首次刷新自动进入审核记录、切换世界观后只读刷新仍保留当前标签、手机端引导与入口换行,以及建议标签不默认接受任何问题。入口显隐覆盖仅人工确认、仅改写、两者并存、无可处理事项、审核通过及预检读取失败;额外验证世界观单独改写无集号仍保留入口,保存记录不一致时隐藏旧范围。旧 Review、活动任务、失败保留草稿及改写二次预检由自动化回归覆盖。开发验收日志出现两次 ResizeObserver 布局提示,来源尚未定位,可见交互正常;未为此修改无关公共布局。验收后恢复真实项目审核记录并停止隔离服务。

2026-10-28 Story Plan 创作流程适配

核对同级后端 dev@c6ad973c 的项目创建路由、创作 Graph、节点保存中间件、恢复服务和任务订阅;只修改前端根目录 dev。

  • 正式顺序为故事规划 → 分集剧本 → 角色设定 → 世界观 → 动作记录整理 → 审核/改写。页面复用原阶段条与任务面板,动作记录整理显示在任务当前阶段,不新增独立业务步骤。
  • POST /projects 请求和 202 回执未变。继续发送标题、主题、风格及原有时长预算,复用全部创建输入组件与默认值,只更新顺序说明。
  • 不存在 Story Plan 独立查询接口。读取现有项目详情、GET /projects/:id/checkpoints、项目级 workflow-executions/latest|events 和按任务编号查询接口;规划是否已保存仅来自最新创作记录的 state.storyPlan,不从后续节点顺序推断、不回退历史规划、不在页面复制规划校验。
  • 项目布局开启创作任务发现;页面在任务编号、节点或执行状态变化后重读项目与保存记录。SSE 使用完整持久化任务,不按旧节点序号过滤。刷新、直接进入及服务端另行启动均复用原发现能力。
  • 新执行开始前的旧审核、角色和世界观不用于完成当前节点。resume-generation 仍可沿用最新保存规划,但派生设定与审核等待本次保存记录确认。完整剧集的派生阶段失败也可恢复生成;有当前审核结论时停止生成恢复,明确未通过且有审核来源才开放原有改写恢复。连续剧集前缀、费用确认及项目活动锁保留。
  • 任务执行完成和审核通过分别展示。任务 result.projectStatus=need_review 使用待修订样式,缺少结论保持待确认;不会仅因 HTTP 成功或任务结束标绿。
  • 创作页只保留阶段、摘要与入口,详细状态和恢复操作放入公共 AppDialog。弹窗按任务状态、剧集进度与恢复提示分组,编号放在默认收起的高级详情;固定底栏集中关闭、只读刷新及原有费用确认。关闭弹窗不停止任务观察,状态读取失败也可以关闭并重读。
  • 注意事项复用 ContextNotice 的按需强调样式:项目主题的中性底面、图标与短标题突出待处理和恢复受限说明;普通信息继续以留白分组。明确失败或成功仅复用项目既有状态色,并进一步降低底面强度;深浅主题自动同步,不把待审或结果未知标为绿色成功。
  • 当前后端失败回执把 stage 统一改成 failed,恢复生成也只有整体 resumeGeneration 阶段,未持久化逐节点失败状态。页面显示任务失败与明确保存的结果,无法确认的具体节点保持待确认;缺少规划时没有独立规划恢复入口,提示新建重试,不虚构 API 或猜测失败节点。

浏览器验收使用已有本地 Chrome 标签页与 localhost:4312 隔离样例接口;样例与临时服务位于 /tmp,不进入产品代码,不连接真实生成服务。真实模型、正式数据写入及付费端到端生成不在本次验收范围。

2026-10-19 导航修复复核与配置冲突同步

后端基线 dev@6a6fd52d,前端根目录 dev;保留已有未提交工作,不修改后端、不提交或推送。

  • Chrome 真实读取“掩耳盗铃”:导航 script/breakdown/storyboard.ready=true,visualStyle/identity/subjectAssets.ready=false;制作入口 ready=true、storyboardValid=true,正式镜头/镜头设计/画面状态均为 61。视觉风格入口已解锁,后续入口按实际准备情况受限;原导航不一致已解决,不需要前端覆盖阶段接口。
  • 计划继续 POST,只发送后端解析的 imageProvider/imageGenerationOptions/videoProvider。执行范围及视频生成参数保留在最终启动快照和 POST start 中,不能把未解析的参数描述成已通过计划预检。
  • 沿用已有配置阻断联合类型与空阶段保护;补充明确的缺配置状态及“前往项目配置”,复用项目标题栏已有全屏抽屉,保存后仍需重新检查,不自动创建配置或启动生成。
  • 配置 409 同时识别顶层 code 和真实 details.code。画幅需重新核对、活动任务、模型参数变更受限使用易懂中文和统一 NMessage,保留草稿、原始错误和已保存配置,不自动重试、清理素材或重新生成;成功保存也不再留下重复常驻提示。
  • 制作计划人工阻断数按独立准备问题说明,各阶段影响数量不能直接相加。模型目录、智能时长 specialValues、项目画布与参考图尺寸的独立关系保持既有实现,不按模型品牌硬编码或覆盖正式镜头时长。

本轮 70 个测试文件、541 项测试通过;静态检查、类型检查、生产构建及差异检查通过。沿用本会话既有约定,未执行格式化或格式检查。真实接口只读验证;缺配置、正常计划和配置冲突在本地 Chrome 临时隔离页面验证,所有请求在页面内模拟,不回退到真实网络。440×956 窄屏核对恢复入口换行和固定底栏;临时页面已删除,恢复真实项目桌面页面。

接口核对范围、改动文件及仍需后端处理的既有诊断列表问题见 frontend-contract-audit-2026-10-19.md。

2026-10-19 正式分镜审核与制作前准备

以同级后端 dev@82756627 的实际路由、Schema、事务及服务回执为准;先接功能,再调整诊断卡片布局;项目配置同步补图标。本轮保留此前未提交更新,只修改前端根目录 dev。

  • 项目顶部统一新增“制作前检查”,在后续页面尚未开放时也可操作:当前项目质量规则确认 → 历史正式分镜规则来源确认 → 正式问题修订 → 整体人工审核 → 镜头设计/画面状态补齐或更新 → 制作入口复检。
  • 对接正式质量复检 storyboard-quality-recheck、历史规则来源 storyboard-review-baseline/preview|confirm、整体审核 storyboard/quality-confirmation GET/POST 以及 production/entry-readiness。只读复检的 canConfirm=false 不代替显式审核;preflightEligible 也不独立放行。实际审核同时绑定项目、Checkpoint、规则修订/指纹及正式 Shot 数量/内容;确认前重读,变化后要求重新核对,不自动替用户确认新版本。
  • 正式动作读取、确定性关联建议、付费语义候选及保存使用 storyboard-shot-repair/preview/:shotId|candidate 与 storyboard-shot-repair。保存真实指纹、完整动作与阶段;已有手部和通用资源证据、持续对象及释放/交接字段保留。模型建议不等同于已保存;保存成功后仍需重新复检和整体审核。
  • 主体遗漏通过正式坐标 locate 定位;剧情段落主体与镜头主体分别使用其预览/确认接口及各自内容版本。段落写入不自动继续镜头写入,不用候选 Checkpoint 修复替代正式数据修订。
  • 旧手部诊断、建议与修订历史路径迁移到 action-resource 与 storyboard-shot-revision-history。列表优先展示 resourceAudit,同时保留旧 handAudit 的含义边界;正式修订历史与诊断历史均按需读取。诊断关闭动画完成后才打开正式修订抽屉。
  • 制作计划读取前先核对 entry-readiness,未满足时不再发 production/plan。覆盖率完整仍需逐集核对 staleCount;过期、缺失或未明确返回新旧版本状态都暂停进入计划。计划启动时沿用原有再次预检、参数变化撤销确认及任务互斥。
  • 制作计划区分 configuration.status=ready 与 blocked / CREATIVE_PROFILE_REQUIRED。配置缺失时显示保存项目配置的中文提示,既不读取空阶段/明细,也不允许启动;独立配置查询后发生变化的情况同样阻断。模型时长选项继续读取真实模型元数据,不硬编码智能时长默认值。
  • 镜头设计与画面状态页面接入当前整体审核,不能只凭已有数量启用生成;费用确认后再次核对审核来源。真实后台任务继续使用既有 WorkflowExecution,不自动重跑 Breakdown、不自动调用模型。
  • 诊断卡片定位、复查、修订与历史入口改为图标加中性独立底面的无边框按钮。窄屏只显示图标,保留完整名称与提示;保存和生成才使用绿色主操作。长表单固定底栏、移除操作使用图标,规则/原因校验不在打开时立即显示。

验证:69 个测试文件、529 项测试、静态检查、类型检查、生产构建及差异检查通过。按既有约定未执行格式化或格式检查。本地 Chrome 复用 localhost:4312,验证真实制作前检查与有效审核、只读正式动作编辑、桌面及 440×956 窄屏操作图标、无边框入口与固定底栏;最终恢复桌面页面。人工确认、修订写入及收费模型分支仅在隔离测试中验证,未改写真实项目或调用收费模型。

历史记录:本节验收时导航尚存在旧待审标记问题;后续已由后端 6a6fd52d 修复并重新核对,见本文件顶部记录及 backend-production-navigation-follow-up.md。

2026-10-18 质量规则确认与诊断更新

核对同级后端 dev@2b079bd1 的公开文档、正式路由、质量规则事务、诊断预检查、结果汇总、修订资格及恢复服务。本次只修改前端根目录 dev。

  • 质量规则 GET 保留服务端 revision/fingerprint/confirmed/confirmedRevision/confirmedAt;PUT 使用 { policy, expectedRevision };用户明确勾选后调用独立 Confirm。删除本地浏览器确认依据,跨浏览器已确认且规则未变时跳过规则表单,仍保留每次模型调用的费用确认。
  • 确认前及最终启动前重新读取同项目规则;实际启动携带 expectedRevision,零版本有效。取消、切换项目或预览、活动锁与迟到响应不能生成启动许可;真正保存或确认期间锁定关闭。服务返回版本冲突时不自动重试写入。
  • 全局规则保存与问题中的动作例外追加均重读最新规则,并携带其真实 revision;例外完整保留。普通保存不伪造明确确认。候选提交安全检查新增 qualityPolicyMatches,缺失或 false 均不放行。
  • 单镜头诊断预览接入正式 diagnosis-preflight/:shotId;费用确认后再次核对预检查和镜头摘要,来源、规则或内容改变时撤销启动。可复用的有效历史诊断不重复调用模型。
  • 动作诊断使用全屏 AppDrawer,正文独立滚动、固定灰色关闭按钮;版本过期、手部免费检查、证据覆盖率、全身动作疑点和 AI 待复查分别展示,不将“已修订”或局部无冲突描述为全部通过。未诊断长列表仍按需查看。
  • 指定镜头的诊断历史与修订资格按需读取,返回项目/镜头/诊断归属不一致时不展示为有效资格。没有提供当前完整动作规划时不从模型建议或旧保存记录构造可写表单;补充接口需求见 backend-diagnosis-follow-up.md。
  • 诊断任务的服务中断摘要直接展示可复用/待核查数量及费用未知提示,不自动重新提交;诊断执行结束不再使用素材生成成功文案或满格绿色进度条。

验证:66 个测试文件、516 项测试通过;类型检查、静态检查、生产构建及差异检查通过。沿用既有约定未运行格式化或格式检查。Chrome 复用已有 localhost:4312 标签页,对真实本地服务验证首次规则确认、取消保留预览、单镜头规则记录不完整时禁用启动、按需历史读取,以及 440×956 窄屏固定底栏;模型执行、规则保存/确认及修订写入只使用测试隔离验证,未对真实用户数据执行写请求或收费模型调用。界面恢复到桌面视口。

2026-10-17 拆解任务发现与过程展示

  • 项目布局通过 GET /projects/:projectId/workflow-executions/latest?workflowName=breakdown 发现服务端最新拆解任务,并通过同项目 workflow-executions/events 订阅任务变化。后端发起的新任务不再依赖当前浏览器保存过启动回执;没有任务时明确返回 null。
  • 拆解页页头、设置弹窗和活动锁共用实际任务记录。运行期间隐藏“查看诊断”和节拍/镜头诊断按钮,禁用恢复、候选提交与质量修订。结束后读取最新结果,按真实终态恢复入口;切换项目和迟到消息不覆盖当前项目,终态不会被旧 running 消息重新激活。
  • 后端只读观察视图使用同次运行时间窗口内的阶段快照补充阶段和进度。metadata.progressUnit 明确区分抽取任务与分镜剧集;状态仍以持久化任务为准,不把抽取 3/3 当作整个拆解完成。新任务尚无快照时标注“上次结果”,未知总量保持未知。
  • 任务执行结束但 storyboardShotValidation.valid=false 时显示校验未通过,保留候选提交限制。发现失败提供重读入口,页面不定时刷新全量项目或完整 Checkpoint;只观察任务状态,终态时刷新业务结果。
  • 本地 Chrome 读取“掩耳盗铃”的真实任务与校验结果;在临时隔离页面验证后台启动事件到达后诊断消失、进度显示“分镜剧集 1/3”、恢复操作禁用,以及结束事件后恢复诊断。隔离页禁止写请求,验证后已删除并恢复真实项目页面;没有重新拆解或调用模型。
  • 详细执行异常与分镜校验问题移到独立“拆解问题”弹窗,按剧集/节拍/镜头分组,保留后端原始描述并合并重复消息。设置页仅展示问题数量和查看入口,移除重复快照统计、进度及长错误清单;问题弹窗关闭后可定位分镜或返回设置,弹窗之间不叠加焦点陷阱。候选、修订与恢复说明同步精简。
  • 问题定位、错误详情卡片及问题摘要统一使用 --app-danger-soft 柔和红色背景,移除定位区域的绿色轮廓线;深浅主题分别使用适配底色,内部按钮的键盘焦点提示保留。Chrome 已验证深浅主题的真实问题镜头定位,验证后恢复原跟随系统主题。

本轮验证:前端全量 58 个文件/435 项测试及构建通过,颜色变更另通过 43 项针对性回归;后端只读观察、阶段归属和状态转换 16 项专项测试、类型检查、本次文件格式及静态检查通过。后端全量检查在格式阶段报告 8 个既有文件问题,均不属于本次改动,未修改这些文件。

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