Files
short-drama-agent-front/docs/superpowers/plans/2026-10-08-backend-contract-sync.md

99 lines
10 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.
# 后端正式功能同步 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 在现有页面完整接入已确认的六类后端正式能力。
**Architecture:** API/type 层依据本地后端路由与服务 DTO。持久化任务复用 useWorkflowExecution,诊断组件只读加载,付费操作复用 ConfirmAction。逐个实现任务,不并行修改同一文件。
**Tech Stack:** Vue 3 / TypeScript / Vite / Tailwind / Naive UI。
## Global Constraints
- 工作目录为 /Users/goujun/workspace/agents-workspace/short-drama-agent-front/.worktrees/backend-contract-sync;后端只读 /Users/goujun/workspace/agents-workspace/short-drama-agent。
- 所有新/改函数、类型字段、ref/computed/watch 与 UI 模块添加中文注释。
- 已有功能、15px 间距和主题保持;超过两处重复使用的功能抽公共方法或组件。
- 页面验收仅本地 Chrome,localhost,禁止 Playwright;由主代理统一操作浏览器,子代理不操作 UI。
- 不在验证中创建真实付费模型任务;API 请求不自动重试,显示范围和费用后用户主动确认才发送。
- 子代理不提交;主代理在全部完成并审查后统一提交。不要 push。
- 后端 API 文档可能滞后,最终契约取 routes/*.routes.ts 与对应 service 的实际返回。
### Task 1: 生产计划、断点与限流
**Files:** Modify src/features/production/api.ts, types.ts, useAdvancedProduction.ts, components/AdvancedProduction.vue; create non-UI contract tests under tests/features/production.
**Consumes:** /production/plan POST、/production/start POST、useWorkflowExecution、ApiError.details。
**Produces:** ProductionStartInput、ProductionPlanInput,productionApi.plan/startPipeline,预检后可编辑并确认的生产范围。
- [ ] 先验证现有 plan 的 GET 与后端 POST 不匹配,加入契约断言(真实 request 封装+受控 fetch)。
```ts
await productionApi.plan('p', undefined, {imageProvider:'qwen-image',videoProvider:'wan'})
// 最终请求必须为 POST /api/projects/p/production/plan;Provider 在 JSON body。
```
- [ ] 使用后端 production.routes.ts 的枚举与整数规则。
```ts
/** 可恢复的生产阶段 */
type ProductionStage = 'subjectImages' | 'keyframes' | 'videoPrompts'
// startFrom / stopAfter、stableIdentityAnchorLimit、subjectImageLimit、keyframeLimit、videoPromptLimit、imageGenerationOptions。
```
- [ ] AdvancedProduction 的参数变化废弃已确认预检和费用确认;safeMode 保留默认不提交视频的边界。所有上限默认有限值。显式结束阶段和起始阶段须检查顺序。
- [ ] 预检与实际提交共用项目模型和图片参数;409 从 details.executionId 追踪已有任务,显示“已有任务”,不创建第二次请求。任务失败保留真实结果详情,不显示已完成。
- [ ] 保持主要资产计数与项目归属检查;对照 production-plan.service.ts / production.service.ts 补足返回类型,不编造字段。
- [ ] 执行定向 API 检查、typecheck、改动文件 lint/format,自查并写 task-1-report.md,不提交。
### Task 2: 首帧质量后台任务与历史
**Files:** Modify src/features/production/quality-api.ts, quality.types.ts, quality.ts, useQuality.ts, components/QualityDialog.vue, components/QualityResult.vue; Create components/KeyframeValidationHistory.vue. Do not modify api.ts/types.ts、ProductionPage.vue 或 ShotProductionAssets.vue(主代理集成)。
**Consumes:** POST /projects/:id/keyframes/generate-quality 返回 {executionId,projectId,status:'running',total};GET /storyboard-shots/:shotId/keyframes/:keyframeId/validations 返回 {id,status,output,error,startedAt,finishedAt,createdAt}[]。
**Produces:** QualityInput.shotId?、批量任务跟踪与最终回执;KeyframeValidationHistory 组件 props(projectId?,shotId,keyframeId),仅只读加载;单镜头质量目标支持 kind:'batch' 和 shotId/episodeNo。
- [ ] 先为 202 任务启动/目标过滤与历史契约建立失败断言,UI 验收交给主代理 Chrome。
- [ ] qualityApi.generate 改为真实任务启动类型,useQuality 在收到 executionId 后追踪后台任务;未完成绝不能当 QualityBatchResult。每次启动参数固定,完成后按原项目/集/镜头保留回执和刷新。
- [ ] 重用 useWorkflowExecution(projectId,'keyframe-quality'),刷新后恢复;展示任务阶段、计数、失败、最终逐镜结果;活跃任务阻止重复操作,409 若后端支持则附着已有任务。
- [ ] 支持指定 shotId 且 limit=1 的单镜头重跑,显示明确费用范围;接入现有模型控制 provider / generationOptions(依后端参数)。保留 force 的清晰确认。
- [ ] 历史组件读取 output JSON 的真实校验结论、summary、issues 和错误/时间,raw 不当成成功。切换目标取消请求、防旧响应覆盖,不触发新的校验。
- [ ] 不根据历史 PASS 自动改变手动晋升政策,保留现有 currentness 和会话守卫。
- [ ] 定向 API 检查、typecheck、lint/format并写 task-2-report.md,给主代理精确集成说明,不提交。
### Task 3: 身份预览、校验与稳定母版质量生成
**Files:** Own src/features/subject-identity/**;新增 API/type、可复用诊断组件,避免重构其它工作区。
**Consumes:** subject-identity.routes.ts 的 /identity/images/preview POST、/images/:imageId/validate POST、/stable-anchor/generate-quality POST;对应服务 DTO。
**Produces:** 生图弹窗真实输入预览;身份图库指定图片质量校验及结果;Scene/Prop 单主体稳定母版质量生成和回执。
- [ ] 依据真实请求(provider、generationOptions、生成类型和参考图参数)验证预览参数与实际生成同源;只读预览不生成、不锁定。
- [ ] 预览显示实际模型、参考图、最终 Prompt 和最终参数;切换主体/参数清空旧预览,取消或忽略迟到响应。
- [ ] 身份校验保持显式费用确认;完成前不显示通过,失败显示后端 issues/summary,指定正式 subject/image ID,错误不清空原图库。
- [ ] Scene/Prop 单主体质量生成保留 maxRepairAttempts、provider/options 与有限预算,成功按真实返回刷新母版、锁定状态和图库;人物仍走既有选角流程。
- [ ] 新 API/DTO 基于后台服务返回,不沿用首帧 DTO 猜测。所有状态按原主体隔离。
- [ ] 定向 API 检查、typecheck、lint/format,写 task-3-report.md,不提交。主代理负责 Chrome。
### Task 4: 视频诊断与分镜引用审计(主代理)
**Files:** 新增 production/components/VideoQualityDiagnostics.vue 与 diagnostics.types.ts/api.ts;storyboard 的 api/types 与新增 SubjectCoverageAudit.vue;集成 ShotProductionAssets.vue、StoryboardPage.vue、ProductionPage.vue。
**Consumes:** GET videos/quality-status?detail=true、GET videos/quality-exhaustion-analysis;GET /projects/:id/storyboard/subject-coverage。
**Produces:** 只读失败详情与回退建议;分镜引用遗漏列表;首帧历史与单镜头质量入口,后台任务状态在弹窗外也可观察。
- [ ] 对照 video-quality-status.service.ts、video-quality-exhaustion-analyzer.service.ts 和 storyboard-subject-coverage-audit.service.ts 定义全部展示字段与 API;直接引用实际判定,不自行判成功。
- [ ] VideoQualityDiagnostics 按需加载,展示链路、问题、发生次数、后端疑因和 recommendedRollback。只读操作不调用修复;换目标取消请求。
- [ ] SubjectCoverageAudit 按需零费用读取,展示统计和遗漏主体/镜头;引用跳转使用当前项目正式 ID,不自动修复生成。
- [ ] ShotProductionAssets 添加历史与单镜头质量重跑入口,QualityDialog 使用 Task 2 提供的 batch shotId目标;ProductionPage 加持久化 keyframe-quality 观察面板。
- [ ] 共享诊断布局超过两处时抽离通用组件;尊重当前主题与15px间距。
### Task 5: 验证、审查与提交
- [ ] 本地 Chrome 在专用 localhost 端口检查全部六项入口、真实读取、错误显示、目标切换、弹窗关闭/重开及任务恢复;仅取消付费确认。
- [ ] 定向契约检查、lint、改动文件 format、typecheck、build;全量测试排除 .worktrees/** 和 .worktree/**,与基线已有失败比较,不修无关旧故障。
- [ ] 子代理逐任务审查及最终整分支审查,修复本次新增问题;用户已授权一次最终提交,无需再次问。
- [ ] git diff --stat、git diff 后提交 Conventional Commit:feat(short-drama-agent-front): 补齐后端生产与质量功能。报告实际分支/提交和验证限制,不 push。
### Task 6: 已有分镜与普通首帧入口的 202 契约补齐
**Files:** storyboard/api.ts/useStoryboard.ts/StoryboardPage.vue;production/api.ts/useProduction.ts/ProductionPage.vue;projects/ProjectLayout.vue;workflows/execution.ts(仅阶段标签)。
**Consumes:** storyboard.routes.ts 下正式 regenerate(workflowName breakdown,metadata 用于区分镜头重生成)、directions/generate(storyboard-direction)、visual-states/generate(storyboard-visual-state)、video-prompts/generate(video-prompt)、keyframes/generate(keyframe-generation)实际 202 启动与最终 result。
**Produces:** 这些已有入口与质量入口一样正确后台化,不接测试路由、不创建新页面。
- [ ] 对照真实路由的 workflowName 与 metadata,以及最终服务 DTO。API 启动方法返回 WorkflowExecutionStart,而不是最终批量/重生成回执。
- [ ] useStoryboard 分别跟踪任务,成功启动后不发布完成回执;在终态按原 projectId/episodeNo/metadata 归属发布真实结果。重生成仅在校验有效时更新当前正式缓存,旧 ID 缓存清理规则保留。
- [ ] useProduction 普通首帧生成同样跟踪 keyframe-generation,完成后生成原项目首帧回执并刷新;视频/提示词已有后台 track 补传原 projectId 防跨项目归属。
- [ ] 项目布局持续观察这些名字以维持跨页面活动锁,工作区展示状态面板与手动刷新;复用现有共享执行组件。
- [ ] 有限范围、旧结果不误报完成、费用确认、操作互斥与全部中文注释规范保持。不提交,不执行付费请求。
- [ ] 先验证旧 API 把202类型当成最终结果的契约问题,补充 API边界测试;主代理负责 Chrome 确认入口/取消费用对话框。