API First Modular

API-First 模块化开发框架

你现在遵循 API-First 模块化开发方法论。这是一套适用于所有 AI 辅助开发场景的基础架构规范，确保代码的可维护性、可调试性和前后端解耦。

核心理念

后端每个功能 = 一个独立 API 包。前端只调 API + 渲染页面。全栈只做多个 API 包之间的编排。

这不是建议，是强制约束。所有涉及前后端的开发和调试任务都必须遵循此框架。

一、三层架构模型

┌─────────────────────────────────────────────────────────────────────┐
│                       项目整体架构                                   │
│                                                                     │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐        │
│  │  前端层      │     │  中间层      │     │  后端API包   │        │
│  │  Frontend    │◄───►│  Glue / BFF  │◄───►│  Backend     │        │
│  │              │     │              │     │              │        │
│  │ 职责:        │     │ 职责:        │     │ 职责:        │        │
│  │ • 页面渲染   │     │ • 跨API编排  │     │ • 业务逻辑   │        │
│  │ • 用户交互   │     │ • 数据聚合   │     │ • 数据处理   │        │
│  │ • API调用    │     │ • 适配转换   │     │ • API暴露    │        │
│  │ • 状态管理   │     │ • 鉴权中继   │     │ • API文档    │        │
│  │              │     │              │     │              │        │
│  │ 禁止:        │     │ 禁止:        │     │ 禁止:        │        │
│  │ • 业务逻辑   │     │ • 重复后端   │     │ • 关心前端   │        │
│  │ • 直连数据库 │     │   已有逻辑   │     │   如何渲染   │        │
│  └──────────────┘     └──────────────┘     └──────────────┘        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

层级判断规则

二、后端 API 包标准开发流程

每个后端功能必须走完以下 5 步闭环：

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 1.开发   │───►│2.Checkfix│───►│ 3.封装   │───►│ 4.API    │───►│5.API文档 │
│ Implement│    │Lint/Build│    │Module/Cls│    │Endpoint  │    │Document  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘

Step 1: 开发 (Implement)

• 实现核心业务逻辑
• 编写单元测试
• 遵循单一职责原则

Step 2: Checkfix 闭环

• 根据技术栈执行自动检查（参考 code-debugger 的技术栈检查表）
• 失败则修复并复跑，直至通过
• 结果记录到 .debug 文档

Step 3: 封装 (Encapsulate)

• 将逻辑封装为独立模块/类/包
• 明确模块的输入输出接口
• 对外隐藏内部实现细节

Step 4: API 暴露 (Expose API)

• 创建 API 端点（REST / GraphQL / RPC / WebSocket / SSE）
• 统一响应格式
• 添加输入验证、错误处理、鉴权中间件

Step 5: API 文档 (Document)

• 按下方模板生成 API 文档
• 文档是前端开发的唯一依据
• 文档与代码必须同步更新

三、API 文档标准模板

每个 API 包完成后，必须在 docs/api/ 或模块目录下生成以下文档：

# [模块名] API 文档

> 最后更新: [YYYY-MM-DD]
> 版本: v1.0
> 维护者: [开发者/AI]

## 概览

[模块的业务功能简介，1-2 句话]

## Base URL

`/api/v1/[module-name]`

## 认证方式

[Bearer Token / API Key / Session / 无认证]

## 端点列表

| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| GET | /api/v1/xxx | 查询XXX | 是 |
| POST | /api/v1/xxx | 创建XXX | 是 |

## 详细接口

### 1. [接口名称]

- **路径**: `[METHOD] /api/v1/xxx`
- **功能**: [功能描述]
- **认证**: [是/否]

#### 请求参数

**Headers**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer {token} |

**Query Parameters** (GET) / **Request Body** (POST/PUT):
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| field1 | string | 是 | - | 描述 |
| field2 | number | 否 | 10 | 描述 |

#### 响应格式

**成功 (200)**:
```json
{
  "code": 0,
  "data": {
    "id": "xxx",
    "field1": "value"
  },
  "message": "success"
}

失败 (4xx/5xx):

{
  "code": 40001,
  "data": null,
  "message": "参数错误：field1 不能为空"
}

错误码

调用示例

curl -X POST https://host/api/v1/xxx 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {token}" 
  -d '{"field1": "value"}'

特殊协议

[如有 WebSocket / SSE / 长轮询等非标准 HTTP 协议，在此描述连接方式、事件格式、重连策略]

---

## 四、前端开发规范

### 允许做的事
- 页面渲染和组件开发
- 调用后端 API（依据 API 文档）
- 前端状态管理（UI 状态、表单状态）
- 用户交互处理（事件绑定、路由）
- 错误展示（将 API 错误码翻译为用户友好提示）

### 禁止做的事
- 在前端实现业务逻辑（计算、校验规则应在后端）
- 直接连接数据库
- 绕过 API 层直接访问后端内部接口
- 在前端硬编码本应由后端提供的配置/数据

### 前端调用 API 的标准模式

```typescript
// 推荐：封装统一的 API 调用层
// src/api/[module-name].ts

import { request } from '@/utils/request'; // 统一请求工具

export const moduleNameApi = {
  getList: (params: ListParams) => request.get('/api/v1/xxx', { params }),
  create: (data: CreateData) => request.post('/api/v1/xxx', data),
  update: (id: string, data: UpdateData) => request.put(`/api/v1/xxx/${id}`, data),
  delete: (id: string) => request.delete(`/api/v1/xxx/${id}`),
};

五、中间层 / 全栈规范

中间层（也叫 BFF - Backend For Frontend）只在以下场景存在：

禁止做的事

• 重复实现后端 API 包内已有的业务逻辑
• 在中间层做数据库直连操作
• 把中间层写成一个"超级后端"

六、跨层任务自动分解协议（核心）

这是本框架最关键的部分。 当 AI 收到一个涉及多个层级的开发或调试需求时，必须执行以下分解协议：

分解流程

┌────────────────────────────────────────────────┐
│           收到跨层开发/调试需求                   │
│   例如: "增加前端 SSE 流式输出功能"              │
└──────────────────────┬─────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────┐
│  Step 1: 层级识别                               │
│  该任务涉及哪些层？                              │
│  → 后端 ✓ (SSE 端点)                           │
│  → 前端 ✓ (EventSource 消费 + UI 渲染)         │
│  → 中间层 ? (可能需要代理/CORS 配置)            │
└──────────────────────┬─────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────┐
│  Step 2: 按 API 边界拆分为有序子任务             │
│                                                 │
│  ① [后端] 开发 SSE API 包                       │
│     开发 → Checkfix → 封装 → SSE端点 → API文档  │
│                                                 │
│  ② [API文档] 编写 SSE 接口文档                   │
│     事件格式、数据结构、重连策略、错误处理        │
│                                                 │
│  ③ [前端] 依据 API 文档实现前端消费               │
│     EventSource/fetch → 流式渲染 → 错误处理     │
│                                                 │
│  ④ [集成] 端到端验证                             │
│     前后端契约一致性 → 异常场景 → 性能          │
└──────────────────────┬─────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────┐
│  Step 3: 严格按序执行                            │
│  后端先行 → 文档产出 → 前端消费 → 集成验证      │
│  每个子任务内部遵循各层的开发规范                │
└────────────────────────────────────────────────┘

典型跨层场景分解示例

场景 1: "增加 SSE 流式输出功能"

场景 2: "增加用户认证功能"

场景 3: "Dashboard 数据加载太慢"（性能调试）

七、Debug 边界规则

分层定位原则

Bug 出现
    │
    ├─ API 返回错误数据？ ──────► 后端 Debug（只查 API 包内部）
    │                              修复后 API 契约不变
    │
    ├─ 页面显示异常？ ──────────► 前端 Debug（只查页面 + API调用参数）
    │                              确认 API 返回数据是否正确
    │
    ├─ 多 API 协作异常？ ──────► 中间层 Debug（查编排逻辑）
    │                              各 API 单独调用是否正常？
    │
    └─ 前后端数据不匹配？ ─────► 契约 Debug（对照 API 文档）
                                   谁违反了契约？改违反方

Debug 禁止行为

.debug 文档扩展

在使用 code-debugger 时，.debug 文档的元信息中应增加：

## 元信息

| 字段 | 值 |
|------|-----|
| **模块名称** | [Module Name] |
| **模块类型** | 前端模块 / 后端API包 / 中间层 / 全栈集成 |
| **API文档路径** | （后端API包时填写）docs/api/xxx.md |
| **API契约版本** | v1.0 |

八、与 PRD / Ralph 的协作

当使用 PRD + Ralph 自主循环开发时，User Story 应按本框架拆分：

正确的 Story 拆分（API 包粒度）

US-001: [后端] 创建用户认证 API 包（注册/登录端点 + 单元测试）
US-002: [后端] 创建认证中间件包（Token校验 + 权限检查）  
US-003: [文档] 编写认证模块 API 文档
US-004: [前端] 实现登录/注册页面（依据 API 文档调用）
US-005: [前端] 实现路由守卫和 Token 自动刷新
US-006: [集成] 端到端认证流程验证

错误的 Story 拆分

US-001: 实现用户认证功能（包括前后端）  ← 太大，跨层
US-002: 优化认证体验  ← 太模糊，不可验证

九、适用边界

本框架适用于

• 前后端分离项目（SPA + API）
• 全栈项目（SSR + API）
• 微服务/微前端架构
• 任何需要多人/多AI协作的项目

本框架不强制适用于

• 纯脚本/CLI 工具（无前后端概念）
• 纯数据处理/ETL 管道
• 嵌入式/系统级编程
• 原型验证/快速实验阶段（可简化流程但保留 API 文档习惯）

遇到不适用的场景时，不要强行套用，但可以借鉴"模块封装 + 接口文档"的核心思想。