Files
short-drama-agent-front/docs/frontend-contract-audit-2026-10-19.md
T

7.1 KiB
Raw Blame History

前后端接口复核记录

基线:前端当前 dev(HEAD c4b43b9,包含此前未提交工作),只读核对后端 dev 6a6fd52d。本轮没有提交、push 或修改后端。

真实导航与制作入口

本地 Chrome 复用 localhost:4312,读取项目“掩耳盗铃”(cmv9eqf6v0000k6idvk1y3256):

检查 当前结果 页面含义
导航 script ready=true 剧本已完成
导航 breakdown ready=true 当前正式分镜审核有效,视觉风格入口开放
导航 visualStyle / identity / subjectAssets ready=false 分别仍需准备,不会因拆解通过而自动解锁全部步骤
导航 storyboard ready=true 镜头生成方案符合此阶段的条件,不等同于视频已生成
制作 entry-readiness ready=true、storyboardValid=true 分镜准入通过,镜头设计和画面状态覆盖完整
正式镜头 / 镜头设计 / 画面状态 61 / 61 / 61 数量覆盖完整;前端仍单独核对 staleCount

旧导航待审问题已解决。前端继续只使用 stage-readiness 决定导航,不从旧 Checkpoint 或任务 completed 状态推导审核结论。无需为了本次后端修复新增导航接口或重复审核状态。

修复的真实问题

  1. 计划请求曾夹带启动阶段、生成上限和视频参数。计划只解析三项模型参数,现由 API 层按真实字段构造 POST body;实际启动仍携带完整参数并再次预检。
  2. 缺少项目配置已有空值保护,但缺少就地恢复操作。现在保留独立业务状态,在计划位置打开已有项目配置抽屉;配置读取后消失的竞态同样阻断,不读取空统计、不启动。
  3. 配置冲突仅显示原始说明且留在正文。现在识别实际 details.code 与顶层 code,将三类 409 转成中文 NMessage 警告,保留草稿、不发布保存成功、不重试写入;普通失败保持错误级别。保存成功不再遗留常驻成功说明。
  4. 计划的 manualBlocked 是独立人工根因数量,原说明把它描述成各阶段累加。现明确独立计数及阶段影响数量可能重叠。

原本正确并保留的契约

以 API 模块对照后端实际路由及挂载顺序:盘点 162 处 request 调用,153 处直接匹配;其余 9 处为动态 action、媒介类型、资产路径及可选查询,逐一展开核对,未发现新增方法或路径错误。另核对任务发现 SSE 路径。

模块 核对要点与结论
项目创建、编辑、阶段 POST /projects、PUT /projects/:id、GET stage-readiness 正确;未完成阶段保持独立限制。未改写用户当前其他编辑页改动
拆解与正式审核 candidate 与正式数据分开;规则保存/确认、正式质量复检、人工审核、版本保护沿用当前接口,不用执行完成替代审核
Direction / VisualState 按集读取、项目生成 start、202 句柄及 staleCount 正确;不只看覆盖数量
Creative Profile GET 可为 null、PUT 完整配置正确;本轮只补冲突反馈和恢复操作
模型目录 GET generation-models、schema/options/defaults/specialValues 驱动;-1 不按品牌补造。项目画布与参考图尺寸独立;不把默认时长写入正式镜头
Production POST plan、POST start、GET status 正确;已有 blocked 联合类型保留,正常计划组件只接收非空阶段
主体图片 预览、生成、批量 start、切主图及模块范围保持正式接口,不混用素材和任务回执
首帧 预览、质量任务、候选编辑、版本权限沿用现有独立流程,不默认晋升或把旧通过当当前许可
视频提示词、视频生成 读取和生成分开;生成提交参数、异步句柄及任务终态沿用现有实现,不触发真实模型作验收
WorkflowExecution latest/get/events 的路径、工作流范围和空结果处理正确;202 是观察句柄,不能当资产或审核完成

方法/路径盘点不代表对全部收费分支进行了真实执行。请求体、返回空值、变更服务与既有测试重点核对配置、计划、导航、质量审核及长任务;其余接口本轮没有新增差异,不进行无关重构。

尚需后端处理的既有问题

诊断列表的新格式手部具体问题仍可能遗漏:storyboard-legacy-action-diagnosis-persistence.service.ts:78 保存对象 { handConflicts, bodyMotionFindings, qualityCodes },storyboard-legacy-action-diagnosis-results.service.ts:141 的 issues 仍只接受数组。前端不从其他镜头或历史证据猜测当前冲突。该问题与本次已修复的导航无关;原需求及边界见 backend-diagnosis-follow-up.md 第 2 项,正式编辑数据缺口第 1 项此前已解决,不应重复开发。

本轮改动文件

文件 用途
src/features/production/api.ts 计划请求字段限制,保留 POST
src/features/production/useAdvancedProduction.ts 缺少配置的明确业务状态及并发保护
src/features/production/components/AdvancedProduction.vue 复用配置恢复入口
src/features/production/components/ProductionPlanPanel.vue 独立人工阻断计数说明
src/features/generation-config/context.ts 共用现有配置抽屉打开入口
src/features/generation-config/components/CreativeProfileSettings.vue 保存成功及冲突统一消息,保留草稿
src/features/projects/ProjectLayout.vue 提供已有抽屉的打开方法
src/lib/http.ts、src/lib/user-facing-text.ts 保留原始错误,转换配置业务码说明
tests/features/generation-config/profile-settings.test.ts(新增) 冲突不重试、不成功、不覆盖草稿;成功消息
tests/features/generation-config/options.test.ts、profile-draft.test.ts 目录智能时长、画布与参考图尺寸独立
tests/features/production/backend-contract.test.ts、capabilities.test.ts 计划/启动字段边界、缺配置恢复及竞态
tests/features/projects/access.test.ts 旧待审标记不覆盖当前阶段,下游仍独立受限
tests/lib/user-facing-text.test.ts 顶层及详情业务码转换
docs/api-contract-sync.md、backend-production-navigation-follow-up.md、本文件 当前结果、历史问题关闭和交付记录

其余工作区原有修改和新增均保留,未一并提交。

验证

  • TypeScript、Oxlint/ESLint、生产构建、差异检查通过。
  • 全量 70 个文件 / 541 项测试通过。测试阻止未模拟请求连接真实服务。
  • 沿用本会话此前约定,未执行格式化或格式检查;未宣称其通过。
  • Chrome 真实服务:导航和制作入口当前结果、视觉风格入口解锁;未写配置、审核或触发模型。
  • Chrome 临时隔离页面:实际组件的缺配置、正常计划、配置保存成功、配置冲突、440×956 视口换行与固定底栏。所有请求在页面内模拟,禁止回退到真实网络。页面已删除并恢复真实项目桌面。
  • 未进行真实收费生成、素材覆盖、审核确认或数据库变更。GitHub 无新增 Commit,本轮只保留在前端 dev 工作区。