crm-backend-matt/.scratch/api-docs-reorg/issues/04-execute-reorg.md

# 04 文档仓重排执行落地

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

## Question

按「一级目录改造机制选型」的结论与「蓝湖一级目录树冻结与全量接口映射表」的映射表，完成落地（票 01 已钉死分支：**A 区路径进源码 tags，深 tag，bruno-sync 唯一权威通道**）：

1. **源码 tags 重构**：按映射表逐 Controller 改 tag（1:1 控制器类级 `@Tag` 改全路径；跨页/拆分控制器方法级多值 `@Operation(tags)`；类级与方法级互斥）；`SystemController` 无 tag 端点补显式深 tag；`LeadPoolController` 按票 02 挂双 tag。回归编译与单测。
2. **重建 `D:\code\crm-api-docs`**：现有 .bru 先按映射表 git-mv 到目标路径（表述保留，bruno-sync 铁律 1）；再跑 bruno-sync 全量对账（钥匙 = METHOD+url+新文件夹名，命中仅结构 patch）；空分区（A1 / A1X / A4 / A5 / A6）手工放 folder.bru + README 占位（bruno-sync 不为无 tag 分区生成文件夹）；公共依赖合并（文件、行政区划并入「公共依赖」）；调试(验证专用) 保留顶层；二级及更深目录不动。
3. **分区索引 README**：A0-A7 每分区 → 已落地接口清单 → 空缺标注 → 对接工程师示位；生成方式（手写 vs 小脚本幂等产出）本票落地时定；bruno-sync 不生成 README。
4. **ADR-0024 修订**：新增修订段——一级目录对齐原型 A 区（引用 v29 树工件）、深 tag 纪律（一级=分区原文，二级=页面，更深=页面内分组）、商机规则归 A7 的裁决、URL 回退通道关闭、双归属方法级多值 tags、未来新接口的一级挂载纪律（新 Controller 按页面全路径挂 tag）。
5. **机制联动（票 01 已定）**：`bruno-sync.config.json` menuBindings 四键随 tags 换 `A2 线索管理/…` 前缀；手工生成器家族（`gen_bruno.py` / `gen_opp_*.py` / `gen_v2_*.py` / `bru_lib.py`）退役留档。
6. **验收**：重建后文档仓目录树与映射表逐项一致；knife4j 分组 = 深路径 tag 原文；用户按分区索引 README 能确认各分区接口全集与空缺状态。

## Answer

## Answer

**（2026-08-31 解决；t1-t9 旧机会话完成，t10-t12 换机后续跑收尾，全绿关票。）**

1. **源码 tags 重构（完成）**：25 个 Controller 按映射表 §2 逐行落地（类级 @Tag 改全路径 / 方法级 @Operation(tags) 深路径 / LeadPool 5 端点双值 tags / SystemController 10 端点补显式 tag / Query 收敛 6→3 / Collab+Sub 分挂），Grep 复核旧前缀零残留。回归：`mvn test` 全仓 **873 测试 0 失败 0 错误**（base 38 / file 84 / auth 210 / dict 51 / rule 134 / preference 16 / lead 131 / opportunity 209），BUILD SUCCESS。
2. **文档仓重建（完成）**：§4 git-mv 清单全部落地；空分区 A1 / A1X / A4 / A5 / A6 folder.bru 占位（seq 2/3/6/7/8）；公共依赖合并（文件 + 行政区划）；调试(验证专用) 保留顶层。全量对账（tmp_reorg_audit.py，本机复跑）：**src keys 196 / doc keys 196，双向差集均 0**。
3. **分区索引 README（完成）**：生成方式落地裁决 = **手写**（叙述性导航，bruno-sync 不生成 README，人工维护）。11 个分区 README.md 已落盘：已落地 .bru 清单按二级目录列 + 空缺标注 + 对接工程师示位，空分区只写占位说明。文档仓 git status = 恰 11 个 untracked README。
4. **ADR-0024 修订（完成）**：文末追加「修订（2026-08-31，api-docs-reorg effort）」段——一级对齐 v29 权威树（引用 lanhu-tree-v29.md）、深 tag 纪律、商机规则归 A7 与线索规则双归属、URL 回退关闭、双归属 = 方法级多值 tags、新接口挂载纪律，另记机制联动（生成器家族退役 / menuBindings 前缀 / 文档仓换机路径）。回读逐字一致、无 BOM。
5. **机制联动（完成）**：bruno-sync.config.json menuBindings 四键前缀换 `A2 线索管理/…`（viewType/scopeKey 未动）；手工生成器家族（gen_bruno.py / gen_opp_*.py / gen_v2_*.py / bru_lib.py）退役留档；bruno-sync 注解驱动通道为唯一权威机制。
6. **验收（通过）**：§6 基线目录树逐目录对照全 OK（38 目录计数一致 + 5 空分区 folder.bru/README 齐 + 接口 .bru 总数 196 = 191 + 5 LeadPool 副本）；knife4j 抽查（起 crm-app 取 /v3/api-docs）：`A0 登录界面` / `A3 商机管理/商机详情/客户` / `A7 后台管理/权限管理/角色管理` / `公共依赖/文件` 4 组 + LeadPool 5 端点双归属 tags 全部命中；按分区索引 README 即可确认各分区接口全集与空缺状态（A7 分区空缺：客户规则 / 项目规则 / 日志管理）。

遗留提醒（不阻塞关票）：`A7 后台管理/权限点管理/资源树列表.bru` url 行为历史绝对地址，对账脚本已归一化识别；下次 bruno-sync 真跑时按「结构听源码」patch 为 `{{baseUrl}}` 形式。换机注记：对账脚本 REPO/DOCS 常量已改本机路径；bruno-sync.local.json = `{"docsRepoPath": "e:/code/crm-api-docs"}`；两仓改动均未提交，由用户审查后自行 commit。
commit 6 days ago			`# 04 文档仓重排执行落地`

			`Type: task`
commit 6 days ago			`Status: resolved`
commit 6 days ago			`Blocked by: 01, 03`

			`## Question`

			`按「一级目录改造机制选型」的结论与「蓝湖一级目录树冻结与全量接口映射表」的映射表，完成落地（票 01 已钉死分支：A 区路径进源码 tags，深 tag，bruno-sync 唯一权威通道）：`

			1. 源码 tags 重构：按映射表逐 Controller 改 tag（1:1 控制器类级 `@Tag` 改全路径；跨页/拆分控制器方法级多值 `@Operation(tags)`；类级与方法级互斥）；`SystemController` 无 tag 端点补显式深 tag；`LeadPoolController` 按票 02 挂双 tag。回归编译与单测。
			2. 重建 `D:\code\crm-api-docs`：现有 .bru 先按映射表 git-mv 到目标路径（表述保留，bruno-sync 铁律 1）；再跑 bruno-sync 全量对账（钥匙 = METHOD+url+新文件夹名，命中仅结构 patch）；空分区（A1 / A1X / A4 / A5 / A6）手工放 folder.bru + README 占位（bruno-sync 不为无 tag 分区生成文件夹）；公共依赖合并（文件、行政区划并入「公共依赖」）；调试(验证专用) 保留顶层；二级及更深目录不动。
			`3. 分区索引 README：A0-A7 每分区 → 已落地接口清单 → 空缺标注 → 对接工程师示位；生成方式（手写 vs 小脚本幂等产出）本票落地时定；bruno-sync 不生成 README。`
			`4. ADR-0024 修订：新增修订段——一级目录对齐原型 A 区（引用 v29 树工件）、深 tag 纪律（一级=分区原文，二级=页面，更深=页面内分组）、商机规则归 A7 的裁决、URL 回退通道关闭、双归属方法级多值 tags、未来新接口的一级挂载纪律（新 Controller 按页面全路径挂 tag）。`
			5. 机制联动（票 01 已定）：`bruno-sync.config.json` menuBindings 四键随 tags 换 `A2 线索管理/…` 前缀；手工生成器家族（`gen_bruno.py` / `gen_opp_.py` / `gen_v2_.py` / `bru_lib.py`）退役留档。
			`6. 验收：重建后文档仓目录树与映射表逐项一致；knife4j 分组 = 深路径 tag 原文；用户按分区索引 README 能确认各分区接口全集与空缺状态。`

			`## Answer`

commit 6 days ago			`## Answer`

			`（2026-08-31 解决；t1-t9 旧机会话完成，t10-t12 换机后续跑收尾，全绿关票。）`

			1. 源码 tags 重构（完成）：25 个 Controller 按映射表 §2 逐行落地（类级 @Tag 改全路径 / 方法级 @Operation(tags) 深路径 / LeadPool 5 端点双值 tags / SystemController 10 端点补显式 tag / Query 收敛 6→3 / Collab+Sub 分挂），Grep 复核旧前缀零残留。回归：`mvn test` 全仓 873 测试 0 失败 0 错误（base 38 / file 84 / auth 210 / dict 51 / rule 134 / preference 16 / lead 131 / opportunity 209），BUILD SUCCESS。
			`2. 文档仓重建（完成）：§4 git-mv 清单全部落地；空分区 A1 / A1X / A4 / A5 / A6 folder.bru 占位（seq 2/3/6/7/8）；公共依赖合并（文件 + 行政区划）；调试(验证专用) 保留顶层。全量对账（tmp_reorg_audit.py，本机复跑）：src keys 196 / doc keys 196，双向差集均 0。`
			`3. 分区索引 README（完成）：生成方式落地裁决 = 手写（叙述性导航，bruno-sync 不生成 README，人工维护）。11 个分区 README.md 已落盘：已落地 .bru 清单按二级目录列 + 空缺标注 + 对接工程师示位，空分区只写占位说明。文档仓 git status = 恰 11 个 untracked README。`
			`4. ADR-0024 修订（完成）：文末追加「修订（2026-08-31，api-docs-reorg effort）」段——一级对齐 v29 权威树（引用 lanhu-tree-v29.md）、深 tag 纪律、商机规则归 A7 与线索规则双归属、URL 回退关闭、双归属 = 方法级多值 tags、新接口挂载纪律，另记机制联动（生成器家族退役 / menuBindings 前缀 / 文档仓换机路径）。回读逐字一致、无 BOM。`
			5. 机制联动（完成）：bruno-sync.config.json menuBindings 四键前缀换 `A2 线索管理/…`（viewType/scopeKey 未动）；手工生成器家族（gen_bruno.py / gen_opp_.py / gen_v2_.py / bru_lib.py）退役留档；bruno-sync 注解驱动通道为唯一权威机制。
			6. 验收（通过）：§6 基线目录树逐目录对照全 OK（38 目录计数一致 + 5 空分区 folder.bru/README 齐 + 接口 .bru 总数 196 = 191 + 5 LeadPool 副本）；knife4j 抽查（起 crm-app 取 /v3/api-docs）：`A0 登录界面` / `A3 商机管理/商机详情/客户` / `A7 后台管理/权限管理/角色管理` / `公共依赖/文件` 4 组 + LeadPool 5 端点双归属 tags 全部命中；按分区索引 README 即可确认各分区接口全集与空缺状态（A7 分区空缺：客户规则 / 项目规则 / 日志管理）。

			遗留提醒（不阻塞关票）：`A7 后台管理/权限点管理/资源树列表.bru` url 行为历史绝对地址，对账脚本已归一化识别；下次 bruno-sync 真跑时按「结构听源码」patch 为 `{{baseUrl}}` 形式。换机注记：对账脚本 REPO/DOCS 常量已改本机路径；bruno-sync.local.json = `{"docsRepoPath": "e:/code/crm-api-docs"}`；两仓改动均未提交，由用户审查后自行 commit。