4.7 KiB
01 一级目录改造机制选型
Type: grilling Status: resolved Blocked by: (无)
Question
一级目录重排在哪一层实现？候选：
- Controller tags 加 A 区前缀：tag 变为「A2 线索管理/线索公海」形式。swagger UI 同步按 A 区分组，延续 ADR-0024「业务代码即文档」纪律；代价是 17+ 个 Controller 的 tags 全改、
bruno-sync.config.json的 menuBindings 键同步更新、种子菜单名（sys_menu）与 tag 的措辞分歧加深。 - gen_bruno.py 映射表：源码 tags 不动，生成器把现有一级名映射为 A 区名（线索管理→A2 线索管理、系统管理→A7 后台管理…）。只有 Bruno 文档生效，swagger 保持旧分组；但生成器已有改名先例（认证→登录、商机管理→商机模块、商机流转→状态流转），一级改名恰好落在既有 seam 上，改动面最小。
- 混合：tags 分批迁移，生成器先行。
裁决需权衡：ADR-0024「tags 即页面归属唯一真相源」纪律的延续性、swagger UI 分组是否需要同步换 A 前缀、menuBindings 同步成本、未来新接口的挂载纪律（新 Controller 该挂什么 tag）。
用户已表态「只是把相关接口都放到同一一级目录下」（机制不设限），但此选择决定 swagger 效果与后续维护纪律，需明确落锤。
票 02 裁决新增的关键输入（2026-08-31）：线索公海池接口（LeadPoolController）需「两个一级目录都放」（A2 线索管理/线索设置 主本 + A7 后台管理/线索规则 副本，同一 tag 幂等双输出）。Controller 的 @Tag 是单值注解，「tags 加 A 前缀」方案（候选 1）天然无法表达双归属——tag 只能携带一个一级前缀，除非生成器对特定 tag 特判；「生成器映射表」方案（候选 2）天然支持（tag → 目录列表）。此约束在裁决时必须纳入权衡。
裁决前勘误（2026-08-31）：上段「候选 1 天然无法表达双归属」的断言不成立——方法级
@Operation(tags)是多值注解，bruno-sync「多值全取、一 tag 一副本」直接支持（OpportunityQueryController.page单方法挂 6 个 tag 为现存先例）。双归属在候选 1 下原生可表达，本票结论不受该断言影响。
Answer
裁决（grilling，2026-08-31）：候选 1——A 区路径进源码 tags，bruno-sync 注解驱动通道为唯一权威机制。 三个分叉逐问落锤：
- Q1 选 1（tags 层实现）：A 区命名写进 Controller tags；swagger/knife4j 同步获得 A 区分组；bruno-sync「tag 原文即路径、多值全取」零改动复现文档树；双归属（票 02）由方法级多值
@Operation(tags)原生表达；gen_bruno.py/gen_opp_*.py/gen_v2_*.py/bru_lib.py手工生成器家族退役（文件留作历史，不再运行）。 - Q2 选 A（深 tag）：tag = 完整页面路径，最深 4 级（如
A7 后台管理/商机规则/公海规则、A3 商机管理/商机详情/主体），保住已裁决的「二级及更深目录不动」。商机侧约 100 个端点需逐个挂方法级页面 tag（线索 25 方法同款纪律先例）；1:1 控制器（整类 = 一个页面文件夹）保留类级@Tag、只改路径字符串。 - Q3 选 A（关闭 URL 回退）：无 tag 端点（
SystemController的用户/部门/管理员角色配置/钉钉组织同步等）全部补显式深 tag；system/游离顶级目录消灭；「进集合的端点必挂 tag」成为一眼可审纪律。
挂载纪律（随 Q3 一并确认）：类级 @Tag 与方法级 @Operation(tags) 互斥使用——并存会触发 bruno-sync「多值全取」产生双份副本（gen_bruno.py 中「登录/认证」双副本先例即此成因）；未来新 Controller 一律按页面全路径挂 tag。
机制联动（供执行票 04 消费）：
- 表述保留策略：现有 .bru 手写表述（表述听人，bruno-sync 铁律 1）通过「先按映射表 git-mv 到目标路径（对账钥匙随所在文件夹换新）→ 再跑 bruno-sync 全量对账」保留：钥匙命中则仅结构 patch、表述逐字不动。
- menuBindings：
bruno-sync.config.json四键随 tags 换A2 线索管理/…前缀；gen_bruno.py的MENUS常量随家族退役一并作废（同源义务消失）。 - swagger 验收口径：knife4j 分组 = 深路径 tag 原文（如
A3 商机管理/商机详情/主体）。 - ADR-0024 修订方向：决策 1 延伸为「tag 命名以原型 A 区页面路径为准：一级 = 分区原文（A0 登录界面…A7 后台管理），二级 = 页面，更深 = 页面内分组」；URL 回退通道关闭记录在案；「业务代码即文档」原则经本裁决强化而非削弱。