05 — Bruno 文档完善 + 按原型页面树对齐

Type: task Status: resolved Blocked by: 01, 03

Question

Bruno 文档「完善 + 按原型页面分文件夹」对齐（仓 = E:\code\crm-api-docs，439 .bru）：

完整性对账：契约 85 端点（票 01 无新端点，字段级变更）vs .bru 覆盖，零缺零余；「前端可联调标准」抽查——照文档能直接发起请求并看懂响应（示例值真值、出参字段全、错误码可查）。
结构对照原型页面树（lanhu-tree-v29），已观察错位待裁决：
- 「战略协议」平铺一级，原型属 A4-4-9/10 客户详情页签；
- 「客户详情\联系人导入」按源码类级 @Tag 归详情（原型 A4-5-4 在独立菜单联系人下）——按 ADR-0024 菜单粒度 + 源码 @Tag 权衡拍板并记录；
- 二级目录名是否加 A4-N 编号前缀：对照全仓跨域一致性（A2/A3 均无编号，倾向不动，票内定）。
票 01 字段变更 → /bruno-sync 重生成三份「workspace 列表分页.bru」（客户公海/客户总览/我的客户）+ 示例值实测注入。
bruno-sync.config.json sourceRoots/menuBindings 对本机 E: 仓核对；verify 对账 PASS；git 不动留用户审查提交。

2026-09-11。四项全交付。

脚本 bruno-audit-t05.py（基线 + 迁移后各跑一次，产物 bruno-audit-t05.json）：

契约 85 端点提取踩坑：API-SUMMARY 存在三种行形态——表格首列型（76）、页签名列型（| 公共头部 | GET \/api/...` |）、内联正文型（\POST /api/...`）。窄表正则只能抓 76，detail-head/follow/oplog/opportunity/ping/archive 族 9 个在页签列/正文行，漏抓会被误报成「多余」。终版 = 三模式并集 + 双侧剥 ?（防 a7 踩过的「query 写进钥匙」坑）。
结果：85/85 全覆盖 missing=0、客户域 extra=0、无法识别=0；50 个无标记文件全为 folder.bru（Bruno 目录描述，天然无 generated，非私产问题）；60 钥匙多副本（页面归属多 tag 同内容副本设计，正常）；418 generated 文件。

战略协议 → 客户详情子级：原型 a4-4-6 页签 + a4-4-9/10 弹页全在「A4-4 客户详情」组（lanhu-tree-v29），无独立菜单。源码 CustomerAgreementController @Tag「A4 客户管理/战略协议」→「A4 客户管理/客户详情/战略协议」，5 个 .bru 平铺迁入 客户详情\战略协议\。
联系人导入 → 联系人菜单下：原型 a4-5-4 在「A4-5 联系人」独立菜单组；旧 @Tag 挂详情是「导入入口在详情页签」的旧理解。ADR-0024 菜单粒度优先 → CustomerContactImportController @Tag →「A4 客户管理/联系人/联系人导入」，6 个 .bru 迁出详情树至 联系人\联系人导入\。接口语义（客户内导入，customerId 必填）不变，仅目录归位。
A4-N 编号前缀：不动。A2/A3 全仓二级目录均无编号，跨域一致性优先；页号映射由 lanhu-tree-v29 + 票 03 矩阵台账承载。

迁移以 bru-move-t05.py 执行（shutil.move 字节不动 + 源目录残留熔断 + 空壳删除）；源码 tag 变更使未来 bruno-sync 重生成天然落新位置，无漂移。

bru-patch-focusflag-t05.py：三份「workspace 列表分页.bru」（公海/总览/我的客户，同内容副本）×3 处 = 9 处：

响应结构表 +1 行（DTO 末字段 lastViewTime 后，与序列化序一致）；
响应示例 JSON +1 字段；
docs 说明段 +1 句语义：「focusFlag：是否关注（1=已关注 0=未关注；customer_focus 行存在=1），列表关注星标列数据源，三 workspace 通用。」

示例值 1 = E2E 实测（票 04 F-09 断言 focus 后列表行 focusFlag=1）。既有表述与示例值一字未动；三份原件 LF/无 BOM 实测后写回恒等。

复对账 PASS（85/85，迁移不改钥匙）；全仓 .bru BOM=0；迁移 11 份内容字节不动。
前端可联调抽查：workspace 3 份 = 出参全（含 focusFlag）+ 实测真值 + 错误码可查；战略协议页签列表（抽查）= 出参 9 字段全 + 错误码可查，但示例值为机械推导值非实测真值（战略协议 CRUD 无 E2E 套件覆盖、无实测值来源）——记档，翻案需先补 E2E 覆盖再重注入。
配置核对：bruno-sync.config.json sourceRoots 含 crm-customer/crm-dict；menuBindings A4 五菜单齐。

文档仓 E:\code\crm-api-docs：M×3（workspace focusFlag）+ D×11 + ??×11（结构迁移）。
后端仓：CustomerAgreementController / CustomerContactImportController 各 1 行 @Tag 注释级变更（仅 swagger 文档分组，无运行时影响）。
注意：文档仓 A5 项目管理区另有本票之前的既有未提交变更（README.md + 若干 .bru），与本票无关，一并留审。