You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4.5 KiB
4.5 KiB
03 · 文档缺口普查（117 端点 × 四类问题 worklist）
Type: research Status: resolved Blocked by: —
Question
对 D:\code\crm-api-docs\A4 客户管理\ 全部 117 个端点 .bru（排除 folder.bru）做缺口普查，逐文件分类：
- (a) 占位示例：标记
// 示例数据，字段结构以上表为准，非真实返回（2026-09-11 盘点 42 个） - (b) 退化示例：标记「E2E 实测」但示例为空集/全 null 而该端点可有数据（如 客户详情\联系人图谱\图谱全量读.bru 的 nodes/edges 空数组——用户点名案例）
- (c) 嵌套 DTO 未展开：字段表存在
List<XxxDTO>/XxxDTO行但无子字段表（盘点 6 处：List×4、List×1、List×1） - (d) 说明不清晰：对照源码
@Schema与字段语义——纯字段名复述、缺值域枚举（状态/类型类字段没列取值）、缺格式/单位/口径说明
产出 assets/doc-gap-worklist.md：文件路径 × 问题类型 × 建议修法 × 所属模块（A4 分区 117 中约 32 个跨模块端点需标注归属 Controller）。该 worklist 是票 02（采集清单）/04（嵌套展开）/05（写回清单）/06（说明修复）的共同输入。
可复用资产：.scratch/a4-doc-fields/diagnose_desc_quality.py（desc 质量诊断先例）、canonical-endpoint-response-mapping.md（117 端点→返回类型→源码位置映射）、endpoint-response-survey.md。
Answer
普查完成（2026-09-11 全量重扫 117 文件，对照源码 @Schema 复核）。逐文件 worklist：assets/doc-gap-worklist.md（每文件一行，类型 列 = a/b/c/d 组合，机器可 grep；含建议修法 + 模块/Controller 归属 + 汇总统计）。
各类型计数（按文件，一文可多类）
| 类型 | 文件数 | 细分 |
|---|---|---|
| (a) 占位示例 | 79 | 其中 Result<Void>/标量端点只需采一次真值信封；有载荷端点需采有数据 specimen |
| (b) 退化示例 | 7 | full×3（失败疑似重复明细×2、图谱全量读）/ partial×4（客户分配 failures、快速添加联系人+页内批量编辑 failedRows、快速创建客户 similarHits 分支） |
| (c) 嵌套未展开 | 26 | List<F> 类型占位×13（failures，票面盘点漏网的最大形态）/ 具名 DTO 零展开×7（similarHits×4、nodes+edges×1、failedRows×2）/ 扁平无前缀×6（DetailRow×3、ImportPreview Row×3） |
| (d) 说明不清晰 | 10 | 引号截断行×1 文件（详情公共头部 7 行）/ 表缺 createTime 行×9 文件（交割×3 + 导入任务/记录×6） |
| ok 无缺口 | 22 | — |
最重要发现
- 票面盘点数全面失准，实际缺口更大：(a) 实为 79 文件（盘点 42），(c) 实为 26 文件 27 行（盘点 6 处）。主因：
List<F>占位类型（BatchResult.failures，13 文件）不带 DTO 后缀，原 grep 模式抓不到。 - 文档生成器有引号转义 bug：详情公共头部 7 行说明在
显 "--"处被截断成 dangling\，口径后半句全丢——修复示例前须先修生成器，否则回填会被再次截断。 - 表缺 createTime 行 9 文件：TransferDetailDTO/ImportResultDTO/ContactImportResultDTO 的 createTime 有 @Schema、实测返回里有，但字段表漏行——静态生成时漏了（可能是时间字段过滤规则误伤）。
- 117 文件只对应 75 个唯一端点：总览/我的客户/公海/联系人四分区大量复用（如 保存列偏好×4、批量分配×3），票 02 采集清单按唯一端点去重可省 ~40% 采集量；修示例回填同理。
- 模块归属：crm-preference 16 文件（列偏好/视图形态，Controller 在 crm-preference），crm-customer 101 文件；另有 3 类跨模块数据依赖需在文档口径中说明：关联商机←crm-opportunity port、工商查询←stub port、详情头部金额字段←恒 null 占位（拍板 A，非退化）。
- (b) 复核排除 3 个假阳性：客户详情（12 个 null 均真可选）、详情公共头部（恒 null 是设计）、任务结果×3（creatorName 可空）——空集≠退化的边界案例已逐个写进 worklist 备注列。
- 额外发现：错误码节回退 30 文件——文档仓工作树是对 HEAD 的整体重写（117 文件全改未提交）；HEAD 有「错误码」节的 78 文件 → 现仅 48 文件，30 文件错误码节被重生成丢掉（如 交接详情 的 67002）。已在 worklist 备注列逐文件标注「错误码丢失」并给出 git 回捞修法，建议并入票 06。