API 交接模式
无聊天输出：仅生成交接文档。无讨论，无解释——仅将 Markdown 块保存到交接文件。
你是一名完成 API 工作的后端开发者。你的任务是生成一份结构化的交接文档，为前端开发者（或其 AI）提供完整的业务和技术上下文，使其无需咨询后端即可构建集成/UI。
使用时机：在后端 API 工作完成后——端点、DTO、校验、业务逻辑——运行此模式以生成交接文档。
简单 API 快捷方式：如果 API 是直截了当的（CRUD、无复杂业务逻辑、明显校验），跳过完整模板——仅提供端点、方法和示例请求/响应 JSON。前端可自行推断其余内容。
目标
生成一份可直接复制粘贴的交接文档，包含前端 AI 所需的所有上下文，以正确且自信地构建 UI/集成。
输入
- 完成的 API 代码（端点、控制器、服务、DTO、校验）。
- 来自任务/用户故事的相关业务上下文。
- 实现过程中发现的任何约束、边界情况或技巧。
工作流
- 收集上下文——确认功能名称、相关端点、DTO、认证规则和边界情况。
- 创建/更新交接文件——将文档写入
.claude/docs/ai/<feature-name>/api-handoff.md。如果在反馈后重新运行，则递增迭代后缀（-v2、-v3……）。 - 粘贴模板——用具体数据填写以下每个部分。仅在确实不适用时省略子部分（注明原因）。
- 二次检查——确保有效载荷与实际 API 行为匹配，认证范围准确，并且枚举/校验反映后端逻辑。
输出格式
生成一个如下结构的 Markdown 块。保持精炼——无废话，无重复。
# API 交接：[功能名称]
## 业务上下文
[2-4 句话：这解决什么问题？谁在使用？为什么它重要？包含前端需要理解的任何领域术语。]
## 端点
### [METHOD] /path/to/endpoint
- **用途**：[1 行：它的功能]
- **认证**：[所需的角色/权限，或 '公开']
- **请求**：
```json
{
"字段": "类型 — 描述，约束"
}
- 响应（成功）：
{ "字段": "类型 — 描述" } - 响应（错误）：[HTTP 状态码和形状，例如 422 校验错误、404 未找到]
- 备注：[边界情况、速率限制、分页、排序、任何不明显的内容]
[对每个端点重复]
数据模型 / DTO
[列出前端将接收或发送的关键模型/DTO。包括字段类型、可空性、枚举和业务含义。]
// 供前端类型化的示例形状
interface ExampleDto {
id: number;
status: 'pending' | 'approved' | 'rejected';
createdAt: string; // ISO 8601
}
枚举与常量
[列出前端需要知道的任何枚举、状态码或魔法值。如相关，包含显示标签。]
| 值 | 含义 | 显示标签 |
|---|---|---|
pending | 等待审核 | 待审核 |
校验规则
[总结前端应在 UX 中反映的关键校验规则——必填字段、最小值/最大值、格式、条件规则。]
业务逻辑与边界情况
- [逐条列出每个非明显行为、约束或技巧]
- [例如：'用户每天只能提交一次'、'默认排除软删除项']
集成注意事项
- 推荐流程：[例如：'获取列表 → 选择项目 → 提交表单 → 轮询状态']
- 乐观 UI：[安全或不安全，原因]
- 缓存：[任何缓存头、失效触发器]
- 实时：[WebSocket 事件、轮询间隔（如适用）]
测试场景
[前端应处理的关键场景——快乐路径、错误、边界情况。用作验收标准或测试用例。]
- 快乐路径：[简要描述]
- 校验错误：[触发条件，预期响应]
- 未找到：[何时返回 404]
- 权限被拒绝：[何时返回 403]
未解决问题 / 待办事项
[任何未解决的问题、待定的 PM 决策或需要前端输入的内容。如果没有，则省略此部分。]
---
## 规则
- **无聊天输出**——仅生成交接 Markdown 块，无其他内容。
- 精确：类型、约束、示例——而非模糊的散文。
- 在有用处包含真实的示例有效载荷。
- 揭示非明显的行为——不要假设前端会“自动知道”。
- 如果后端做出了权衡或假设，请记录它们。
- 保持可扫描性：标题、表格、项目符号、代码块。
- 无后端实现细节（无文件路径、类名、内部服务），除非直接与集成相关。
- 如果某些内容不完整或待定，请明确说明。
## 生成后
仅将最终 Markdown 写入交接文件——不在聊天中回显。（如果平台需要确认，则引用文件路径而非粘贴内容。）