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.
5.4 KiB
5.4 KiB
03 裁剪与补缺方案拍板（修订 ADR-0024）
Status: resolved (2026-08-17) Type: grilling Blocked by: 02, 04
Question
拿着 02 的矩阵 + 04 的完善度审计，与用户逐项拍板（/grilling，一次一问）：
- 裁剪机制与真相源：源码方法级
@Operation(tags)改为每页实挂（swagger UI 同步受益，业务代码即文档）vs 仅 gen_bruno.py / bruno-sync.config.json 层配页面×接口矩阵（源码不动）？ - 裁剪粒度：查询类（page/detail/stats/列偏好 get+save）是否四菜单全放、命令类逐页裁剪？还是全部逐页严格裁剪？
- 无独立菜单的接口归属：行政区划（新建/编辑线索表单与线索设置的依赖）、列偏好——保留独立资源文件夹 vs 并入使用它的页面文件夹？
- 幻影处置边界：从页面文件夹删副本即可，还是有接口应整体下沉/保留在公共位置（防「删没了」）？
- Bruno 布局：D 盘当前 Bruno 2 单仓布局（collection 在仓根）vs e 盘产物的 Bruno 3 workspace 布局（collections/ 子目录）——取决于前端 Bruno 版本，需用户提供。
- D 盘旧结构清理范围：重复的权限点管理、旧文件夹名、untracked 状态——重生成时如何处置。
- 完善度补缺口径（结合 04）：示例值/枚举/错误码/响应注释补到什么程度，哪些靠 gen_bruno.py 机制、哪些靠数据补齐。
产出：ADR-0024 修订（或接续新 ADR）+ gen_bruno.py 改造需求清单，交给 05 执行。
Answer
2026-08-17 与用户两轮 8 问全部拍定（均采纳推荐方案）：
| # | 问题 | 决议 |
|---|---|---|
| 1 | 裁剪机制与真相源 | 源码方法级 @Operation(tags) 每页实挂——单源真相，swagger UI 同步受益；gen_bruno.py 忠实读 tags，不自设页面×接口矩阵 |
| 2 | 裁剪粒度 | 全部严格按 02 矩阵逐页裁——查询类四页皆有入口是事实非宽放；未来新接口同样按「真实入口才挂 tag」纪律 |
| 3 | region / 列偏好归属 | region 保留独立文件夹（参数无差别，副本无增益）：落位 D 盘根级「公共依赖/行政区划/」；3 个表单页的 create .bru docs 注明依赖。列偏好按 scope 各归各菜单文件夹（四份不同参数，本质是四页各自的接口） |
| 4 | 幻影处置边界 | 只删该页副本，不设全量总览文件夹——32 个接口全部有真实入口页，删副本不删接口；全量索引 = ADR-0024 决策 3 复辟，禁止 |
| 5 | Bruno 布局 | 维持 D 盘 Bruno 2 单仓（collection 在仓根）——前端工具假设零变化，只换内容 |
| 6 | D 盘旧结构清理 | 线索域全清 + 去重：删旧平铺「线索管理/」23 个、「线索规则-公海池配置/」（旧名）、「线索规则-行政区划/」、「列偏好/」，生成新菜单结构；另删根目录重复「权限点管理/」（保留系统管理/下那份）；git 提交由用户执行 |
| 7 | 完善度口径 | 全量机制化补齐：参数六元组（名称/类型/必填/示例/说明/枚举）、PageResult/BatchResult、status 七态枚举、典型报错（401/403/业务码）；修 collection.bru 两处失效文案；baseUrl 与登录说明写清 |
| 8 | 缺失 3 项处置 | 本期一并实现：follow-batch / unfollow-batch 后端补接口（Service+Controller+tags+单测）；create 加 followOnCreate 参数（原型「是否关注」复选，PRD §6.1）——文档与原型彻底对齐，零「暂缺」标注 |
ADR-0024 修订要点（05 落盘为新 ADR 或修订）
- 决策 1（菜单粒度分组）：保留。
- 决策 2（tags 机制驱动）：保留并强化——tags 从「全量四菜单」改为「每页实挂」：接口在哪个页面有入口就只挂哪个菜单 tag。
- 决策 3（四菜单全量副本）：推翻——以蓝湖原型逐页交互为真相源（research 02 矩阵），每页文件夹 = 该页真实需要的接口，不多不少。
- 补记两个例外：region 独立「公共依赖/行政区划」文件夹；列偏好四 scope 随页归档。
gen_bruno.py 改造需求（交 05）
- WSROOT
e:\code\crm-api-docs→D:\code\crm-api-docs； - 布局切 Bruno 2 单仓（collection 在仓根，非 collections/ 子目录）；
- 移除 MENU_EXPAND 全量副本机制——源码 tags 实挂后直接按 tags 分组生成；
- region 生成到根级「公共依赖/行政区划/」（region/list、region/level）；create 类 .bru docs 注明依赖；
- 列偏好按 scope 生成四份归各菜单文件夹（bindv 的 scopeKey 机制已有）；
- D 盘清理步骤（决议 6 的四个旧文件夹 + 重复权限点管理）。
后端改动需求（交 05，决议 8）
follow/batch、unfollow/batch：LeadService + LeadController + 每页实挂 tags + 单测（BatchResult 部分成功语义，与 claim-batch 同构）；create增followOnCreate（Boolean，默认 false）：Param DTO + service 创建后自关注 + 文档示例；- 既有 23+2 个接口 tags 按 02 矩阵四页保留集全量重挂（含 ColumnPreference 两方法改四菜单实挂、Region 改「公共依赖/行政区划」tag）+
mvn compile+ 全量 BOM 扫描。
前端验收默认方案（map 遗留雾收口）
不安排专门评审会：交付时 collection.bru 首页写清「按菜单文件夹逐页联调」用法 + baseUrl/登录说明，用户把 D 盘仓指给前端自助联调；异议走 issue 增量修订。