Frontend Api Guide

---
name: frontend-api-guide
description: 把 API 设计文档转成前端可直接编码的调用流程文档（含 UI 映射与错误处理速查）。触发："生成前端 API 文档"、"API 调用流程"，或 api-design 完成后交付前端时。
---

# 前端 API 集成指南

## 概述

**目的**：将 API 设计文档转化为前端可直接编码的集成指南，让前端开发者一看就懂

**功能**：基于 API 设计文档和技术设计文档，生成两类独立文档——**API 文档**（接口契约 + UI 映射）和**调用流程文档**（场景级调用序列 + 流程图），外加 INDEX.md 总览

**使用场景**：
- api-design 完成后，需要将 API 文档交付给前端
- 用户要求"生成前端 API 文档"、"API 调用流程"、"给前端的文档"
- 复杂场景下前端需要知道每个 API 在什么时机调用

## 定位

```
design-craft → api-design → frontend-api-guide（本 skill）
   技术设计      API 契约       前端集成指南
```

- **输入**：API 设计文档 + 技术设计文档 + UI 设计稿（可选）
- **输出**：API 文档（接口契约 + UI 映射）+ 调用流程文档（场景流程 + 流程图）
- **边界**：只描述"前端怎么调"，不修改 API 契约本身。API 文档和调用流程文档必须分开，互不混入

## 核心原则

1. **独立自包含**：生成的前端文档必须是完全独立的，不引用任何后端设计文档中的内部编号（如 "B-03"、"S-01"）或术语。前端拿到的是一份不需要查阅其他后端文档即可完整理解的独立指南
2. **场景驱动**：以用户操作流程为主线，不以接口列表为主线
3. **一看就懂**：前端拿到文档后无需再问后端"这个接口什么时候调"
4. **纯文档输出**：只描述接口调用信息，不包含任何前端代码（JS/TS/React/Vue 等），不指挥前端如何实现。文档只回答三个问题：调什么、传什么、返回什么
5. **可选 UI 映射**：有 UI 设计稿时，将 API 返回值与 UI 元素一一对应，但不涉及前端组件的具体实现方式
6. **错误处理闭环**：每个可能的错误响应都有明确的前端行为指引

7. **API 与流程分离**：API 文档只写接口契约和 UI 映射，不写调用流程；调用流程文档只写场景步骤和流程图，不嵌入接口契约

## 工作流总览

```
阶段 1：输入解析         → 读取 API 设计文档和技术设计文档
阶段 2：场景提取         → 从设计文档中提取用户操作场景
阶段 3：API 文档编写     → 按模块编写接口契约 + UI 映射（如有多模块则拆分为多个独立文件）
阶段 4：调用流程生成     → 为每个场景生成 API 调用序列 + 简要流程图
阶段 5：错误处理速查表   → 汇总所有错误码的前端行为
阶段 5.5：常见问题预判   → 预判前端可能产生的业务逻辑疑问并提前解答
阶段 6：落盘输出         → 生成集成指南文档
```

**各阶段顺序执行，阶段 2~5 的结果在阶段 6 统一输出。**

---

## 阶段 1：输入解析

读取以下文档，提取 API 列表和业务流程：

| 输入 | 来源 | 提取内容 |
|------|------|---------|
| API 设计文档 | api-design 产出 | 接口列表、参数、返回值、错误码 |
| 技术设计文档 | design-craft 产出 | 业务流程、用户角色、时序图 |
| UI 设计稿 | 用户提供（可选） | 页面结构、元素布局 |

**输出**：API 清单 + 业务场景清单

---

## 阶段 2：场景提取

从技术设计文档中提取用户操作场景，按角色分组。

### 场景提取规则

1. **从时序图提取**：每个时序图对应一个场景
2. **从方案(TO-BE)提取**：每个功能模块对应一组场景
3. **从用户角色提取**：不同角色的操作流程独立列出

### 输出格式

```text
📋 场景清单
━━━━━━━━━━━━━━━━

| # | 场景 | 角色 | 涉及 API 数 | 来源 |
|---|------|------|:---------:|------|
| 1 | 用户注册 | 普通用户 | 3 | 时序图 §注册 |
| 2 | 订单创建 | 普通用户 | 4 | 方案 §订单 |
| 3 | 订单审核 | 管理员 | 2 | 时序图 §审核 |

请确认场景是否完整。
```

---

## 阶段 3：API 文档编写

按模块编写面向前端的 API 文档，每个模块一个独立 md 文件。API 文档只包含接口契约和 UI 映射，不包含调用流程。

### 3.1 API 文档模板

每个模块（如用户模块、订单模块）一个独立文件，内部包含该模块所有接口的完整契约。

```markdown
# {模块名称} API

> 基础路径：/api/v1

## 接口清单

| 编号 | 方法 | 路径 | 说明 |
|------|------|------|------|
| API-01 | POST | /auth/register | 创建新用户 |
| API-02 | POST | /auth/send-code | 发送邮箱验证码 |

---

## API-01：{接口名称}

### 基本信息

| 项目 | 值 |
|------|-----|
| 方法 | POST |
| 路径 | /api/v1/auth/register |
| 认证 | 无 |
| 限流 | 1 次/分钟（同 IP）|
| 幂等 | 否 |

### 请求参数

#### Request Body

```json
{
  "email": "user@example.com",
  "password": "Abc12345",
  "name": "张三"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|:----:|------|
| email | string | 是 | 邮箱地址，需唯一 |
| password | string | 是 | 密码，8-32 位，含大小写字母和数字 |
| name | string | 否 | 用户昵称，2-20 字符（默认同邮箱前缀）|

### 成功响应（201）

```json
{
  "code": 201,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "张三"
  },
  "message": "success"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| data.id | string | 用户 ID |
| data.email | string | 注册邮箱 |
| data.name | string | 用户昵称 |

### 错误响应

| HTTP Status | 错误码 | 说明 |
|-------------|--------|------|
| 400 | INVALID_INPUT | 参数缺失或格式错误 |
| 409 | EMAIL_EXISTS | 邮箱已注册 |
| 429 | RATE_LIMITED | 请求过于频繁 |

### UI 映射（如有 UI 设计稿）

| UI 区域 | 元素 | 对应数据字段 | 数据处理 | 空状态 |
|---------|------|-------------|---------|--------|
| 注册表单 | 邮箱输入框 | request.email | 前端校验格式 | — |
| 注册成功页 | 用户昵称 | response.data.name | 直接显示 | — |
```

### 3.2 编写规则

- **API 文档只包含**：接口清单、契约（参数+响应）、UI 映射。**不包含**：调用时机、调用顺序、流程图
- 每个模块一个独立文件，存放在 `frontend-guide/api/` 下
- JSON 示例必须是真实可用的

---

## 阶段 4：调用流程生成

为每个场景生成调用序列和简要流程图，引用 API 文档中的接口编号而非嵌入契约细节。

### 调用序列格式

```text
🔄 调用序列：[场景名称]
━━━━━━━━━━━━━━━━

【角色】[角色名称]
【触发条件】[用户执行什么操作]

【调用步骤】

步骤 1：[用户操作描述]
  → 调用 API：[API-01 创建用户](./api/user-api.md#api-01)
  → 触发时机：[什么条件下调用]
  → 成功后：[下一步操作]
  → 失败时：[错误处理方式]

步骤 2：...
```

### 流程图规则

- 使用 mermaid flowchart 或 sequenceDiagram，**必须简要**
- 不超过 10 个节点，前端一眼能看完
- 节点 = 用户操作 / 页面 / API 调用 / 分支判断
- 连线 = 操作顺序 + 条件分支
- 标注成功/失败分支，但不要展开每个异常路径的细节

---

## 阶段 5：错误处理速查表

汇总所有 API 的错误码，为每个错误定义前端行为。

### 输出格式

```text
⚠️ 错误处理速查表
━━━━━━━━━━━━━━━━

【通用错误处理】

| HTTP 状态码 | 前端行为 |
|:----------:|---------|
| 401 | 清除本地 token，跳转登录页 |
| 403 | 提示"无权限执行此操作" |
| 404 | 提示"资源不存在" |
| 429 | 提示"操作过于频繁，请稍后重试" |
| 500 | 提示"服务器繁忙，请稍后重试" |

【业务错误处理】

| API | 业务错误码 | 错误信息 | 前端行为 |
|-----|----------|---------|---------|
| POST /auth/register | DUPLICATE_EMAIL | 邮箱已注册 | 表单字段标红 + 提示"该邮箱已注册，请直接登录" |
| POST /auth/register | WEAK_PASSWORD | 密码强度不足 | 表单字段标红 + 提示密码要求 |
| POST /orders | INSUFFICIENT_STOCK | 库存不足 | 提示"商品库存不足" + 刷新商品数量 |
| PUT /orders/:id | ORDER_STATUS_CHANGED | 订单状态已变更 | 提示"订单状态已变更，请刷新" + 自动刷新 |
```

---

## 阶段 5.5：常见问题预判

基于 API 设计和业务流程，预判前端拿到文档后可能产生的疑问，以 Q&A 形式在 INDEX.md 中呈现。

### 预判角度

| 角度 | 典型问题 |
|------|---------|
| 状态流转 | "这个字段什么时候有值、什么时候为空？" |
| 边界条件 | "列表为空时接口返回什么？" |
| 操作副作用 | "这个操作完成后页面数据怎么刷新？" |
| 跨页面联动 | "A 页面操作后 B 页面需要感知吗？怎么感知？" |
| 授权/权限 | "什么情况下需要跳转授权页？授权完怎么回来？" |
| 轮询/推送 | "这个数据是轮询刷新还是 WebSocket 推送？" |
| 回调处理 | "第三方回调后前端页面如何得知？" |

### 输出格式

```text
❓ 常见问题
━━━━━━━━━━━━━━━━

### Q1：[问题标题]

[用前端能理解的语言直接回答，不引用后端内部概念]

### Q2：[问题标题]

[用前端能理解的语言直接回答]
```

**质量要求**：
- 每个问题必须来自前端视角，预判的是"前端拿到文档后真正会问的"
- 每个回答必须自包含，不引用后端设计文档内部编号或术语
- 回答只描述事实（接口行为、数据含义、流程步骤），不指挥前端怎么实现

---

## 阶段 6：落盘输出

将所有阶段的输出整合为前端集成指南文档。

### 文档结构

按模块和场景拆分。API 文档和调用流程文档分开存放，互不混入：

```
frontend-guide/
├── INDEX.md              # 总览：整体流程图 + API 清单 + 错误处理 + FAQ + 注意事项
├── api/                  # API 文档（接口契约 + UI 映射，不包含流程）
│   ├── user-api.md       # 用户模块 API
│   └── order-api.md      # 订单模块 API
└── flow/                 # 调用流程文档（场景步骤 + 流程图，不嵌入契约）
    ├── user-register.md  # 场景：用户注册
    └── order-create.md   # 场景：订单创建
```

**INDEX.md（总览枢纽）**：

```markdown
# 前端 API 集成指南：{功能名称}

> 基于 API 设计文档版本：{版本}
> 生成时间：YYYY-MM-DD

## 整体调用流程

用 ASCII 字符画出前端操作 → API 调用 → 页面跳转的完整流程，让前端一眼看清全局。

```
用户点击「创建单据」
       │
       ▼
  选择「TAPD 单据」
       │
       ▼
  ┌─ 检查授权状态 ─┐
  │                │
  │  未授权          │  已授权
  │                │
  ▼                ▼
跳转用户态      进入建单表单
授权页             ...
```

## 1. API 清单

| # | 接口 | 方法 | 路径 | 说明 | 详细文档 |
|---|------|------|------|------|----------|
| 1 | 用户注册 | POST | /auth/register | 创建新用户 | [user-register.md](user-register.md) |
| 2 | 发送验证码 | POST | /auth/send-code | 发送邮箱验证码 | [user-register.md](user-register.md) |
| 3 | 创建订单 | POST | /orders | 创建新订单 | [order-create.md](order-create.md) |

## 2. 错误处理速查表

（阶段 5 内容：通用错误 + 业务错误表格）

## 3. 常见问题

（阶段 5.5 内容：以 Q&A 形式预判并解答前端可能产生的业务逻辑疑问）

## 4. 注意事项

- 前端需要维护的本地状态（如 token、用户信息缓存）
- 接口调用频率限制说明
- 需要前端轮询或 WebSocket 的场景
```

**api/{module}.md（API 文档）**：

```markdown
# {模块名称} API

> 基础路径：/api/v1

（阶段 3 内容：接口清单 + 每个 API 的完整契约 + UI 映射。不包含调用时机或流程图）
```

**flow/{scene}.md（调用流程文档）**：

```markdown
# {场景名称}

> 所属功能：{功能名称}
> 角色：{角色名称}

## 调用序列

（阶段 4 内容：步骤描述 + 引用 API 编号，不嵌入 JSON 参数/响应细节）

## 调用流程图

（mermaid flowchart 或 sequenceDiagram 简要版：不超过 10 个节点）
```

### 存储路径

检查项目中是否已配置存储位置（`.requirements/config`）：

- **已配置**：读取 `storage_path`，文档存放在 `{storage_path}/{feature}/frontend-guide/` 目录下
  - `INDEX.md`：整体流程图 + API 清单 + 错误处理 + FAQ + 注意事项
  - `api/{module}.md`：每个模块的 API 文档（接口契约 + UI 映射）
  - `flow/{scene}.md`：每个场景的调用流程文档（步骤 + 流程图）
- **未配置**：询问用户，给出默认建议 `.requirements/{feature}/frontend-guide/`

### 质量自检

```text
✅ 前端集成指南已生成

📄 <路径>

🔍 质量自检清单
━━━━━━━━━━━━━━━━

【可自动校验】
☐ 每个场景都有完整的调用序列
☐ 每个 API 都被至少一个场景引用
☐ 每个错误码都有对应的前端行为
☐ UI 映射覆盖了所有 API 响应字段（如有 UI 设计稿）
☐ 调用流程图使用 mermaid（flowchart 或 sequenceDiagram），简要且不超过 10 个节点
☐ 文档中不包含任何后端内部编号（B-03、S-01 等）
☐ 请求参数和响应字段均有标准 JSON 示例 + 表格说明
☐ INDEX.md 包含整体调用流程图（ASCII 字符画，一目了然）
☐ INDEX.md 包含常见问题章节，预判前端可能产生的业务逻辑疑问

【需人工判断】
☐ 调用时序是否正确（前端是否能在该时机调用）
☐ UI 映射是否准确（字段含义与 UI 元素匹配）
☐ 错误处理行为是否符合产品要求
☐ 是否遗漏了需要前端轮询或 WebSocket 的场景
```

### 后续行动选择

```text
🚀 后续行动选择
━━━━━━━━━━━━━━━━

前端集成指南已生成。请选择后续行动：

1. 📁 落盘归档
   将文档保存到需求目录，注册到需求管理系统

2. 📋 生成测试计划
   使用 test-planner 技能基于 API 设计生成接口测试计划

3. ⏭️ 跳过
   不进行后续操作，结束流程

请选择 [1/2/3]：
```

---

## 与 api-design 的衔接

### 作为后续步骤推荐

api-design 完成 API 设计后，在"后续行动选择"中推荐：

```
📖 生成前端集成指南
   使用 frontend-api-guide 技能为前端生成可直接编码的调用流程文档
```

### 输入输出关系

| api-design 产出 | frontend-api-guide 使用方式 |
|-----------------|---------------------------|
| 接口列表 + 契约 | 作为 API 清单和调用序列的基础 |
| 错误码定义 | 作为错误处理速查表的输入 |
| 请求/响应示例 | 作为 UI 映射的数据来源 |
| 时序图 | 作为调用流程图的参考 |

## 需求管理集成

当项目配置了 `.requirements/config` 时，落盘后自动执行集成操作：

```bash
req update {REQ-NNN} \
  --docs add frontend-guide/INDEX.md,frontend_guide --changelog "完成前端集成指南"
```

| 产出物 | 存储路径 | docs 类型 |
|--------|----------|-----------|
| 前端集成指南（总览） | `frontend-guide/INDEX.md` | `frontend_guide` |
| 前端 API 文档 | `frontend-guide/api/{module}.md` | `frontend_guide` |
| 前端调用流程 | `frontend-guide/flow/{scene}.md` | `frontend_guide` |

---

## 反模式

### 内容层面
- ❌ **只列接口清单**：前端需要的是"什么时候调什么接口"，不是接口列表
- ❌ **忽略错误处理**：每个错误码都必须有明确的前端行为
- ❌ **遗漏空状态**：API 返回空数据时 UI 显示什么，必须定义
- ❌ **不标注触发时机**：只说"调用 GET /users"不说什么时候调

### 格式层面
- ❌ **缺少流程图**：纯文字描述调用序列不直观，必须配简要的 mermaid 流程图或时序图
- ❌ **API 与流程混入**：API 文档里写调用流程，或流程文档里嵌入 JSON 契约细节
- ❌ **UI 映射模糊**："显示用户信息"不是映射，必须精确到字段
- ❌ **错误处理写"提示错误"**：必须给出具体的提示文案

### 流程层面
- ❌ **跳过场景提取**：直接从 API 列表生成文档，缺少业务流程上下文
- ❌ **不确认直接输出**：场景提取后需用户确认，避免遗漏

### 独立性层面
- ❌ **引用后端内部编号**：文档中出现 "B-03"、"S-01" 等后端设计文档编号，前端根本不知道这些是什么。必须用自然语言直接说明
- ❌ **依赖外部文档**：文档包含"详见设计文档第X节"等跳转引用，前端拿到的应是自包含的独立指南
- ❌ **暴露后端内部概念**：不区分前端是否关心，如 "TAPD 回调接口 B-05 前端不直接调用" 应改为描述前端需要知道的事：OAuth 流程中前端只需跳转授权页，回调由后端处理

### 边界层面
- ❌ **包含前端代码**：文档中出现 JS/TS/React/Vue 等任何前端代码。只描述接口信息，不教前端怎么写代码
- ❌ **指挥前端实现**：文档说"你应该用 useState 管理状态"、"用 axios 发请求"。前端团队有自己的技术选型和编码规范，只需告诉他们接口契约即可