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

79 lines
7.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 前后端接口复核记录
基线:前端当前 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 工作区。