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.
5.0 KiB
5.0 KiB
04 文档仓重排执行落地
Type: task Status: resolved Blocked by: 01, 03
Question
按「一级目录改造机制选型」的结论与「蓝湖一级目录树冻结与全量接口映射表」的映射表，完成落地（票 01 已钉死分支：A 区路径进源码 tags，深 tag，bruno-sync 唯一权威通道）：
- 源码 tags 重构：按映射表逐 Controller 改 tag（1:1 控制器类级
@Tag改全路径；跨页/拆分控制器方法级多值@Operation(tags)；类级与方法级互斥）；SystemController无 tag 端点补显式深 tag；LeadPoolController按票 02 挂双 tag。回归编译与单测。 - 重建
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 分区生成文件夹）；公共依赖合并（文件、行政区划并入「公共依赖」）；调试(验证专用) 保留顶层；二级及更深目录不动。 - 分区索引 README：A0-A7 每分区 → 已落地接口清单 → 空缺标注 → 对接工程师示位；生成方式（手写 vs 小脚本幂等产出）本票落地时定；bruno-sync 不生成 README。
- ADR-0024 修订：新增修订段——一级目录对齐原型 A 区（引用 v29 树工件）、深 tag 纪律（一级=分区原文，二级=页面，更深=页面内分组）、商机规则归 A7 的裁决、URL 回退通道关闭、双归属方法级多值 tags、未来新接口的一级挂载纪律（新 Controller 按页面全路径挂 tag）。
- 机制联动（票 01 已定）：
bruno-sync.config.jsonmenuBindings 四键随 tags 换A2 线索管理/…前缀；手工生成器家族（gen_bruno.py/gen_opp_*.py/gen_v2_*.py/bru_lib.py）退役留档。 - 验收：重建后文档仓目录树与映射表逐项一致；knife4j 分组 = 深路径 tag 原文；用户按分区索引 README 能确认各分区接口全集与空缺状态。
Answer
Answer
（2026-08-31 解决；t1-t9 旧机会话完成，t10-t12 换机后续跑收尾，全绿关票。）
- 源码 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。 - 文档仓重建（完成）：§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。
- 分区索引 README（完成）：生成方式落地裁决 = 手写（叙述性导航，bruno-sync 不生成 README，人工维护）。11 个分区 README.md 已落盘：已落地 .bru 清单按二级目录列 + 空缺标注 + 对接工程师示位，空分区只写占位说明。文档仓 git status = 恰 11 个 untracked README。
- ADR-0024 修订（完成）：文末追加「修订（2026-08-31，api-docs-reorg effort）」段——一级对齐 v29 权威树（引用 lanhu-tree-v29.md）、深 tag 纪律、商机规则归 A7 与线索规则双归属、URL 回退关闭、双归属 = 方法级多值 tags、新接口挂载纪律，另记机制联动（生成器家族退役 / menuBindings 前缀 / 文档仓换机路径）。回读逐字一致、无 BOM。
- 机制联动（完成）：bruno-sync.config.json menuBindings 四键前缀换
A2 线索管理/…（viewType/scopeKey 未动）；手工生成器家族（gen_bruno.py / gen_opp_*.py / gen_v2_*.py / bru_lib.py）退役留档；bruno-sync 注解驱动通道为唯一权威机制。 - 验收（通过）：§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。