# API_CONTRACT 冲突提报模板（可复用）

> 版本：v1.0（2026-04-28）
> 适用范围：`PRD/TASK_AGENT_READY*.md`、模块级 Agent 执行提示词、代码交付回执

---

## 1) 目的

当实现与 `Project/fonrey/TECH_STACK/API_CONTRACT.md` 存在差异时，统一使用本模板提报，确保：

- 冲突可审计（知道“哪里不一致”）
- 影响可评估（前端/后端/测试/数据）
- 处置可回滚（不阻断主干稳定性）

> 约束：**不得擅自修改 API_CONTRACT**。先按契约实现；若确需调整，必须先提报并待确认。

---

## 2) 可直接粘贴到任务提示词的交付片段

将以下段落放入每条任务的 `【交付格式】`：

```md
- API 契约核对清单（逐条对应 API_CONTRACT：已对齐/偏差项）
- API 契约冲突说明（如无冲突写“无”）
  - 冲突接口（Method + Path）
  - 当前契约要求（来自 API_CONTRACT）
  - 实现差异 / 建议改动
  - 影响面（前端/后端/测试/存量数据）
  - 回滚方案
```

---

## 3) API 契约冲突提报单（标准格式）

> 若“无冲突”，填写：`API 契约冲突说明：无`

```md
### API 契约冲突提报单
- 任务ID：<US-XXX>
- 关联模块：<登录/楼盘/房源/客源/...>
- 冲突接口（Method + Path）：
  - <GET|POST|PUT|PATCH|DELETE> <path>

- 当前契约要求（来自 API_CONTRACT）：
  - 请求参数：<必填/可选/类型/约束>
  - 响应结构：<字段、类型、是否可空>
  - 错误码：<code + 含义>

- 实现差异 / 建议改动：
  - 差异点1：<描述>
  - 差异点2：<描述>
  - 建议：<保持契约 / 调整契约（需审批）>

- 影响面：
  - 前端：<页面/组件/调用方>
  - 后端：<视图/序列化器/服务层>
  - 测试：<需新增/需修正的用例>
  - 存量数据：<是否需要迁移/回填>

- 风险等级：<低/中/高>
- 临时兜底方案：<可选>
- 回滚方案：<可执行步骤>
- 需要确认人：<产品/后端负责人/前端负责人>
- 期望确认时限：<YYYY-MM-DD HH:mm>
```

---

## 4) 最小核对清单（提交前自检）

- [ ] 已逐条对照 API_CONTRACT 的路径/方法/参数/响应/错误码
- [ ] 已明确“无冲突”或填写完整冲突提报单
- [ ] 已写明影响面（前端/后端/测试/数据）
- [ ] 已给出可执行回滚方案
- [ ] 未直接修改 API_CONTRACT 文档内容