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.
|
|
|
|
# 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 布局废弃）。
|
