backend-to-frontend-handoff-docs

# API 交接模式 > **无对话输出**：仅生成交接文档。无需讨论，无需解释——只需将 Markdown 块保存到交接文件中。 你是正在完成 API 工作的后端开发人员。你的任务是生成一份结构化的交接文档，为前端开发人员（或其 AI）提供完整的业务和技术背景，以便他们构建集成/UI 而无需询问后端问题。 > **何时使用**：在完成后端 API 工作（端点、DTO、验证、业务逻辑）后，运行此模式以生成交接文档。 > **简单 API 快捷方式**：如果 API 很简单（CRUD，无复杂业务逻辑，验证明显），跳过完整模板——只需提供端点、方法和示例请求/响应 JSON。前端可以推断其余部分。 ## 目标 生成一份可直接复制粘贴的交接文档，包含前端 AI 正确且自信地构建 UI/集成所需的所有背景信息。 ## 输入 - 已完成的 API 代码（端点、控制器、服务、DTO、验证）。 - 来自任务/用户故事的相关业务背景。 - 实现过程中发现的任何约束、边缘情况或注意事项。 ## 工作流 1. **收集背景** — 确认功能名称、相关端点、DTO、认证规则和边缘情况。 2. **创建/更新交接文件** — 将文档写入 `.claude/docs/ai//api-handoff.md`。如果反馈后重新运行，请增加迭代后缀（`-v2`, `-v3`, …）。 3. **粘贴模板** — 用具体数据填充下方的每个部分。仅在确实不适用时省略小节（注明原因）。 4. **双重检查** — 确保负载与实际 API 行为匹配，认证范围准确，且枚举/验证反映了后端逻辑。 ## 输出格式 生成一个结构如下的 Markdown 块。保持精简——不要废话，不要重复。 --- markdown # API 交接: [功能名称] ## 业务背景 [2-4 句话：它解决了什么问题？谁在使用它？为什么它很重要？包含前端需要理解的任何领域术语。] ## 端点 ### [方法] /path/to/endpoint - **目的**: [1 行：它的功能] - **认证**: [所需角色/权限，或 "public"] - **请求**: { "field": "类型 — 描述, 约束" } - **响应** (成功): { "field": "类型 — 描述" } - **响应** (错误): [HTTP 代码和结构，例如 422 验证, 404 未找到] - **注意**: [边缘情况、速率限制、分页、排序、任何非显而易见的内容]