后端 API 完成后为前端生成交接文档

当后端接口、DTO、校验和业务逻辑完成后，需要输出一份结构化交接文档供前端或前端 AI 直接集成时使用。

适用场景

解决思路

1. 确认功能名称、相关端点、DTO、鉴权规则和边界情况，收集上下文。
2. 将交接文档写入 `.claude/docs/ai/<feature-name>/api-handoff.md`；若根据反馈重跑，递增迭代后缀（`-v2`、`-v3`……）。
3. 套用模板并填入具体数据，每个小节都要填写；仅在确实不适用时省略子小节并注明原因。
4. 文档结构包含：Business Context（2-4 句说明解决什么问题、谁使用、为何重要，并解释前端需理解的领域术语）。
5. Endpoints 部分：每个端点写清 METHOD 与路径、Purpose（一行说明）、Auth（所需角色/权限或 public）、Request JSON（字段类型、描述、约束）、成功 Response JSON、错误 Response（HTTP 状态码与结构，如 422 校验、404 未找到）、Notes（边界情况、限流、分页、排序等非显而易见信息）。
6. Data Models / DTOs 部分：列出前端会收发的关键模型/DTO，包含字段类型、可空性、枚举和业务含义，并给出 TypeScript 接口示例。
7. Enums & Constants 部分：用表格列出枚举、状态码或魔法值及其含义和展示标签。
8. Validation Rules 部分：总结前端应在 UX 上镜像的关键校验规则，如必填、最小/最大值、格式、条件规则。
9. Business Logic & Edge Cases 部分：逐条列出非显而易见的行为、约束或坑点（如每天只能提交一次、默认排除软删除项）。
10. Integration Notes 部分：写明推荐流程（如拉列表→选中项→提交表单→轮询状态）、是否可做乐观 UI 及原因、缓存（缓存头、失效触发）、实时（WebSocket 事件、轮询间隔）。
11. Test Scenarios 部分：列出前端应处理的关键场景作为验收标准，至少覆盖 happy path、校验错误、未找到、权限拒绝。
12. Open Questions / TODOs 部分：记录未决事项、待产品决策或需前端输入的内容；若无则省略该节。
13. 生成后再次核对：payload 与实际 API 行为一致、鉴权范围准确、枚举与校验反映后端逻辑。
14. 若 API 很简单（CRUD、无复杂业务逻辑、校验直观），跳过完整模板，只提供端点、方法以及请求/响应 JSON 示例。
15. 只输出交接 markdown 块，不输出聊天内容、讨论或解释；若平台要求确认，只引用文件路径而非粘贴内容。
16. 保持精确：写清类型、约束、示例，避免模糊描述；包含真实示例 payload。
17. 主动暴露非显而易见的行为，不要假设前端会“自然知道”；若后端做了取舍或假设，要记录在文档中。
18. 保持可扫读：使用标题、表格、项目符号、代码块。
19. 不写后端实现细节（文件路径、类名、内部服务），除非与集成直接相关；若有未完成或 TBD 的内容，明确说明。

适用边界 · 注意事项

• API 非常简单（纯 CRUD、无复杂业务逻辑、校验直观）时，不必套用完整模板。
• 后端工作尚未完成、接口行为还会变动时，不宜生成正式交接文档。
• 需要输出聊天解释或讨论而非文档本身时，不适用此模式。