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/<feature-name>/api-handoff.md。如果在收到反馈后重新运行，请递增迭代后缀（-v2、-v3……）。
3. 粘贴模板 — 用具体数据填写以下每个部分。仅在确实不适用时才省略子部分（并注明原因）。
4. 复查 — 确保载荷与实际 API 行为一致、认证范围准确、枚举/验证与后端逻辑相符。

输出格式

生成如下结构的单个 markdown 代码块。保持内容密集——不要空话，不要重复。

---

# API Handoff: [Feature Name]

## Business Context
[2-4 sentences: What problem does this solve? Who uses it? Why does it matter? Include any domain terms the frontend needs to understand.]

## Endpoints

### [METHOD] /path/to/endpoint
- **Purpose**: [1 line: what it does]
- **Auth**: [required role/permission, or "public"]
- **Request**:
  ```json
  {
    "field": "type — description, constraints"
  }

• 响应（成功）：

  {
    "field": "type — description"
  }
  

• 响应（错误）：[HTTP 状态码和结构，例如 422 验证错误、404 未找到]
• 备注：[边界情况、速率限制、分页、排序、任何不明显的内容]

[对每个端点重复]

数据模型 / DTO

[列出前端将接收或发送的关键模型/DTO。包括字段类型、可空性、枚举和业务含义。]

// Example shape for frontend typing
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

枚举与常量

[列出前端需要了解的任何枚举、状态码或魔法值。如相关，请包括显示标签。]

值	含义	显示标签
pending	等待审核	待处理

验证规则

[总结前端为提升 UX 应镜像的关键验证规则——必填字段、最小/最大值、格式、条件规则。]

业务逻辑与边界情况

• [用项目符号列出每个不明显的行为、约束或陷阱]
• [例如，“用户每天只能提交一次”、“默认排除软删除项”]

集成说明

• 推荐流程：[例如“获取列表 → 选择项 → 提交表单 → 轮询状态”]
• 乐观 UI：[是否安全，原因]
• 缓存：[任何缓存头、失效触发条件]
• 实时：[如适用，WebSocket 事件、轮询间隔]

测试场景

[前端应处理的关键场景——正常路径、错误、边界情况。用作验收标准或测试用例。]

1. 正常路径：[简要描述]
2. 验证错误：[触发条件、预期响应]
3. 未找到：[何时返回 404]
4. 权限被拒绝：[何时返回 403]

未决问题 / 待办事项

[任何未解决、待 PM 决定或需要前端输入的事项。如无，请省略此部分。]

---

## Rules
- **NO CHAT OUTPUT**—produce only the handoff markdown block, nothing else.
- Be precise: types, constraints, examples—not vague prose.
- Include real example payloads where helpful.
- Surface non-obvious behaviors—don't assume frontend will "just know."
- If backend made trade-offs or assumptions, document them.
- Keep it scannable: headers, tables, bullets, code blocks.
- No backend implementation details (no file paths, class names, internal services) unless directly relevant to integration.
- If something is incomplete or TBD, say so explicitly.

## After Generating
Write the final markdown into the handoff file only—do not echo it in chat. (If the platform requires confirmation, reference the file path instead of pasting contents.)