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.
37 lines
4.1 KiB
37 lines
4.1 KiB
2 days ago
|
# A4 客户管理接口文档响应字段补全
|
||
|
|
|
||
|
|
## Destination
|
||
|
|
|
||
|
|
把 A4 客户管理模块（`D:\code\crm-api-docs\A4 客户管理\`，117 个端点）中所有缺响应字段表的端点真正补全：字段名/类型/说明齐全，附带按类型合成的占位 JSON 示例，落地写入 Bruno 文档仓。到达终点即：A4 分区 117/117 个端点均有字段表，且原有完整文件与其余生成链条（目录/请求参数/meta）不被破坏。
|
||
|
|
|
||
|
|
真值示例（拿 e2e 实测替换占位值）不在本地图范围内，属于后续跟进，参见「Not yet specified」。
|
||
|
|
|
||
|
|
## Notes
|
||
|
|
|
||
|
|
- 领域：CRM API 文档治理（`bruno-sync.config.json`、`D:\code\crm-api-docs`）。
|
||
|
|
- 本效力覆盖模块：仅 `crm-customer`（A4 客户管理）。A5 项目管理、A2/A3/A7 的同类缺口不在本地图范围，是独立效力。
|
||
|
|
- 根因背景：`.scratch/customer-e2e/gen_a4_bru.py` 的字段表生成逻辑是"E2E 实测驱动"（`resp_struct_table()` 只在抓到 specimens JSON 时才展开字段），99/117 端点因未抓到实测值而回退成 `defs_a4.py` 里手写的一行类型描述，无字段表无 JSON 示例。
|
||
|
|
- 好消息：`crm-customer` 的 DTO/Entity 源码字段已普遍带 `@Schema(description=...)` 注解（Swagger 风格），字段说明文字是现成的，新工具只需机械抽取，不必人工新写描述。项目未接 springdoc-openapi，不能走运行时 OpenAPI JSON 这条路，只能静态解析 `.java` 源码文本。
|
||
|
|
- 本效力性质：**决策 + 执行**（覆盖默认的"只规划不执行"）——票的产出物包括真正写回 `.bru` 文件的动作，不仅是决策记录。
|
||
|
|
- 相关规范：Controller 出入参规范（ADR-0017，`deleted`/`creatorId`/`updaterId` 不应出现在响应里）、`docs/agents/domain.md`（CONTEXT.md 索引）。
|
||
|
|
- 涉及技能：/grilling（架构决策）、直接写代码/脚本（执行票）。
|
||
|
|
|
||
|
|
## Decisions so far
|
||
|
|
|
||
|
|
- [99 个缺口端点的返回类型普查](issues/01-endpoint-response-type-survey.md) — 当前 `defs_a4.py` 实际为 57 条、29 个缺口；与作为唯一真源的 Bruno 117 个端点不一致，不能直接作为全量写回清单。
|
||
|
|
- [字段表写回策略：定点补丁 vs 重跑整目录](issues/02-writeback-strategy.md) — 已确认只定点替换响应字段表与示例，保留其余 Bruno 文档内容；端点真源未定前禁止整目录重跑。
|
||
|
|
- [确认 A4 端点清单的唯一真源](issues/05-reconcile-canonical-endpoint-inventory.md) — 以 Bruno A4 目录中排除 `folder.bru` 的 117 个端点文件为唯一真源；先补齐未被 `defs_a4.py` 覆盖端点的返回类型映射，再写回字段表。
|
||
|
|
- [建立 Bruno A4 端点与返回类型映射清单](issues/06-build-canonical-response-mapping.md) — 117 个端点均已映射到 Controller 返回类型与源码位置，涵盖六种响应形态。
|
||
|
|
- [构建静态 DTO 反射工具并写回 A4 缺口端点](issues/03-build-static-reflector.md) — 工具 v2 重写为逐行状态机（排除 static/hidden、修类级 @Schema 错配、record 消费 @Schema）并补 7 个源码文件 @Schema 后，全量重写 117 文件字段表；75 个 E2E 示例保留。
|
||
|
|
- [验收核验：A4 字段表覆盖率清零核对](issues/04-verify-coverage.md) — 说明列中文语义验收：字段名复制 73→0、缺说明 0；117/117 含中文说明表 + JSON 示例，git diff --check 通过。
|
||
|
|
|
||
|
|
## Not yet specified
|
||
|
|
|
||
|
|
- e2e 实测值替换占位 JSON 示例——需要先有能跑通 A4 全端点的 e2e 用例/specimens 抓取，属于独立跟进，本地图只产出类型占位合成值。
|
||
|
|
- 静态反射工具是否要顺带扫描/校验 A2/A3/A7 已有的手抄字段表是否与当前源码字段一致（漂移检测）——本次不在范围，但普查结果如果暴露出明显漂移，可能会催生新效力。
|
||
|
|
|
||
|
|
## Out of scope
|
||
|
|
|
||
|
|
- A5 项目管理、A2/A3/A7 的字段表缺口——已确认是同一根因的不同表现，但用户明确要求"先处理客户模块"，缩小本次范围。留作后续独立效力。
|
||
|
|
- 全仓统一文档生成架构重建（如废弃 specimen 驱动模式、统一迁移所有模块到静态反射）——本地图只解决 A4，不做全局架构改造决策。
|