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

10 KiB
Raw Permalink Blame History

后端正式功能同步 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)。
await productionApi.plan('p', undefined, {imageProvider:'qwen-image',videoProvider:'wan'})
// 最终请求必须为 POST /api/projects/p/production/plan;Provider 在 JSON body。
  • 使用后端 production.routes.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 确认入口/取消费用对话框。