03 — 构建静态 DTO 反射工具并写回 A4 缺口端点

Type: task Status: resolved

Blocked by: 01, 02, 05, 06

Question

基于票 01 的返回类型普查、票 02 拍板的写回方式及票 06 产出的全量端点—返回类型映射，构建一个静态解析工具并实际补全 A4 中所有缺响应字段表的端点：

工具能力：给定一个 Java 类型名（如 CustomerDetailDTO），在 crm-customer 源码（含继承的 crm-base BaseDTO 等公共基类）里定位对应 .java 文件，解析其 private <Type> <fieldName>; 字段声明和紧邻的 @Schema(description = "...") 注解，产出字段名/类型/说明三元组列表。
形态支持：按票 01 的分类结果，至少覆盖 PageResult<T>（展开 content[] + total/size/current/pages/empty）、List<T>、单个 DTO 三种主形态；票 01 发现的非标准/找不到 DTO 的边界情况，逐条决定跳过（保留原一行描述）还是特殊处理，并记录决定依据。
占位 JSON 示例合成：按字段类型生成占位值（String→示例中文/字符串、Integer/Long→示例数字或字符串化 ID、LocalDateTime→示例时间戳、Boolean→false 等），保持与 A2/A3/A7 现有文档风格一致（"示例数据，字段结构以上表为准，非真实返回"注释）。
禁用字段过滤：按 ADR-0017，deleted/creatorId/updaterId 等不应出现在响应里的字段，即使源码里存在也不要写进字段表。
写回：按票 02 拍板的定点补丁方式实际执行，只修改票 06 确认的缺口 .bru 文件。
跑完后自检：票 06 确认的全部缺口端点是否都产出了字段表 + JSON 示例；原有已完整文件是否保持不变（定点补丁方式下应完全不动它们）。

已通过 complete_a4_doc_fields.py 完成定点补丁。

工具只替换各 .bru 的“响应 data 结构”和“响应示例”区块；不重跑旧生成器。
静态解析结果覆盖 DTO、分页/列表包装、标量、空响应、二进制响应及嵌套 record；字段排除了 deleted、creatorId、updaterId、createTime、updateTime。
共修改 99 个 Bruno 文件：首轮补齐 67 个无字段表文件；复核后发现另有 32 个旧表仅含“示例值”而无字段说明，已改为 字段 | 类型 | 说明。
对已有 E2E 响应示例的旧文件，只替换字段表、保留实测示例；其余补丁端点使用标注为非真实返回的占位 JSON 示例。

根因三类：①字段解析把 static final long serialVersionUID 当业务字段（类型还拼成 staticfinallong）；②类级 @Schema("客户详情") 错配到首个字段（customerNo 说明成了"客户详情"）；③拿不到 @Schema 时回退字段名充当说明（stageName | String | stageName）。
工具重写为逐行状态机：排除 static/transient/@Schema(hidden=true) 字段；@Schema 必须紧贴字段声明才消费，方法/类型声明处清空缓冲；record 参数列表逐字段消费 @Schema，且 record 不再套用审计字段黑名单（OpportunityItem.updateTime 属业务字段）。
负责人拍板说明中文来源走"补源码 @Schema"：共补 7 个文件——BaseDTO.id、BaseEntity.id、OpportunityItem(7 字段)、CompanyCandidate(9 字段)、CustomerOplog(6 字段)、CustomerFollow(7 字段)、ColumnPreference(2 字段)；mvn compile BUILD SUCCESS，改动文件 BOM 扫描通过。
--force --apply 全量重写 117 个文件字段表；patch() 对已有"## 响应示例"的文件只换表，75 个 E2E 实测示例保留。