2.3 KiB
2.3 KiB
API_CONTRACT 冲突提报模板（可复用）
版本：v1.0（2026-04-28） 适用范围：
PRD/TASK_AGENT_READY*.md、模块级 Agent 执行提示词、代码交付回执
1) 目的
当实现与 Project/fonrey/TECH_STACK/API_CONTRACT.md 存在差异时，统一使用本模板提报，确保：
- 冲突可审计（知道“哪里不一致”）
- 影响可评估（前端/后端/测试/数据）
- 处置可回滚（不阻断主干稳定性）
约束：不得擅自修改 API_CONTRACT。先按契约实现；若确需调整，必须先提报并待确认。
2) 可直接粘贴到任务提示词的交付片段
将以下段落放入每条任务的 【交付格式】：
- API 契约核对清单（逐条对应 API_CONTRACT：已对齐/偏差项）
- API 契约冲突说明（如无冲突写“无”）
- 冲突接口（Method + Path）
- 当前契约要求（来自 API_CONTRACT）
- 实现差异 / 建议改动
- 影响面（前端/后端/测试/存量数据）
- 回滚方案
3) API 契约冲突提报单（标准格式）
若“无冲突”，填写：
API 契约冲突说明：无
### 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 文档内容