# Research 04：文档完善度审计（前端视角）

日期：2026-08-17 · 范围：`D:\code\crm-api-docs` 线索相关 .bru（线索管理 23 + 线索规则-公海池配置 5 + 线索规则-行政区划 2 + 列偏好 2 = 32 个）+ collection.bru + environments/local.bru · 方法：逐文件抽读 + 与 gen_bruno.py（141 版生成器）能力对照

## 总结论

**D 盘现状 = 旧版生成器产物，完善度仅「目录级」：有 URL 和一句话说明，无参数、无响应、无枚举——前端无法据此联调。** 但 `.scratch/bruno-coldstart/gen_bruno.py`（e 盘 141 版的生成器）**已具备全部补齐能力**，D 盘从未用它重新生成过。即：多数致命问题是「未重生成」而非「能力缺失」。

## 发现清单

### A. 致命：无法联调（32 个 .bru 全体）

| # | 问题 | 证据 |
|---|---|---|
| A1 | **无实际请求参数**：`body: formUrlEncoded` 只是类型声明，无参数键值块；GET query 同样缺失。前端不知道字段名/类型/必填/格式（ids 逗号分隔？复杂字段 stringify？） | 线索分页.bru、批量领取.bru、转商机.bru、保存列偏好.bru、新增或编辑公海池.bru 全部 21 行以内，无 body 块 |
| A2 | **无响应字段与示例**：PageResult\<LeadDTO\>、BatchResult、LeadStatsDTO 的字段集不可见，前端必须翻 Java 源码 | 同上，docs 仅一句话 |
| A3 | **枚举不展开**：status 七态值域、viewType 四值、feedbackStatus、claim_rule——名字都没有 | 同上 |

### B. 误导：文实不符（collection.bru）

| # | 问题 | 证据 |
|---|---|---|
| B1 | 失效指向：「完整契约见 **crm-core 仓库**根目录 API_CONTRACT.md」——该仓/文件不存在（后端仓是 crm-backend-matt，根目录无此文件） | collection.bru L12 |
| B2 | 路径不符：使用说明让「运行 **auth/**钉钉扫码登录」，实际接口在「**登录/**」文件夹（无 auth/ 文件夹） | collection.bru L16 vs 目录 |
| B3 | **文实不符的混合状态**：collection.bru「页面归属规范」讲的是方法级 @Operation(tags) 按页面分组的新机制（ADR-0024 后的文案），但接口文件夹还是旧的平铺结构——说明 collection.bru 被单独更新过、.bru 结构从未跟上 | collection.bru L56-58 vs 目录树 |
| B4 | 无 menuBindings 对照（四视图 viewType/scopeKey 专属值表；ADR-0024 设计、141 版已实现，D 盘没有） | collection.bru 全文 |

### C. 中：可用性

| # | 问题 | 证据 |
|---|---|---|
| C1 | 错误/边界场景零覆盖（删除已转商机、领取超限、非池成员、主部门无池拦截文案） | 全部 .bru |
| C2 | environments/local.bru 的 baseUrl=`https://ai.itc.vip/crm-api`（测试环境域名）、token 空——是否前端联调环境待用户确认 | local.bru |

## gen_bruno.py（141 版）能力核对——A 类问题在重生成后自动消失

| 能力 | 状态 | 证据（gen_bruno.py） |
|---|---|---|
| 参数完整定义（名/类型/必填/默认/说明/示例值） | ✅ 已有 | params 六元组；如 claimOnCreate、ConvertOpportunityParam 已展开为 4 字段 |
| 响应字段表 + 示例 JSON（PageResult 分页信封自动构造） | ✅ 已有 | `page_of()`、`BATCH_LEAD_ROWS`（failures 明细）、LeadStatsDTO 五卡片字段 |
| 枚举展开 | ✅ 已有 | status「1 未分发 2 待领取 3 已领取 4 跟进中 5 已转商机 6 过期失效 7 线索作废」、feedbackStatus 1=有效 2=无效 |
| 四菜单副本 viewType/scopeKey 绑定 +【X 页】docs 前缀 +「本页固定传」 | ✅ 已有 | `MENU_EXPAND` / `bindv()` |
| menuBindings 对照进 collection.bru | ✅ 已有（141 版） | ADR-0024 后果记录 |

## 对 03 的输入（补缺口径建议）

达到「前端不看源码可联调」只需三件事，两小一大：

1. **【小·文案】** collection.bru 模板修两处：删 crm-core 失效指向（改为就地完整化或指向后端仓 README）；auth/ → 登录/。
2. **【小·增强】** 每接口 docs 补一行「典型报错」（gen_bruno.py desc 字段扩展即可，非必须）。
3. **【大·机制】** 逐页裁剪（03 的主体议题）——重生成 + 裁剪一起落地，A/B 类问题随之消灭。

## 遗留确认项（进 03 grill）

- baseUrl（ai.itc.vip/crm-api）是否前端联调环境。
- C1 错误场景点述是否纳入本期口径。