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.
61 lines
5.4 KiB
61 lines
5.4 KiB
3 weeks ago
|
# 03 裁剪与补缺方案拍板（修订 ADR-0024）
|
||
|
|
|
||
|
|
Status: resolved (2026-08-17)
|
||
|
|
Type: grilling
|
||
|
|
Blocked by: 02, 04
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
拿着 02 的矩阵 + 04 的完善度审计，与用户逐项拍板（/grilling，一次一问）：
|
||
|
|
|
||
|
|
1. **裁剪机制与真相源**：源码方法级 `@Operation(tags)` 改为每页实挂（swagger UI 同步受益，业务代码即文档）vs 仅 gen_bruno.py / bruno-sync.config.json 层配页面×接口矩阵（源码不动）？
|
||
|
|
2. **裁剪粒度**：查询类（page/detail/stats/列偏好 get+save）是否四菜单全放、命令类逐页裁剪？还是全部逐页严格裁剪？
|
||
|
|
3. **无独立菜单的接口归属**：行政区划（新建/编辑线索表单与线索设置的依赖）、列偏好——保留独立资源文件夹 vs 并入使用它的页面文件夹？
|
||
|
|
4. **幻影处置边界**：从页面文件夹删副本即可，还是有接口应整体下沉/保留在公共位置（防「删没了」）？
|
||
|
|
5. **Bruno 布局**：D 盘当前 Bruno 2 单仓布局（collection 在仓根）vs e 盘产物的 Bruno 3 workspace 布局（collections/ 子目录）——取决于前端 Bruno 版本，需用户提供。
|
||
|
|
6. **D 盘旧结构清理范围**：重复的权限点管理、旧文件夹名、untracked 状态——重生成时如何处置。
|
||
|
|
7. **完善度补缺口径**（结合 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）
|
||
|
|
|
||
|
|
1. WSROOT `e:\code\crm-api-docs` → `D:\code\crm-api-docs`；
|
||
|
|
2. 布局切 Bruno 2 单仓（collection 在仓根，非 collections/ 子目录）；
|
||
|
|
3. 移除 MENU_EXPAND 全量副本机制——源码 tags 实挂后直接按 tags 分组生成；
|
||
|
|
4. region 生成到根级「公共依赖/行政区划/」（region/list、region/level）；create 类 .bru docs 注明依赖；
|
||
|
|
5. 列偏好按 scope 生成四份归各菜单文件夹（bindv 的 scopeKey 机制已有）；
|
||
|
|
6. D 盘清理步骤（决议 6 的四个旧文件夹 + 重复权限点管理）。
|
||
|
|
|
||
|
|
### 后端改动需求（交 05，决议 8）
|
||
|
|
|
||
|
|
1. `follow/batch`、`unfollow/batch`：LeadService + LeadController + 每页实挂 tags + 单测（BatchResult 部分成功语义，与 claim-batch 同构）；
|
||
|
|
2. `create` 增 `followOnCreate`（Boolean，默认 false）：Param DTO + service 创建后自关注 + 文档示例；
|
||
|
|
3. 既有 23+2 个接口 tags 按 02 矩阵四页保留集全量重挂（含 ColumnPreference 两方法改四菜单实挂、Region 改「公共依赖/行政区划」tag）+ `mvn compile` + 全量 BOM 扫描。
|
||
|
|
|
||
|
|
### 前端验收默认方案（map 遗留雾收口）
|
||
|
|
|
||
|
|
不安排专门评审会：交付时 collection.bru 首页写清「按菜单文件夹逐页联调」用法 + baseUrl/登录说明，用户把 D 盘仓指给前端自助联调；异议走 issue 增量修订。
|