# 接口一致性检查规范（code-audit）

## 一、背景与目标

本项目为多端共用后端架构，多个前端调用同一套后端接口。修改代码时若只为 A 端调整接口（参数、返回结构、校验规则、权限等），容易把同调用的 B 端改坏。

本规范定义「接口一致性检查」的触发条件、检查项、执行流程与产出要求。

- 端（调用方）清单不固定枚举，以 `./project-structure.md` 当时登记的目录为准
- 网关前缀口径见 `./java-code-review.md` 第 2 条：管理端 `/api`，面客端 `/c-api`

核心原则：**改接口先找全调用方，破坏性变更必须全端适配。**

## 二、触发条件

出现以下任一情形即执行本检查：

1. 后端新增/修改/删除 Controller 接口（路径、入参 DTO、返回 VO、校验注解、权限注解、错误码）
2. 修改被多个接口引用的公共 DTO / VO / 枚举 / Service（按字段与方法引用搜索确认影响面）
3. 某一端前端修改了公共请求封装（request 拦截器、api 聚合层、公共组件内的接口调用）
4. 代码审查例行扫描时，对本次 diff 涉及的接口做调用方清点

仅 A 端独占的接口（确认无第二调用方）可简化为只核对 A 端自身适配，矩阵仍需留档。

## 三、检查前准备

1. 更新主分支代码（主分支为 development 或 dev，同代码审查流程）
2. 自建接口清单：**不假定存在现成的接口清单或提取脚本，每次检查时从源码现场生成**：
   - 后端侧：扫描 `./project-structure.md` 登记的后端目录全部 Controller，提取类级 + 方法级映射注解（`@RequestMapping` / `@PostMapping` 等），得到「路径、入参 DTO、返回 VO」清单
   - 前端侧：扫描各端源码的 api 封装层与请求调用点，提取「请求 URL、传参、响应字段读取点」
   - 交叉验证：前端调用 URL 集合与后端映射集合双向比对，悬空项（有调无实现 / 有实现无调用）单列
3. 调用方定位方法：
   - 后端 → 前端：按后端映射路径（换算网关前缀差异）在前端各端源码搜索 URL 片段与关键参数名
   - 前端 → 后端：从前端 api 封装层提取 URL + 入参，与后端接口清单比对
   - 后端 → 后端：搜索 Feign Client / RestTemplate / WebClient 的服务间调用
4. 路径匹配注意：区分 `/api` 与 `/c-api` 网关前缀；`/client/` 段归属判定见 `./java-code-review.md` 第 2 条

## 四、检查项

### 4.1 调用方清点（必做，先行）

对每个变更接口建立「调用方矩阵」：

- **行** = 变更接口
- **列** = 调用方：按 `./project-structure.md` 当时登记的前端目录逐一生成，不写死端列表（新增/下线端以该文件更新为准），末尾固定追加「后端内部」「第三方」两列

示例（列名以检查时 `./project-structure.md` 登记为准）：

| 变更接口 | \<前端目录A\> | \<前端目录B\> | … | 后端内部 | 第三方 |
|---|---|---|---|---|---|
| POST /api/xxx/yyy | 调用(3处) | 不涉及 | … | 未调用 | 未调用 |
| POST /api/zzz（破坏性变更） | 已适配(同批提交 abc123) | 未适配 | … | 未调用 | 无法确认（检索方式：…） |

- 标记口径（统一使用文字，禁止使用 ✓/✗/— 等符号）：
  - `调用(n处)` — 该方调用此接口，附调用点数量
  - `已适配` — 调用方已与本次变更同批适配（附 file:line 或提交号）
  - `未适配` — 调用方未同步适配本次破坏性变更（计问题）
  - `未调用` — 经源码检索确认该方无调用点
  - `不涉及` — 该方无此业务场景，功能上不可能调用（如该端无对应业务模块）
  - `无法确认` — 复核后仍无法确认
- **「无法确认」不得静默放过**：以 URL 最后两段路径 + 关键参数名全局复核；仍无结果的注明检索方式后按「未调用」处理
- 「调用 / 已适配 / 未适配」格子须落到具体调用点（file:line），作为后续逐格核对的依据

### 4.2 一致性核对项（对矩阵中每个「调用 / 已适配 / 未适配」格子逐项执行）

**C1 路径一致性**
- 前端请求 URL 与后端当前映射一致；接口改名/迁移后，其余端的旧路径残留即为断链

**C2 请求参数一致性**
- 前端传的每个字段后端仍在接收（改名/删除字段时逐端核对）
- 后端新增必填参数 → 所有调用方必须已适配，否则报问题
- 校验规则收紧（`@NotNull` / `@Size` / 正则）→ 核对各端既有数据及**已发布未强更的旧版 APP** 是否触发拒绝

**C3 响应结构一致性**
- 前端读取的每个字段（含 `data.xxx` 嵌套取值）后端仍在返回
- 字段改名/删除/类型变化 → 列出所有读取该字段的调用点
- 后端新增枚举值/字典项 → 各端前端是否有兜底（default 分支、未匹配文案）
- 统一返回结构 `{ code, message, data }` 未被破坏

**C4 语义与行为一致性**
- 分页参数语义（page/size、每页上限 1000）、排序白名单
- 日期/时区格式、金额单位（分/元）、ID 类型（string/number 精度）
- 权限调整：接口加权限注解后，原先可调用的其他端是否会 403
- 幂等 / 防重复提交约束变化对多端的影响

**C5 后端内部共用逻辑（后端改动自查）**
- 公共 DTO/VO 字段变更 → 搜索所有 `@RequestBody` 与返回该类型的 Controller，逐一核对
- 公共 Service/Mapper 逻辑变更 → 列出全部调用方 Controller，逐一评估行为变化
- 差异化需求：确需不同行为的，拆独立接口或加版本参数；**禁止在同一共享接口内按请求来源写 if 分支**

### 4.3 变更分类与判定

| 分类 | 判定 | 处理 |
|---|---|---|
| 非破坏性 | 仅新增可选字段/新增接口，不影响既有调用方 | 放行，矩阵留档 |
| 破坏性已适配 | 所有调用方在同一提交/同一批次内完成适配 | 放行，矩阵留档 |
| 破坏性未适配 | 存在调用方未同步适配 | **计违规/整改**，标注受影响端与现象 |
| 调用方悬空 | 前端调用了后端不存在的接口（或后端接口无任何前端调用） | 计违规/整改 |

## 五、执行流程

1. 由 diff 识别变更接口清单（后端 Controller 级 + 公共 DTO 级 + 前端封装层）
2. 生成调用方矩阵（4.1）
3. 逐格执行 C1–C4，后端改动补 C5
4. 按 4.3 分类判定
5. 按第六节产出报告

## 六、产出要求

- 报告文件：`./代码审查-[年-月-日-时]-一致性检查.md`（独立成文，或作为代码审查报告章节并注明覆盖范围）
- 必含内容：
  1. 变更接口清单
  2. 调用方矩阵（含调用点 file:line）
  3. 问题明细，每条含：检查项编号（C1–C5）、位置、受影响端、现象、修复建议、严重度
  4. 分类判定汇总与结论
- 严重度对齐代码审查报告口径：**严重**（其他端功能不可用/报错）、**一般**（兼容但口径不一致）、**提示**（风险与建议）
- 问题标注样式：报告内所有**计违规/整改**的内容——问题明细标题、矩阵「未适配」格子、判定汇总计整改行、不合格结论、待整改项——一律用加粗红字 `<font color="red">**…**</font>` 标注；放行留档项不得标红
- 中间数据（矩阵原始数据、搜索结果、脚本）统一放 `./scan-data/`，脚本可直接复跑，不要另建目录
- 豁免项按 `./CLAUDE.md` 豁免清单处理，不重复上报

## 七、速查清单（执行时逐项打勾）

- [ ] 已更新主分支并完成接口清单自建（后端映射 + 前端调用点 + 交叉验证）
- [ ] 每个变更接口已完成调用方清点，无「无法确认」遗留
- [ ] C1 路径 / C2 请求 / C3 响应 / C4 语义 已逐格核对
- [ ] 公共 DTO / Service / 枚举 变更已排查全部使用方（C5）
- [ ] 破坏性变更全部「已适配」或已列入整改
- [ ] 差异化需求已给出拆分接口 / 版本化建议
- [ ] 报告与中间数据已落盘到约定位置