name: 后端至前端交接文档 description: 为前端开发者创建API交接文档。当后端工作完成需要为前端集成记录文档时使用，或用户说“创建交接”、“记录API”、“前端交接”或“API文档”。
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。包括字段类型、可空性、枚举和业务含义。]
// 前端类型的示例形状
接口 示例Dto {
id: 数字;
状态: '待处理' | '已批准' | '已拒绝';
创建时间: 字符串; // ISO 8601
}
枚举与常量
[列出前端需要知道的任何枚举、状态代码或魔法值。包括显示标签（如果相关）。]
| 值 | 含义 | 显示标签 |
|---|---|---|
待处理 |
等待审核 | 待处理 |
验证规则
[总结前端应为UX镜像的关键验证规则—必填字段、最小/最大、格式、条件规则。]
业务逻辑与边界情况
- [每个非显而易见行为、约束或陷阱的项目符号]
- [例如，“用户每天只能提交一次”、“软删除项目默认排除”]
集成备注
- 推荐流程：[例如，“获取列表 → 选择项目 → 提交表单 → 轮询状态”]
- 乐观UI：[安全与否，原因]
- 缓存：[任何缓存头、失效触发]
- 实时：[WebSocket事件、轮询间隔（如果适用）]
测试场景
[前端应处理的关键场景—快乐路径、错误、边界情况。用作接受标准或测试用例。]
- 快乐路径：[简短描述]
- 验证错误：[触发什么，预期响应]
- 未找到：[何时返回404]
- 权限拒绝：[何时返回403]
开放问题 / 待办事项
[任何未解决、待PM决策或需要前端输入的内容。如果没有，省略此部分。]
---
## 规则
- **无聊天输出**—仅生成交接Markdown块，无其他。
- 精确：类型、约束、示例—非模糊散文。
- 包含真实示例负载（如有帮助）。
- 展现非显而易见行为—不要假设前端“自然会知道”。
- 如果后端做出权衡或假设，记录它们。
- 保持可扫描：标题、表格、项目符号、代码块。
- 无后端实现细节（无文件路径、类名、内部服务），除非直接相关于集成。
- 如果某些内容不完整或待定，明确说明。
## 生成后
仅将最终Markdown写入交接文件—不要在聊天中回显。（如果平台需要确认，引用文件路径而非粘贴内容。）