4.3 KiB

Raw Blame History

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 的输入（补缺口径建议）

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

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

遗留确认项（进 03 grill）

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

4.3 KiB Raw Blame History