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.
34 lines
3.7 KiB
34 lines
3.7 KiB
2 days ago
|
# 03 — 构建静态 DTO 反射工具并写回 A4 缺口端点
|
||
|
|
|
||
|
|
Type: task
|
||
|
|
Status: resolved
|
||
|
|
|
||
|
|
Blocked by: 01, 02, 05, 06
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
基于票 01 的返回类型普查、票 02 拍板的写回方式及票 06 产出的全量端点—返回类型映射，构建一个静态解析工具并实际补全 A4 中所有缺响应字段表的端点：
|
||
|
|
|
||
|
|
1. **工具能力**：给定一个 Java 类型名（如 `CustomerDetailDTO`），在 `crm-customer` 源码（含继承的 `crm-base` BaseDTO 等公共基类）里定位对应 `.java` 文件，解析其 `private <Type> <fieldName>;` 字段声明和紧邻的 `@Schema(description = "...")` 注解，产出字段名/类型/说明三元组列表。
|
||
|
|
2. **形态支持**：按票 01 的分类结果，至少覆盖 `PageResult<T>`（展开 content[] + total/size/current/pages/empty）、`List<T>`、单个 DTO 三种主形态；票 01 发现的非标准/找不到 DTO 的边界情况，逐条决定跳过（保留原一行描述）还是特殊处理，并记录决定依据。
|
||
|
|
3. **占位 JSON 示例合成**：按字段类型生成占位值（String→示例中文/字符串、Integer/Long→示例数字或字符串化 ID、LocalDateTime→示例时间戳、Boolean→false 等），保持与 A2/A3/A7 现有文档风格一致（"示例数据，字段结构以上表为准，非真实返回"注释）。
|
||
|
|
4. **禁用字段过滤**：按 ADR-0017，`deleted`/`creatorId`/`updaterId` 等不应出现在响应里的字段，即使源码里存在也不要写进字段表。
|
||
|
|
5. **写回**：按票 02 拍板的定点补丁方式实际执行，只修改票 06 确认的缺口 `.bru` 文件。
|
||
|
|
6. 跑完后自检：票 06 确认的全部缺口端点是否都产出了字段表 + JSON 示例；原有已完整文件是否保持不变（定点补丁方式下应完全不动它们）。
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
已通过 [complete_a4_doc_fields.py](../complete_a4_doc_fields.py) 完成定点补丁。
|
||
|
|
|
||
|
|
- 工具只替换各 `.bru` 的“响应 data 结构”和“响应示例”区块；不重跑旧生成器。
|
||
|
|
- 静态解析结果覆盖 DTO、分页/列表包装、标量、空响应、二进制响应及嵌套 record；字段排除了 `deleted`、`creatorId`、`updaterId`、`createTime`、`updateTime`。
|
||
|
|
- 共修改 99 个 Bruno 文件：首轮补齐 67 个无字段表文件；复核后发现另有 32 个旧表仅含“示例值”而无字段说明，已改为 `字段 | 类型 | 说明`。
|
||
|
|
- 对已有 E2E 响应示例的旧文件，只替换字段表、保留实测示例；其余补丁端点使用标注为非真实返回的占位 JSON 示例。
|
||
|
|
|
||
|
|
### v2 修复（用户复核 stageName 说明为字段名后）
|
||
|
|
|
||
|
|
- 根因三类：①字段解析把 `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 实测示例保留。
|