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.
43 lines
4.5 KiB
43 lines
4.5 KiB
2 days ago
|
# 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<CustomerSimilarHitDTO>×4、List<GraphNodeDTO>×1、List<GraphEdgeDTO>×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 | — |
|
||
|
|
|
||
|
|
### 最重要发现
|
||
|
|
|
||
|
|
1. **票面盘点数全面失准，实际缺口更大**：(a) 实为 79 文件（盘点 42），(c) 实为 26 文件 27 行（盘点 6 处）。主因：`List<F>` 占位类型（BatchResult.failures，13 文件）不带 DTO 后缀，原 grep 模式抓不到。
|
||
|
|
2. **文档生成器有引号转义 bug**：详情公共头部 7 行说明在 `显 "--"` 处被截断成 dangling `\`，口径后半句全丢——修复示例前须先修生成器，否则回填会被再次截断。
|
||
|
|
3. **表缺 createTime 行 9 文件**：TransferDetailDTO/ImportResultDTO/ContactImportResultDTO 的 createTime 有 @Schema、实测返回里有，但字段表漏行——静态生成时漏了（可能是时间字段过滤规则误伤）。
|
||
|
|
4. **117 文件只对应 75 个唯一端点**：总览/我的客户/公海/联系人四分区大量复用（如 保存列偏好×4、批量分配×3），票 02 采集清单按唯一端点去重可省 ~40% 采集量；修示例回填同理。
|
||
|
|
5. **模块归属**：crm-preference 16 文件（列偏好/视图形态，Controller 在 crm-preference），crm-customer 101 文件；另有 3 类跨模块数据依赖需在文档口径中说明：关联商机←crm-opportunity port、工商查询←stub port、详情头部金额字段←恒 null 占位（拍板 A，非退化）。
|
||
|
|
6. **(b) 复核排除 3 个假阳性**：客户详情（12 个 null 均真可选）、详情公共头部（恒 null 是设计）、任务结果×3（creatorName 可空）——空集≠退化的边界案例已逐个写进 worklist 备注列。
|
||
|
|
7. **额外发现：错误码节回退 30 文件**——文档仓工作树是对 HEAD 的整体重写（117 文件全改未提交）；HEAD 有「错误码」节的 78 文件 → 现仅 48 文件，30 文件错误码节被重生成丢掉（如 交接详情 的 67002）。已在 worklist 备注列逐文件标注「错误码丢失」并给出 git 回捞修法，建议并入票 06。
|