API-First 模块化开发框架

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

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

三层架构模型

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

层级判断规则

如果任务涉及…	归属层	处理方式
页面布局、组件、样式、用户交互	前端	前端开发
数据库操作、算法、业务规则	后端API包	后端开发
多个API的组合调用、数据聚合	中间层	全栈开发
前后端数据格式不匹配	集成问题	先查API文档契约

后端 API 包标准开发流程（5 步闭环）

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

开发 ──► Checkfix ──► 封装 ──► API端点 ──► API文档

开发 (Implement) — 实现核心业务逻辑，编写单元测试，遵循单一职责
Checkfix 闭环 — 执行技术栈对应的 lint/build 检查，失败则修复并复跑直至通过
封装 (Encapsulate) — 封装为独立模块/类/包，明确输入输出接口，隐藏内部实现
API 暴露 (Expose) — 创建 API 端点（REST/GraphQL/RPC/WebSocket/SSE），统一响应格式，添加输入验证、错误处理、鉴权
API 文档 (Document) — 按标准模板生成文档，文档是前端开发的唯一依据，必须与代码同步

API 文档标准模板

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

# [模块名] API 文档

> 最后更新: [YYYY-MM-DD] | 版本: v1.0

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

## Base URL
`/api/v1/[module-name]`

## 认证方式
[Bearer Token / API Key / Session / 无认证]

## 端点列表
| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|

## 详细接口

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

#### 请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|

#### 响应格式
**成功 (200)**:
{ "code": 0, "data": {...}, "message": "success" }

**失败 (4xx/5xx)**:
{ "code": 40001, "data": null, "message": "参数错误：field1 不能为空" }

#### 错误码
| 错误码 | HTTP状态码 | 含义 | 处理建议 |
|--------|-----------|------|----------|

#### 调用示例
[curl 示例]

## 特殊协议
[WebSocket / SSE / 长轮询等非标准协议的连接方式、事件格式、重连策略]

前端开发规范

允许：页面渲染、组件开发、调用后端 API（依据文档）、前端状态管理、用户交互处理、错误展示

禁止：在前端实现业务逻辑、直接连接数据库、绕过 API 层、硬编码本应由后端提供的数据

前端统一封装 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 规范

仅在以下场景存在：

场景	职责	示例
多API聚合	组合多个后端API结果	Dashboard 聚合用户+订单+统计
协议转换	gRPC/消息队列 → REST/WebSocket	Kafka 推送 → SSE
鉴权网关	统一 Token 校验、权限检查	API Gateway
数据适配	针对特定前端裁剪数据	移动端精简字段

禁止：重复后端已有逻辑、中间层直连数据库、把中间层写成"超级后端"。

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

收到涉及多层的开发/调试需求时，必须执行：

分解流程

收到跨层需求
    │
    ▼
Step 1: 层级识别 — 该任务涉及哪些层？（后端/前端/中间层）
    │
    ▼
Step 2: 按 API 边界拆分为有序子任务
    │
    ▼
Step 3: 严格按序执行 — 后端先行 → 文档产出 → 前端消费 → 集成验证

典型分解示例

"增加 SSE 流式输出功能"：

[后端] 创建 SSE 端点 API 包 → Checkfix 通过
[文档] 编写 SSE 接口文档 → docs/api/sse-stream.md
[前端] EventSource 调用 + 流式 UI 渲染 + 断线重连
[集成] 端到端测试

"增加用户认证功能"：

[后端] 用户认证 API 包（注册/登录/Token刷新/登出）
[后端] 认证中间件包（Token校验/权限检查）
[文档] 认证接口文档
[前端] 登录/注册页面 + Token管理 + 路由守卫
[中间层] 认证中间件集成到网关
[集成] 完整认证流程测试

Debug 边界规则

分层定位

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

Debug 禁止行为

禁止	原因
改前端代码来绕过后端 Bug	治标不治本
改后端 API 契约来迁就前端 Bug	影响所有调用方，破坏契约
在前端做本应在后端的数据校验	违反职责分离
不确认问题归属层就动手	在错误层浪费时间

与 PRD / Ralph 的协作

User Story 应按 API 包粒度拆分：

正确：

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

错误：

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

适用边界

适用：前后端分离项目、全栈项目（SSR+API）、微服务/微前端架构、多人/多AI协作项目

不强制适用：纯脚本/CLI、纯数据处理/ETL、嵌入式/系统级、原型验证阶段（可简化但保留 API 文档习惯）

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

api-first-modular