|
|
|
|
# 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-sync` skill 机制 + 根目录 `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。
|
