Claude_skill_pool / rules

---
description: API-First 模块化开发方法论 — 适用于所有涉及前后端的开发与调试任务
globs: 
alwaysApply: false
---

# API-First 模块化开发框架

当项目涉及前后端分离、全栈开发、或任何需要多层协作的场景时，本规则自动生效。

## 核心架构：三层分离

```
前端层（Frontend）          中间层（Glue/BFF）         后端API包（Backend）
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│ 页面 & 组件   │  ←API→  │ 跨API编排     │  ←API→  │ 独立业务模块  │
│ 只调API+渲染  │          │ 数据聚合适配   │          │ 内聚逻辑封装  │
│ 不含业务逻辑  │          │ 耦合逻辑处理   │          │ 对外只暴露API │
└──────────────┘          └──────────────┘          └──────────────┘
```

## 后端 API 包标准开发流程

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

```
开发（Implement） → Checkfix（Lint/Build） → 封装（Module/Class） → API暴露（Endpoint） → API文档（Doc）
```

- **一个 API 包只做一件事**，对外只暴露 API 端点
- 完成开发后必须执行 Checkfix 闭环（参考 code-debugger 技术栈检查表）
- 封装为独立模块后暴露 REST/GraphQL/RPC 端点
- 必须生成 API 文档（见下方模板），前端开发者仅依据此文档调用

## API 文档标准模板

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

```markdown
# [模块名] API 文档

## 端点概览
| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| POST | /api/v1/xxx | 描述 | Bearer Token |

## 详细接口

### [接口名称]
- **路径**: `POST /api/v1/xxx`
- **描述**: 功能说明

**请求参数**:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| field | body | string | 是 | 描述 |

**响应格式**:
成功 (200):
```json
{ "code": 0, "data": { ... }, "message": "success" }
```
失败 (4xx/5xx):
```json
{ "code": 错误码, "data": null, "message": "错误描述" }
```

**错误码**:
| 错误码 | 含义 | 处理建议 |
|--------|------|----------|

**调用示例**:
```bash
curl -X POST .../api/v1/xxx -H "Content-Type: application/json" -d '{...}'
```
```

## 前端开发规范

- 前端只负责：页面渲染 + 调用后端 API + 用户交互
- 业务逻辑全部在后端 API 包内，前端不重复实现
- 依据 API 文档开发，可与后端并行

## 中间层/全栈规范

- 只处理多个 API 包之间的编排和聚合
- 只处理前端特殊需求的数据适配（BFF 模式）
- 不重复实现后端已有的业务逻辑

## 跨层任务自动分解协议

当收到涉及多个层级的开发/debug 需求时（如"增加 SSE 流式输出"），必须按以下协议分解：

### Step 1: 层级识别
判断任务涉及哪些层：后端？前端？中间层？

### Step 2: 按 API 边界拆分子任务

```
子任务 1 [后端]: 开发 API 包（开发→Checkfix→封装→API端点→API文档）
子任务 2 [API文档]: 确保 API 契约清晰（请求/响应/错误码/示例）
子任务 3 [前端]: 依据 API 文档实现页面功能
子任务 4 [集成]: 验证前后端契约一致性
```

### Step 3: 严格按序执行
后端 API 包先行 → API 文档产出 → 前端/中间层消费 → 集成验证

## Debug 边界规则

| Bug 表现 | 归属层 | Debug 范围 | 禁止行为 |
|----------|--------|-----------|----------|
| API 返回错误数据 | 后端 | 只查 API 包内部逻辑 | 不改前端来"绕过" |
| 页面不显示/显示异常 | 前端 | 只查页面逻辑+API调用参数 | 不改后端API契约来迁就 |
| 多API协作异常 | 中间层 | 查编排逻辑+各API契约一致性 | 不进入单个API包内部改逻辑 |
| 前后端数据不匹配 | 集成 | 对照API文档检查契约一致性 | 先确定谁违反了契约再改 |

## 与其他 Skill 的协作

- **ai-spec**: 生成技术规格时默认采用本框架的三层分离架构
- **code-debugger**: Debug 时先判断模块类型（前端/后端API包/中间层），按边界规则定位
- **debug-ui**: 天然对应前端层，只处理页面和 API 调用
- **prd / ralph**: 拆分 User Story 时按 API 包粒度拆分（后端API包 → API文档 → 前端消费）