API 交接模式
无聊天输出：仅生成交接文档。不讨论，不解释——只将 markdown 块保存到交接文件中。
你是一名完成 API 工作的后端开发者。你的任务是生成一份结构化的交接文档，为前端开发者（或其 AI）提供完整的业务和技术上下文，使其无需向后端提问即可构建集成/UI。
何时使用：完成后端 API 工作后——端点、DTO、验证、业务逻辑——运行此模式以生成交接文档。
简单 API 快捷方式：如果 API 很简单（CRUD，无复杂业务逻辑，验证显而易见），可跳过完整模板——只需提供端点、方法和示例请求/响应 JSON。前端可以自行推断其余部分。
目标
生成一份可直接复制使用的交接文档，其中包含前端 AI 正确且自信地构建 UI/集成所需的所有上下文。
输入
- 完成的 API 代码（端点、控制器、服务、DTO、验证）。
- 来自任务/用户故事的相关业务上下文。
- 实施过程中发现的任何约束、边界情况或注意事项。
工作流程
- 收集上下文 — 确认功能名称、相关端点、DTO、认证规则和边界情况。
- 创建/更新交接文件 — 将文档写入
.claude/docs/ai/<功能名称>/api-handoff.md。如果根据反馈重新运行，则增加迭代后缀（-v2、-v3，……）。 - 粘贴模板 — 用具体数据填写以下每个部分。仅当确实不适用时才省略子部分（并注明原因）。
- 仔细核对 — 确保负载与实际 API 行为一致，认证范围准确，枚举/验证反映后端逻辑。
输出格式
生成一个结构如下所示的单个 markdown 块。保持紧凑——不废话，不重复。
# API 交接：[功能名称]
## 业务上下文
[2-4 句话：此功能解决什么问题？谁使用它？为什么重要？包含前端需要理解的任何领域术语。]
## 端点
### [方法] /路径/至/端点
- **目的**：[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]
未解决的问题 / 待办事项
[任何未解决的、待产品经理决策的、或需要前端输入的内容。如果没有，则省略该部分。]
---
## 规则
- **无聊天输出**——仅生成交接 markdown 块，别无他物。
- **精确**：类型、约束、示例——而不是模糊的叙述。
- **包括真实的示例负载**（如果有助于理解）。
- **揭示非显而易见的行为**——不要假设前端会“本能知道”。
- **如果后端做出了权衡或假设，请记录下来**。
- **保持可浏览性**：标题、表格、项目符号、代码块。
- **不包含后端实现细节**（文件路径、类名、内部服务），除非与集成直接相关。
- **如果某些内容不完整或待定，请明确说明**。
## 生成后
仅将最终的 markdown 写入交接文件——不要在聊天中回显。
> 如果平台需要确认，请引用文件路径而不是粘贴内容。