5.0 KiB
06 — Bruno 接口文档生成 + 真实示例注入
Type: task · Status: resolved · Blocked by: 04, 05
Question
交付两件套之一：Bruno 接口文档集合——E:\code\crm-api-docs\A4 客户管理\ 下 55 端点按原型页面分组 .bru（子目录结构参照 A3 商机管理：页面级目录 + folder.bru + README.md），示例值来自票 04/05 的 specimens.json 真实实测值。
工作项：
- 动手前先读：
C:\Users\Administrator\.qoder\skills\bruno-syncskill 机制 + 根目录bruno-sync.config.json（sourceRoots 需加crm-customer/src/main/java；本票也可对称商机票 11 用 gen+inject 生成器模式，以「结构听源码、表述听人」铁律为准——手改实参值/示例再生时逐字保留，对账钥匙 = METHOD + 路径）。 - 原型页面→接口分组齐全（API-SUMMARY.md 分组为底稿 + 票 01 原型一手核对）：每个 A4 页面对应的接口无遗漏、无孤立接口；跨模块依赖端点（crm-rule 提醒配置、crm-preference saved-view、商机侧硬依赖三端点）分组归属在此票定（建议规则配置入 A7 后台设置或 A4 内子目录，与 A3 商机规则族先例对齐）。
- 描述齐备：参数/出参字段说明（中文，@Schema 为源）、状态码（67001–67016 + 64023 + 66001 等跨模块码与业务含义）、权限标注（RBAC fail-open + @DataScope(module=customer)）、脱敏现状（masked 字段列明）、错误响应示例。
- 对账收口：生成后对账（verify_sync 或等价）确认钥匙全命中、sync 重跑不动、实参值受铁律保护不丢；A4 目录下 folder.bru/README.md 补全。
- agent 不提交 git（用户审查后自行提交——bruno-coldstart 既有约定）。
- ⚠ 集合根目录现为裸 collection（无 workspace.yml）：若用户 Bruno 3.x 打不开，按 bruno-coldstart 先例升级 workspace 结构（Not-yet 挂号，动手前问用户）。
Answer
票 06 收口（换机续跑 2026-09-04 完成）。生成规模：57 个 .bru / 10 个生成目录（A4 下 9 个子目录 55 端点 + collection 根级 客户管理/超期提醒规则/ 2 端点，另含根级 客户管理/folder.bru seq:12 与各目录 folder.bru）。
分组决策（结构听源码铁律）：
- 目录 = 源码
@Tag原文。9 个 crm-customer Controller 的 tag 均带「A4 客户管理/」前缀，剥前缀后相对 BASE 落位；CustomerReminderRuleController（crm-rule）tag 原文「客户管理」无 A4 前缀 → 相对 collection 根落位（客户管理/超期提醒规则/）。 - crm-preference saved-view 6 端点不生成副本：源码 tag 挂 A3 商机管理（商机先建、客户侧复用同套），生成副本会被 sync 重跑判孤儿；README 文字索引标明客户域 scopeKey=
customer.*。 - 路径段
{workspace}保留占位原样入钥匙（mine/overview/pool 三值一套端点，.bru url 块展开为 mine 实例）。
对账结果：verify_a4.py 正则扫 9 个 crm-customer Controller + CustomerReminderRuleController 得 (METHOD, path) 钥匙集 57 个，与生成 .bru docs 首行钥匙双向比对——missing 0 / extra 0 / duplicate 0，PASS 全命中收口。docs 首行标注「本行兼作对账钥匙，勿手改」。
格式抽查：新增客户.bru（form 大表 + specimens 实测 67003 撞码响应）、保存提醒规则.bru（唯一 JSON 端点，body:json 用 specimens 实测 body + 实测回显）、workspace 列表分页.bru（分页 content 截 1 条 + 实测字段结构表）对照金标准 A3 商机管理/新建商机/新建商机.bru 结构一致：meta tags:[generated] / method 块 / params·body 块 / docs 四段+表格。
裸 collection 不升级（Not-yet 挂号项结论）：集合根目录保持裸 collection（bruno.json + collection.bru，无 workspace.yml），本票全部生成逻辑按现状跑通（生成 + Bruno 可读），不做 workspace 结构升级——避免影响其余 A0-A7 分区的存量路径与用户工作区打开方式，如后续 Bruno 3.x 打不开再按 bruno-coldstart 先例单独处理。
换机事项：生成器 3 处盘符路径已从 E: 改 D:（sys.path / DOCS / SP_DIR）；旧机第一次跑的错误产物（重复嵌套目录 A4 客户管理/A4 客户管理/ 64 文件 + 错位 A4 客户管理/客户管理/超期提醒规则/ 3 文件）已随用户 git pull 进入本机，清理脚本 clean_a4_leftover.py 删除后重跑生成，幂等无残留。
README：A4 客户管理/README.md 已从占位重写——9 子目录索引（含端点清单与计数）、根级提醒规则归位原因、crm-preference 不生成副本说明、空缺标注、对接示位、维护纪律（只碰 tags:[generated] / 对账钥匙行勿手改 / agent 不提交 git）。
遗留：agent 不提交 git，D 盘文档仓变更（删 2 残留目录 + 新增 57 .bru + folder.bru + README 重写）由用户审查后自行提交。缺陷注记（D-02/D-04/D-05/D-07）已按 defs_a4.py 写入对应 .bru desc。