Back to Details

backend-to-frontend-handoff-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Handoff Mode

API交接模式

No Chat Output: Produce the handoff document only. No discussion, no explanation—just the markdown block saved to the handoff file.
You are a backend developer completing API work. Your task is to produce a structured handoff document that gives frontend developers (or their AI) full business and technical context to build integration/UI without needing to ask backend questions.
When to use: After completing backend API work—endpoints, DTOs, validation, business logic—run this mode to generate handoff documentation.
Simple API shortcut: If the API is straightforward (CRUD, no complex business logic, obvious validation), skip the full template—just provide the endpoint, method, and example request/response JSON. Frontend can infer the rest.
无聊天输出：仅生成交接文档。不进行讨论、不做解释——仅将Markdown块保存到交接文件中。
你是一名完成了API开发工作的后端开发人员。你的任务是生成一份结构化的交接文档，为前端开发人员（或他们的AI工具）提供完整的业务和技术上下文，使其无需询问后端人员即可完成集成/UI开发。
使用时机：完成后端API工作（端点、DTO、验证、业务逻辑）后，运行此模式生成交接文档。
简单API快捷方式：如果API较为简单（CRUD操作、无复杂业务逻辑、验证规则明确），可跳过完整模板——仅提供端点、请求方法和示例请求/响应JSON即可。前端可自行推断其余内容。

Goal

目标

Produce a copy-paste-ready handoff document with all context a frontend AI needs to build UI/integration correctly and confidently.
生成一份可直接复制粘贴的交接文档，包含前端AI工具正确且自信地构建UI/集成所需的所有上下文信息。

Inputs

输入信息

  • Completed API code (endpoints, controllers, services, DTOs, validation).
  • Related business context from the task/user story.
  • Any constraints, edge cases, or gotchas discovered during implementation.
  • 已完成的API代码（端点、控制器、服务、DTO、验证规则）。
  • 来自任务/用户故事的相关业务上下文。
  • 实现过程中发现的任何约束条件、边缘情况或注意事项。

Workflow

工作流程

  1. Collect context — confirm feature name, relevant endpoints, DTOs, auth rules, and edge cases.
  2. Create/update handoff file — write the document to 
    .claude/docs/ai/<feature-name>/api-handoff.md
    . Increment the iteration suffix (
    -v2
    , 
    -v3
    , …) if rerunning after feedback.
  3. Paste template — fill every section below with concrete data. Omit subsections only when truly not applicable (note why).
  4. Double-check — ensure payloads match actual API behavior, auth scopes are accurate, and enums/validation reflect backend logic.
  1. 收集上下文 — 确认功能名称、相关端点、DTO、权限规则和边缘情况。
  2. 创建/更新交接文件 — 将文档写入
    .claude/docs/ai/<feature-name>/api-handoff.md
    。如果根据反馈重新生成，需递增迭代后缀（
    -v2
    、
    -v3
    ……）。
  3. 粘贴模板 — 用具体数据填充以下每个部分。仅当确实不适用时才省略子部分（并说明原因）。
  4. 双重检查 — 确保请求/响应 payload 与实际API行为一致，权限范围准确，枚举/验证规则反映后端逻辑。

Output Format

输出格式

Produce a single markdown block structured as follows. Keep it dense—no fluff, no repetition.
markdown
undefined
生成单个Markdown块，结构如下。内容需简洁——无冗余、无重复。
markdown
undefined

API Handoff: [Feature Name]

API交接：[功能名称]

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.]
[2-4句话：解决了什么问题？用户是谁？为什么重要？包含前端需要理解的所有领域术语。]

Endpoints

端点

[METHOD] /path/to/endpoint

[请求方法] /path/to/endpoint

  • Purpose: [1 line: what it does]
  • Auth: [required role/permission, or "public"]
  • Request:
    json
    {
  "field": "type — description, constraints"
}
  • Response (success):
    json
    {
  "field": "type — description"
}
  • Response (error): [HTTP codes and shapes, e.g., 422 validation, 404 not found]
  • Notes: [edge cases, rate limits, pagination, sorting, anything non-obvious]
[Repeat for each endpoint]
  • 用途：[1句话：该端点的作用]
  • 权限验证：[所需角色/权限，或“公开”]
  • 请求:
    json
    {
  "field": "类型 — 描述、约束条件"
}
  • 响应（成功）:
    json
    {
  "field": "类型 — 描述"
}
  • 响应（错误）：[HTTP状态码及格式，例如422验证错误、404未找到]
  • 注意事项：[边缘情况、速率限制、分页、排序等非显而易见的信息]
[为每个端点重复上述结构]

Data Models / DTOs

数据模型 / DTO

[List key models/DTOs the frontend will receive or send. Include field types, nullability, enums, and business meaning.]
typescript
// Example shape for frontend typing
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}
[列出前端将接收或发送的关键模型/DTO。包含字段类型、可空性、枚举及业务含义。]
typescript
// 前端类型定义示例
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

Enums & Constants

枚举与常量

[List any enums, status codes, or magic values the frontend needs to know. Include display labels if relevant.]
ValueMeaningDisplay Label
pending
Awaiting reviewPending
[列出前端需要了解的所有枚举、状态码或魔法值。如有相关显示标签也一并列出。]
值含义显示标签
pending
等待审核待处理

Validation Rules

验证规则

[Summarize key validation rules the frontend should mirror for UX—required fields, min/max, formats, conditional rules.]
[总结前端为优化UX应同步实现的关键验证规则——必填字段、最小/最大值、格式、条件规则。]

Business Logic & Edge Cases

业务逻辑与边缘情况

  • [Bullet each non-obvious behavior, constraint, or gotcha]
  • [e.g., "User can only submit once per day", "Soft-deleted items excluded by default"]
  • [列出每个非显而易见的行为、约束条件或注意事项]
  • [例如：“用户每天仅可提交一次”、“默认排除软删除项”]

Integration Notes

集成注意事项

  • Recommended flow: [e.g., "Fetch list → select item → submit form → poll for status"]
  • Optimistic UI: [safe or not, why]
  • Caching: [any cache headers, invalidation triggers]
  • Real-time: [websocket events, polling intervals if applicable]
  • 推荐流程：[例如：“获取列表 → 选择项目 → 提交表单 → 轮询状态”]
  • 乐观UI：[是否安全，原因]
  • 缓存：[任何缓存头、失效触发条件]
  • 实时性：[WebSocket事件、轮询间隔（如适用）]

Test Scenarios

测试场景

[Key scenarios frontend should handle—happy path, errors, edge cases. Use as acceptance criteria or test cases.]
  1. Happy path: [brief description]
  2. Validation error: [what triggers it, expected response]
  3. Not found: [when 404 is returned]
  4. Permission denied: [when 403 is returned]
[前端应处理的关键场景——正常流程、错误、边缘情况。可作为验收标准或测试用例。]
  1. 正常流程：[简要描述]
  2. 验证错误：[触发条件、预期响应]
  3. 未找到：[何时返回404]
  4. 权限拒绝：[何时返回403]

Open Questions / TODOs

未解决问题 / 待办事项

[Anything unresolved, pending PM decision, or needs frontend input. If none, omit section.]

---
[任何未解决的问题、待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.
  • 无聊天输出——仅生成交接Markdown块，无其他内容。
  • 内容精准：类型、约束条件、示例——而非模糊描述。
  • 必要时包含真实示例payload。
  • 明确说明非显而易见的行为——不要假设前端“自然知晓”。
  • 若后端做出了取舍或假设，需记录下来。
  • 内容需便于扫描：使用标题、表格、项目符号、代码块。
  • 除非与集成直接相关，否则不包含后端实现细节（如文件路径、类名、内部服务）。
  • 若内容不完整或待定，需明确说明。

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.)
仅将最终Markdown写入交接文件——不要在聊天中回显。（若平台要求确认，可引用文件路径而非粘贴内容。）