API与数据契约设计

---
name: api-and-data-contract-design
description: 设计并固化前后端之间、服务之间、以及数据层的契约（API、事件、Schema、共享类型），保证"接口不漂、数据不烂"。产出/更新 `模块与契约/`。
---

# API与数据契约设计

## 何时使用

- 变更涉及新增 / 修改 API、事件、Webhook。
- 变更涉及数据库 Schema、字段语义、数据生命周期。
- 前后端 / 多服务需要"先把接口说死再各写各的"。
- 评审中发现契约文档与实现不一致。

## 前置

- 必读 `.agents/rules/API与兼容性规则.md`、`数据与迁移规则.md`、`架构边界.md`。
- 必读 `.agents/context/API与事件契约.md`、`数据模型与存储.md`。
- 变更已有 `影响分析.md` + `实现计划.md`。

## 输入

- `变更/<id>/实现计划.md`
- 现有 `模块与契约/API/`、`模块与契约/数据/`、`模块与契约/后端/`

## 步骤

### A. API 契约

1. 明确**风格**：REST / RPC / GraphQL / 事件驱动——沿用以有的，不要为单个变更换风格。
2. 定义每个端点：方法、路径、认证要求、请求体、响应体、错误码、幂等性、限流。
3. 定义**兼容性策略**：是否破坏性变更？若是：
   - 是否加版本（`/v2`、header 版本）？
   - 是否走"双写 / 双读 → 灰度 → 下线旧接口"的过渡？
   - 弃用时是否给了 deprecation 期限与通知？
4. 给出**请求 / 响应示例**（真实可粘贴的 JSON）。
5. 明确**错误语义**：与 `模块与契约/后端/错误码与异常约定.md` 对齐，禁止自定义散装错误串。

### B. 事件 / Webhook 契约

1. 事件名、触发时机、payload schema、版本、投递语义（至少一次 / 精确一次）、重试与死信。
2. 消费方的幂等要求。

### C. 数据契约

1. 表 / 集合 / 索引的字段、类型、可空、默认值、约束。
2. **迁移方案**：向前迁移（migrate）与回滚（rollback）脚本都要有；大表改动需评估锁与耗时。
3. **数据生命周期**：写入 → 更新 → 归档 → 删除（含软删 / 硬删 / 合规删除）。
4. **数据修复规范**：如需历史数据回填，写明分批策略、幂等、可中止。

## 输出

- 更新 `模块与契约/API/API目录.md`（或对应细分文件）
- 更新 `模块与契约/数据/数据模型.md`、`Schema迁移.md`（如涉及）
- 更新 `模块与契约/后端/任务与事件.md`（如涉及）
- 如需重大取舍 → 写一条 ADR（`.agents/templates/ADR.md`）

## 检查清单

- [ ] 每个端点都有完整请求 / 响应示例（不是"略"）。
- [ ] 破坏性变更有版本或过渡方案，且写明弃用期限。
- [ ] 错误码与既有约定一致。
- [ ] Schema 变更同时提供 migrate 与 rollback。
- [ ] 迁移评估了数据量、锁、耗时、失败可恢复性。
- [ ] 消费方幂等要求已写明。
- [ ] 契约文档与 `.agents/context/API与事件契约.md` 同步。

## 边界与禁止

- **禁止**只改代码不改契约文档。
- **禁止**在没有迁移与回滚方案的情况下改生产表结构。
- **禁止**在客户端与服务端约定之外私自定义字段语义。
- 涉及**私人数据 / 密钥 / 合规数据**时，必须对照 `.agents/rules/安全与隐私规则.md`，并提示需安全评审。