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.1 KiB
4.1 KiB
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 个缺口端点的返回类型普查 — 当前
defs_a4.py实际为 57 条、29 个缺口；与作为唯一真源的 Bruno 117 个端点不一致，不能直接作为全量写回清单。 - 字段表写回策略：定点补丁 vs 重跑整目录 — 已确认只定点替换响应字段表与示例，保留其余 Bruno 文档内容；端点真源未定前禁止整目录重跑。
- 确认 A4 端点清单的唯一真源 — 以 Bruno A4 目录中排除
folder.bru的 117 个端点文件为唯一真源；先补齐未被defs_a4.py覆盖端点的返回类型映射，再写回字段表。 - 建立 Bruno A4 端点与返回类型映射清单 — 117 个端点均已映射到 Controller 返回类型与源码位置，涵盖六种响应形态。
- 构建静态 DTO 反射工具并写回 A4 缺口端点 — 工具 v2 重写为逐行状态机（排除 static/hidden、修类级 @Schema 错配、record 消费 @Schema）并补 7 个源码文件 @Schema 后，全量重写 117 文件字段表；75 个 E2E 示例保留。
- 验收核验：A4 字段表覆盖率清零核对 — 说明列中文语义验收：字段名复制 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，不做全局架构改造决策。