# 01 — 接口契约

> **这是前后端共享的唯一真相来源。** 修改本文件 = 修改协议，必须同步更新所有端。

---

## 契约生命周期（任务拆分时决定）

契约由**任务拆分时先开工的那一端**负责起草。这是任务产出物之一，不是额外工作。

```
任务拆分阶段：
  ┌─ 任务A：后端-用户管理CRUD ──→ 产出：接口契约（后端起草）
  │                                        + 后端代码
  │
  └─ 任务B：前端-用户管理页面 ──→ 拿到契约后对接

反过来：
  ┌─ 任务A：前端-首页改版 ──→ 产出：接口契约（前端起草）
  │                                   + 前端页面
  │
  └─ 任务B：后端-首页数据接口 ──→ 按契约实现
```

**铁律**：
- 拆分任务时明确标注：**本任务包含接口契约起草**
- 契约随任务一起交付，不单独走审批
- 后开工的一方拿到契约后，发现问题直接跟起草方沟通修改
- 联调时对照本文件，不一致的以本文件为准

### 分仓库时契约放哪

```
Monorepo（推荐）：        分仓库：
项目根/                  后端仓库/              前端仓库/
└── rules/               ├── rules/              ├── rules/
    └── 01-接口契约.md    │   └── 01-接口契约.md  │   └── 01-接口契约.md
                          ← git submodule 引用同一份 →
```

---

## 返回格式（不变式）

```json
// ✅ 唯一正确格式
{ "code": 200, "message": "success", "data": { ... } }
{ "code": 500, "message": "错误原因", "data": null }

// ❌ 永远不许出现
return data;                           // 裸对象
return "ok";                           // 裸字符串
{ "success": true, "result": {...} }   // 自造格式
```

---

## 分页格式（不变式）

```json
{ "list": [...], "total": 100, "pages": 10, "current": 1, "size": 10 }
```

---

## 接口命名约定

| 前缀 | 用途 | 示例 |
|------|------|------|
| `/admin/**` | 管理后台 | `/admin/user/list` |
| `/app/**` | 移动端/H5/小程序 | `/app/task/list` |
| `/auth/**` | 登录注册（共享） | `/auth/login` |
| `/open/**` | 对外开放接口 | `/open/callback` |

---

## 状态值映射表

**← 改这里 = 改协议，必须同步后端 + 所有前端。**

| 含义 | 后端值 | 前端显示 | 前端 CSS 类 |
|------|--------|----------|------------|
| [状态1] | [值] | [文字] | [class] |
| [状态2] | [值] | [文字] | [class] |

---

## 字段名桥接表

同一个概念在不同端字段名不同时，在此登记：

| 概念 | 后端字段 | 前端A字段 | 前端B字段 |
|------|----------|-----------|-----------|
| | | | |

---

## 契约同步铁律

```
改后端接口 → grep 所有前端 → 逐个同步 → 两端都通过才算完成

步骤：
1. 改之前：grep -r "接口路径" 所有前端目录/
2. 改后端 → 编译通过
3. 逐个改前端 → 构建通过
4. 更新本文件的映射表（如有新增状态值/字段差异）
```