---
name: api-implement
description: 阶段 4。批量实现 status=confirmed 的 API 业务契约。读 docs/api-contracts/ + openapi/openapi.yaml,产出 backend/src/* + migrations + tests。跑 make backend-verify 全过才算完成。当用户说"实现 API"、"开始写后端"、"把契约落地"时触发。前置:至少一个 docs/api-contracts/*.yaml status=confirmed。
---

# 阶段 4:批量实现后端

## 前置检查

```bash
ls docs/api-contracts/*.yaml
test -f openapi/openapi.yaml
```

逐个读 status:

- 没有 confirmed 的契约 → 拒绝,提示用户走 api-design
- 部分 confirmed → 列出可实现 vs 跳过
- 全部 confirmed → 列清单等用户确认范围

```
找到 N 个可实现的契约:
- registerUser.yaml      (confirmed)
- loginUser.yaml         (confirmed)
- createProject.yaml     (confirmed)
- ...

跳过(状态不对):
- deleteUser.yaml        (draft)
- bulkUpdateTasks.yaml   (draft)

要全部实现?或挑选某几个先做?
```

---

## 工作流程

### 1. 读所有相关文件

- CLAUDE.md(全局约定)
- docs/domain/*.md(实体定义,理解字段含义)
- openapi/openapi.yaml(结构契约)
- docs/api-contracts/*.yaml(业务契约,核心实现依据)
- 现有 backend/src/* 代码
- view `implementation-rules.md`
- view `verify-and-report.md`

### 2. 按层批次推进

**不要"按接口逐个完成"**,要**按层批次**。理由:同层风格、抽象级别一致,跨接口复用机会能被发现。

```
批次 1:DB migrations
  - 为所有 confirmed 接口涉及的表,设计 migration
  - 列出 SQL → 用户审 → 跑

批次 2:核心基础设施
  - errors.py(错误码 + ErrorEnvelope)
  - auth.py(Bearer 鉴权中间件)
  - audit.py(审计服务)
  - event_bus.py(事件发布)
  - 如已存在则复用

批次 3:Repository 层
  - 每个实体一个 repo 文件
  - 只 CRUD,不含业务逻辑
  - 软删默认过滤

批次 4:Service 层(核心,占总实现时间的 60%)
  - 每条 R 规则代码加 # R<n> 注释
  - 每个 side_effect 真实落地
  - 错误抛 BusinessError(code=...)
  - 实现一个 service 跑一次它的单测

批次 5:Handler 层
  - 只做解析输入 → 调 service → 包装响应
  - 错误统一捕获 → ErrorEnvelope

批次 6:测试
  - 每个 test_case 一个独立函数
  - 命名 test_<category>_<scenario>
  - 跑 unit + contract test (schemathesis)

批次 7:Verify
  - make backend-verify 全过
```

每个批次完成后**简短**报告进度,不等用户确认,继续下一个。

### 3. 严格映射 schema → 代码

详细规则在 `implementation-rules.md`,关键:

- **每条 R** 在 service 层有 `# R<n>` 注释
- **每个 side_effect** 真实落地
- **每个 errors 条目** 对应 raise BusinessError(code=...)
- **每个 test_case** 一个测试函数
- **observability.log_fields** 真实出现在 logger 调用
- **observability.metrics** 真实 emit
- 不修改 `do_not_touch` 文件

### 4. 跑 verify

详细规则在 `verify-and-report.md`。

```
make backend-verify
```

任何一项失败 → 修复 → 再跑。不允许"剩下让用户修"。

### 5. 更新契约状态

每个成功实现的接口,把对应 yaml 的:

```yaml
status: confirmed → implemented
implemented_at: 2026-05-21
```

### 6. 输出批量实现总结

按 `verify-and-report.md` 格式,**必须**包含:

- 改动文件总览(表格,带行数)
- 每接口的 R 规则代码位置
- 每接口的 side_effect 落地位置
- 测试覆盖矩阵
- verify 结果
- 偏离 schema 的地方(主动报告)
- 实现中发现的 schema 问题
- 状态变更清单

### 7. 提示下一步

```
✅ N 个 API 已实现,契约状态置为 implemented。

下一步选一:
- frontend-wire skill:把前端 mock 切到真接口
- 启动后端服务手动 smoke test
```

---

## 发现 schema 问题(实现中)

立即停下,**不要自己看着办**。

```
⚠️ 实现 createTask 时发现 schema 问题:

问题:R5 说 Project 内未完结任务上限 1000,但 errors 里没有 PROJECT_TASK_LIMIT 的 422 条目。
     业务契约 yaml 自相矛盾。

请决定:
A. 补 errors.422.PROJECT_TASK_LIMIT
B. 取消 R5
C. 其他

需要回到 api-design 修订,我会把对应 yaml status 改回 draft。
```

---

## 严禁

详见 `implementation-rules.md` 的严禁清单。最关键的:

1. ❌ 修改契约的业务字段
2. ❌ 修改 openapi.yaml
3. ❌ 修改 docs/domain/*
4. ❌ do_not_touch 文件
5. ❌ 跳过 test_case
6. ❌ 跳过 verify
7. ❌ 偷偷"优化"无关代码
8. ❌ pip install 新依赖不询问