|
|
|
|
# 11 — Bruno 示例落地：商机+规则族接口示例刷新
|
|
|
|
|
|
|
|
|
|
Type: task
|
|
|
|
|
Status: resolved
|
|
|
|
|
Blocked by: 06, 05
|
|
|
|
|
|
|
|
|
|
## Question
|
|
|
|
|
|
|
|
|
|
按票 06 的机制结论 + `seed-data-manifest.md` 的真实数据，把 `D:/code/crm-api-docs` 中**商机模块 + 商机规则族**全部接口的请求示例替换为真实测试数据：
|
|
|
|
|
|
|
|
|
|
- 每个接口：query / body 示例值 = seed 真实值（真实商机 id、真实字典 code、真实分页参数），响应示例同步补关键回显（若格式支持）；
|
|
|
|
|
- 商机模块范围：列表 / 详情 / 子表族 / 流转操作 / convertible-leads；规则族范围：阶段模板 / 方案卡模板 / 公海规则全接口；
|
|
|
|
|
- **已知缺口（票 01 核实 20260828）**：规则族 25 端点（`/api/rule/opp-stage-template|opp-scheme-template|opp-pool-rule`）当前在集合里**无对应 folder**——执行时先确认票 06 结论：bruno-sync 是否覆盖 crm-rule 源码；若不覆盖需扩 config 后再生，再注示例；**自定义视图 4 端点**（`/api/preference/view/list|save|delete|set-default`，票 04 新增 F15 核实 20260828）同样不在 Bruno 集合，一并补齐；
|
|
|
|
|
- 顺序按票 06 结论定（先 sync 后注示例 or 反之），改完跑一次 `/bruno-sync` 验证示例不丢；
|
|
|
|
|
- **验收口**：用户在 Bruno 里点开任一商机接口，即可照抄发起真实请求拿到真实响应。
|
|
|
|
|
|
|
|
|
|
产出：更新后的集合 + 在 `research-bruno-examples.md` 补一段执行记录。
|
|
|
|
|
|
|
|
|
|
## Answer
|
|
|
|
|
|
|
|
|
|
已解决（20260828）。执行口径：不猜值，全部以 `specimens.json` **32 个实测标本**为数据源（含 8080 补采 stage_versions/scheme_versions）。
|
|
|
|
|
|
|
|
|
|
### 产出
|
|
|
|
|
|
|
|
|
|
- **存量 48 请求示例注入**（`inject-examples.py`）：48 个既有 .bru 的实参块 + docs「请求示例」段换成 seed 真实值（viewType/current/size/keyword、真实商机 id、字典 code）。
|
|
|
|
|
- **规则族 25 + 自定义视图 4 新入集合**（`gen-rules-views.py`）：29 接口 .bru + 4 folder.bru，落 4 个新目录树（商机管理/商机规则/{公海规则,阶段模板,方案卡模板}、销售机会/自定义视图），folder seq 取同父 max+10；真实值来自标本（POOL_ID=748507245062389760、SCHEME_ID=748508098259320832、STAGE_ID=747831302652166144、VIEW_ID=e7b9595f7ea54641b093e9d6bfb096f9——**32 位 hex 非雪花**，handoff 初稿有误以标本为准）。
|
|
|
|
|
- 商机模块接口文件总数 **77** = 71 唯一钥匙 + page/board-cards/board-stage-summary 3 接口 × 3 页面副本多 6 文件。
|
|
|
|
|
- 幂等验证：gen 重跑 33 skipped；`--force` 重写限 OWN_DIRS 白名单防误伤；全仓 209 个 .bru 0 BOM。
|
|
|
|
|
|
|
|
|
|
### 对账结论（`verify_sync.py`）
|
|
|
|
|
|
|
|
|
|
源码侧扫 12 控制器（crm-opportunity 8 + crm-rule 3 商机控制器 + SavedViewController）提 `@(Get|Post)Mapping`，与文件侧 docs 首行钥匙三向对比：**71 唯一钥匙全命中、双零差集**。⚠ 正则勘误：`@PostMapping` 无参形态（OpportunityCreateController 新建商机，端点=类级 base）初版漏扫，已修正为可选路径组。结论：sync 若重跑，结构已镜像源码 → 全部「不动」；实参值与示例在 docs 块属表述（SKILL 铁律 1）→ 不会丢。
|
|
|
|
|
|
|
|
|
|
### 新契约事实（本次实测沉淀）
|
|
|
|
|
|
|
|
|
|
- **board 两端点源码无 viewType 参数**（OpportunityCollabController：stage-summary 只收 stageTemplateId、cards 只收 stageId/offset/limit）——e2e 发的 viewType 被 Spring 静默忽略 = **D-20「公海看板未过滤」根因**；.bru 参数表本来就对。
|
|
|
|
|
- **scopeKey 实测值=`opportunity`**（seed/demo/e2e 全用此值）；⚠ `OpportunityViewQueryImpl` 内部常量 `SAVED_VIEW_SCOPE="opportunity.sales"` 与前端写入 scope 不一致——列表页 savedViewId 叠加可能读不到已保存视图，**疑似新缺陷候选，未实测**。
|
|
|
|
|
- view/save 是 viewId upsert（空=新建非空=覆盖编辑）；删除/设默认走 form `scopeKey&viewId`。
|
|
|
|
|
- nodes/fields **索引式表单绑定**（`nodes[0].stageDictCode=…`，e2e-rules R02/R03 实测通过）；deptIds 逗号分隔字符串。
|
|
|
|
|
- publish 自我顶替（同 code 发布中新版顶旧版）；阶段模板末位固定节点 OPP_STAGE_05 系统保证、入参不可伪造。
|
|
|
|
|
- `Result<Void>` data=null 非失败（删除/设默认等写操作）。
|
|
|
|
|
- versions 实体直出泄露 creatorId/updaterId/deleted（违 ADR-0017，D-19 在 stage/scheme versions 补采中同样坐实）。
|
|
|
|
|
|
|
|
|
|
### 验收口
|
|
|
|
|
|
|
|
|
|
Bruno 里点开任一商机接口，实参块即 seed 真实值（起服见 map.md 环境；debug token userId=739564171091247104），照抄即可发真实请求拿真实响应。详见 `research-bruno-examples.md` 执行记录段 + `specimens.json`。
|
