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.
4.3 KiB
4.3 KiB
0024. Bruno 接口文档页面归属采用菜单粒度
状态: 已接受
冷启动生成的 collection 按类级 @Tag 聚合：LeadController 类级 @Tag("线索管理") 导致 23 个接口平铺在一个文件夹，而文档受众是前端，心智模型是菜单页——「我开发 /lead/public-pool，要用哪些接口、viewType 传什么」。菜单有两处候选真相源：LeadPermissionInitializer seed（公海 / 我的线索 / 我的关注 / 线索管理，挂「线索管理」目录）与产品原型（线索管理一级文件夹 → 线索公海 / 我的线索 / 我的关注 / 线索管理 / 线索设置），措辞不完全一致。
决策
- 文档页面归属 = 菜单粒度，tag 命名以产品原型为准：
线索管理/线索公海、线索管理/我的线索、线索管理/我的关注、线索管理/线索管理；「线索规则-公海池配置」改名「线索管理/线索设置」对齐原型。行政区划无菜单对应，保留资源命名。 - 真相源双层：归属 = Controller 方法级
@Operation(tags)（LeadController 23 个方法、ColumnPreferenceController 2 个方法全量挂 4 菜单；删除两处类级@Tag，避免多出聚合文件夹）；参数语义 =bruno-sync.config.json的menuBindings（菜单 → viewType / scopeKey 专属值，生成器据此在副本中替换示例值并注明「本页固定传」）。 - 四菜单共用接口全量副本（不做接口级页面裁剪）：按钮显隐由前端权限点运行时控制（权限码全集下发接口已立 ticket
.scratch/auth-perms/），文档不预估页面按钮集。 - 副本幂等维护：
gen_bruno.py重跑覆盖，前端只读；手改会在下次同步时丢失。 - scope_key 四值钉死（与 viewType 一一对应）：
lead.public_pool/lead.my_lead/lead.my_follow/lead.manage。 - 视图对照：线索公海=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 布局废弃）。