luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
137 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: 2329f8cf14
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2329f8cf14'
${ noResults }
crm-backend-matt/docs/adr/0024-bruno-docs-grouping-by...

6.9 KiB
Raw Blame History

0024. Bruno 接口文档页面归属采用菜单粒度

状态: 已接受

冷启动生成的 collection 按类级 @Tag 聚合：LeadController 类级 @Tag("线索管理") 导致 23 个接口平铺在一个文件夹，而文档受众是前端，心智模型是菜单页——「我开发 /lead/public-pool，要用哪些接口、viewType 传什么」。菜单有两处候选真相源：LeadPermissionInitializer seed（公海 / 我的线索 / 我的关注 / 线索管理，挂「线索管理」目录）与产品原型（线索管理一级文件夹 → 线索公海 / 我的线索 / 我的关注 / 线索管理 / 线索设置），措辞不完全一致。

决策

  1. 文档页面归属 = 菜单粒度，tag 命名以产品原型为准：线索管理/线索公海、线索管理/我的线索、线索管理/我的关注、线索管理/线索管理；「线索规则-公海池配置」改名「线索管理/线索设置」对齐原型。行政区划无菜单对应，保留资源命名。
  2. 真相源双层：归属 = Controller 方法级 @Operation(tags)（LeadController 23 个方法、ColumnPreferenceController 2 个方法全量挂 4 菜单；删除两处类级 @Tag，避免多出聚合文件夹）；参数语义 = bruno-sync.config.json 的 menuBindings（菜单 → viewType / scopeKey 专属值，生成器据此在副本中替换示例值并注明「本页固定传」）。
  3. 四菜单共用接口全量副本（不做接口级页面裁剪）：按钮显隐由前端权限点运行时控制（权限码全集下发接口已立 ticket .scratch/auth-perms/），文档不预估页面按钮集。
  4. 副本幂等维护：gen_bruno.py 重跑覆盖，前端只读；手改会在下次同步时丢失。
  5. scope_key 四值钉死（与 viewType 一一对应）：lead.public_pool / lead.my_lead / lead.my_follow / lead.manage。
  6. 视图对照：线索公海=PUBLIC_POOL=lead.public_pool · 我的线索=MY_LEAD=lead.my_lead · 我的关注=MY_FOLLOW=lead.my_follow · 线索管理=MANAGE=lead.manage（glossary 同步收词）。

考虑过的替代

  • 只把 page / stats / 列偏好按菜单出副本，命令接口留公共文件夹——被否：前端要单页自足，且「页面 × 命令」矩阵无真相源（button 权限点未 seed）。
  • 不改源码、纯 config 覆盖映射——被否：swagger UI 同样受益于菜单分组，映射应进业务代码（业务代码即文档）。
  • 生成器自行推断页面接口集——被否：无源可依，等同编故事，违背「结构听源码」铁律。

后果

  • collection 从 66 涨到 141 个 .bru；21 个命令接口副本零参数差异（仅 docs 前缀【X 页】不同），为已知代价，用户已确认前端不手改文档。
  • menuBindings（config）与 gen_bruno.py 的 MENUS 常量需人工保持同源。
  • seed 菜单名「公海」与原型「线索公海」不一致：seeder 按 name find-or-create，直接改字符串会 seed 出第二个菜单，需数据迁移（UPDATE sys_menu）才能统一——遗留待办，文档侧命名先行以原型为准。
  • swagger UI 分组从 1 个「线索管理」变为 4 个菜单组，前端打开后端 swagger 同样按菜单导航。

修订（2026-08-17，lead-docs-audit effort）

决策 3「四菜单全量副本」推翻：实测每页文件夹 40%~60% 的接口在该页无入口（research 02 逐页矩阵），前端反馈迷惑。修订为每页实挂：

  • tags 只挂有真实页面入口的菜单（真相源 = 蓝湖原型逐页交互矩阵，.scratch/lead-docs-audit/research/02-page-endpoint-matrix.md）；LeadController 25 个（含新增 follow-batch/unfollow-batch）+ ColumnPreference 2 个方法按矩阵实挂，未来新接口同样按「真实入口才挂 tag」纪律。
  • 四页保留集：公海 10 + 我的线索 12 + 我的关注 8 + 管理 13（Lead 接口，另各页列偏好 ×2）；region 归档「公共依赖/行政区划」（无菜单，被三处表单依赖）；列偏好随 scope 四页各一份。
  • 不设全量总览文件夹（全量副本复辟禁止）。
  • 决策 2 强化：tags 即页面归属唯一真相源；gen_bruno.py 忠实读 tags（MENU_BIND 仅做参数值绑定，不再做副本展开）。
  • 决策 1/4/5/6 不变。产物重建于 D:\code\crm-api-docs（Bruno 2 单仓，前端实际消费仓；e 盘 workspace 布局废弃）。

修订（2026-08-31，api-docs-reorg effort）

一级目录对齐蓝湖原型 A 区：v29 快照（2026-08-31）冻结为权威树（.scratch/api-docs-reorg/lanhu-tree-v29.md），文档仓一级目录改为 A0 登录界面 / A1 销售工作台（首页）/ A1X 工作计划 / A2 线索管理 / A3 商机管理 / A4 客户管理 / A5 项目管理 / A6 数据看板 / A7 后台管理 / 公共依赖 / 调试(验证专用)，与原型 A 区分区一一对应；二级及更深目录不做重排。

  1. 深 tag 纪律：tag = 完整页面路径——一级 = 分区原文，二级 = 页面，更深 = 页面内分组（最深 4 级，如 A7 后台管理/商机规则/公海规则）。tag 原文即文档目录路径（bruno-sync 身份映射），swagger/knife4j 分组同构。决策 2 的 menuBindings（viewType/scopeKey 绑定）不变，四键前缀随本修订换为 A2 线索管理/…。
  2. 商机规则归 A7（决策 1 页面归属修正）：v29 将 A3-4 商机管理设置整体迁至 A7-3-2 商机规则，后台为唯一入口，阶段模板 / 方案卡模板 / 公海规则三组接口改挂 A7 后台管理/商机规则/{阶段模板,方案卡模板,公海规则}。线索规则接口（LeadPoolController）对称裁决为双归属：A2 线索管理/线索设置（主本，功能页所在）+ A7 后台管理/线索规则（副本，A7-3-1 为 A2-1-5 的引用页）。
  3. 双归属 = 方法级多值 @Operation(tags)：单接口挂 N 个 tag 即在 N 个页面文件夹各有一份副本，由 bruno-sync「多值全取」幂等输出，无需生成器特判。
  4. URL 回退通道关闭：无 tag 端点不再按 URL 兜底分组——全部端点必须显式挂深 tag（SystemController 10 端点已补挂，system/ 游离顶级目录消灭）；「进集合的端点必挂 tag」成为一眼可审纪律。
  5. 新接口挂载纪律：新 Controller 一律按页面全路径挂 tag——1:1 页面控制器可用类级 @Tag，跨页 / 双归属用方法级多值 tags；类级 @Tag 与方法级 @Operation(tags) 互斥，并存会因「多值全取」产生双份副本；无真实页面入口的接口不挂页签（2026-08-17 修订纪律延续）。
  6. 机制联动：bruno-sync 注解驱动通道为唯一权威机制；手工生成器家族（gen_bruno.py / gen_opp_*.py / gen_v2_*.py / bru_lib.py）退役留档、不再运行，其 MENUS 常量同源义务随之作废；分区索引 README 为人工维护件（bruno-sync 不生成 README）。文档仓现路径 E:\code\crm-api-docs（2026-08-31 换机记录，前值 D:\code\crm-api-docs 作废）。