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.
39 lines
4.7 KiB
39 lines
4.7 KiB
6 days ago
|
# 01 一级目录改造机制选型
|
||
|
|
|
||
|
|
Type: grilling
|
||
|
|
Status: resolved
|
||
|
|
Blocked by: (无)
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
一级目录重排在哪一层实现？候选：
|
||
|
|
|
||
|
|
1. **Controller tags 加 A 区前缀**：tag 变为「A2 线索管理/线索公海」形式。swagger UI 同步按 A 区分组，延续 ADR-0024「业务代码即文档」纪律；代价是 17+ 个 Controller 的 tags 全改、`bruno-sync.config.json` 的 menuBindings 键同步更新、种子菜单名（sys_menu）与 tag 的措辞分歧加深。
|
||
|
|
2. **gen_bruno.py 映射表**：源码 tags 不动，生成器把现有一级名映射为 A 区名（线索管理→A2 线索管理、系统管理→A7 后台管理…）。只有 Bruno 文档生效，swagger 保持旧分组；但生成器已有改名先例（认证→登录、商机管理→商机模块、商机流转→状态流转），一级改名恰好落在既有 seam 上，改动面最小。
|
||
|
|
3. **混合**：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 注解驱动通道为唯一权威机制。** 三个分叉逐问落锤：
|
||
|
|
|
||
|
|
1. **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` 手工生成器家族**退役**（文件留作历史，不再运行）。
|
||
|
|
2. **Q2 选 A（深 tag）**：tag = 完整页面路径，最深 4 级（如 `A7 后台管理/商机规则/公海规则`、`A3 商机管理/商机详情/主体`），保住已裁决的「二级及更深目录不动」。商机侧约 100 个端点需逐个挂方法级页面 tag（线索 25 方法同款纪律先例）；1:1 控制器（整类 = 一个页面文件夹）保留类级 `@Tag`、只改路径字符串。
|
||
|
|
3. **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 回退通道关闭记录在案；「业务代码即文档」原则经本裁决强化而非削弱。
|