# 04 — 验收核验：A4 字段表覆盖率清零核对

Type: task
Status: resolved

Blocked by: 03

## Question

对 `D:\code\crm-api-docs\A4 客户管理\` 跑一次覆盖率统计（复用本次调查用的 `字段 | 类型 | 说明` 表头扫描方法或等价脚本），确认：

- 117 个端点文件（排除 `folder.bru`）是否 117 个都命中字段表模式。
- 抽查 5-8 个票 03 新补的端点，人工核对字段说明文字是否语义准确（不是机械抽取出的乱码或截断），JSON 示例格式是否与该分区其余文档风格一致。
- 确认原本已完整的端点文件内容未被意外改动（定点补丁方式下应逐字节不变）。
- 把最终覆盖率数字和核对结论记录下来，作为本效力的收尾证据。

## Answer

验收通过。

- 初次核验错误地仅将“存在字段表”视为通过；用户复核 `POST /api/customer/workspace/page` 后，发现其旧表缺少说明列，已按“字段 | 类型 | 说明”重新验收。
- 最终独立扫描结果：`117` 个端点文件中，`117` 个同时命中 `字段 | 类型 | 说明` 表和 JSON 响应示例；工具最终 dry-run 为 `changed=0`。
- 共修改 `99` 个文件：67 个原无字段表文件，另有 32 个旧表改为带说明列；后者保留其 E2E 实测响应示例。
- 已对分页、对象、列表、二进制、空响应、标量六种返回形态复核字段表；映射清单记录每一端点的 Controller 来源。

### v2 复核（说明列质量验收）

- 验收口径升级为"说明列必须是中文业务语义"：`diagnose_desc_quality.py` 全量统计——字段名复制 73→0、缺说明 0、`serialVersionUID` 污染 0；说明行 938→897（垃圾字段清除），798 行来自源码 `@Schema` 中文，其余为分页元字段（总条数/每页条数等）与二进制/空响应的准确语义说明。
- 抽样回读 6 端点：`关联商机页签`（`stageName→商机阶段名`，用户指出的 `POST /api/customer/opportunity/page`）、`工商信息查询`（record 9 字段全中文）、`操作日志分页`/`跟进记录分页`（实体字段全中文）、`读取列偏好`、`下载导入模板`（二进制说明准确）。
- 117/117 仍含 `字段 | 类型 | 说明` 表 + JSON 示例（missing_json=0，75 个 E2E 真值保留）；`git diff --check` 通过。