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 -- --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 =
• 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 =
• tasks.backend.finalize.current_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 =
• 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 

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: timzaak
• Source: timzaak/web-dev-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.