t-backend-finalize

后端收口执行

运行时边界统一参考：${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md

Purpose

• 读取 .ai/task/[feature]/.state.json 和 backend/finalize.md。
• 在 backend-accept 通过后执行统一收口：
  • /code-review
  • cargo clippy --fix --allow-dirty --allow-staged --all-targets --all-features
  • cargo fmt --all
  • OpenAPI 文档导出与前端 API 生成
• 若任一步失败，修复后默认从失败步骤恢复，不提供额外恢复参数。

Args

参数	说明
[feature]	功能名

Preconditions

• .ai/task/[feature]/.state.json 必须存在且可解析。
• backend 阶段必须已生成，且存在：
  • backend/index.md
  • backend/accept.md
  • backend/accept/*.md
  • backend/finalize.md
• tasks.backend.accept.status 必须为 completed。

Fixed Flow

• 读取 backend/accept.md manifest、backend/accept/*.md item handoff、backend/finalize.md、backend 改动范围和最小必要状态。
• 确定 /code-review 作用范围：
  • 优先使用 finalize.md 中声明的 feature 相关 backend 改动文件
  • 若未显式声明，则回退到当前工作区 backend/** 改动集
• 执行 /code-review，简化目标范围内代码。
• 执行 cargo clippy --fix --allow-dirty --allow-staged --all-targets --all-features。
• 执行 cargo fmt --all。
• 导出 OpenAPI 文档并生成前端 API 客户端：
  • 先根据目标仓库的 backend app crate、现有导出脚本或文档定位实际导出 binary
  • 执行 cd backend && cargo run --bin <app-binary> -- --export-openapi ../frontend/api.json && cd ../
  • 验证生成的 OpenAPI JSON（格式、路径占位符 camelCase）
  • 执行 cd frontend && npm run generate-api && cd ../
  • 验证生成的 TypeScript 文件
• 若任一步出现问题，则修复并从失败步骤恢复。

State Transition

• 开始前写入：
  • tasks.backend.finalize.status = running
  • tasks.backend.finalize.started_at = <timestamp>
  • phases.backend.status = awaiting_finalize
• 维护步骤级状态：
  • tasks.backend.finalize.current_step
  • tasks.backend.finalize.steps.code_review|clippy|fmt|openapi_export|frontend_api_gen
• 某一步成功后，写入对应 step 为 completed。
• 某一步失败后：
  • tasks.backend.finalize.status = failed
  • tasks.backend.finalize.last_error = <summary>
  • tasks.backend.finalize.current_step = <failed_step>
  • phases.backend.status = failed
• 再次执行同一命令时：
  • 默认从 current_step 或最后失败步骤恢复
  • 若失败发生在 openapi_export 或之后，修复后至少重新执行 clippy -> fmt -> openapi_export -> frontend_api_gen
• 全部成功后：
  • tasks.backend.finalize.status = completed
  • tasks.backend.finalize.completed_at = <timestamp>
  • phases.backend.status = completed

Success Criteria

• /code-review 已执行且没有遗留待处理冲突。
• cargo clippy --fix --allow-dirty --allow-staged --all-targets --all-features 执行完成，收口结束时无 warning。
• cargo fmt --all 已执行。
• OpenAPI 文档已成功导出到 frontend/api.json。
• 前端 API 客户端已成功生成（frontend/api/*.ts）。

Failure

• accept 未完成：拒绝执行，并提示先完成 /t-run [feature] --phase backend。
• finalize.md 缺失：提示先重新生成 backend 任务。
• OpenAPI 导出失败：提示检查 utoipa 注解完整性，修复后从 openapi_export 步骤恢复。
• 前端 API 生成失败：提示检查 OpenAPI JSON 格式，修复后从 frontend_api_gen 步骤恢复。
• 状态写入失败：重试一次，失败则终止。
• 超过 3 轮自动修复仍未通过：标记 failed 并返回阻塞步骤。

Examples

/t-backend-finalize <feature>