api-first-modular

API-First 模块化开发框架

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

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

---

三层架构模型

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

层级判断规则

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

---

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

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

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

1. 开发 (Implement) — 实现核心业务逻辑，编写单元测试，遵循单一职责
2. Checkfix 闭环 — 执行技术栈对应的 lint/build 检查，失败则修复并复跑直至通过
3. 封装 (Encapsulate) — 封装为独立模块/类/包，明确输入输出接口，隐藏内部实现
4. API 暴露 (Expose) — 创建 API 端点（REST/GraphQL/RPC/WebSocket/SSE），统一响应格式，添加输入验证、错误处理、鉴权
5. 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 / 长轮询等非标准协议的连接方式、事件格式、重连策略]