test-backend/.claude/contract.md

01 — 接口契约

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

---

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

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

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

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

铁律：

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

分仓库时契约放哪

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

---

返回格式（不变式）

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

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

---

分页格式（不变式）

{ "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. 更新本文件的映射表（如有新增状态值/字段差异）