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.
50 lines
5.4 KiB
50 lines
5.4 KiB
5 hours ago
|
# 05 — 接口文档同步
|
||
|
|
|
||
|
|
**Type:** task (HITL)
|
||
|
|
**Status:** resolved (20260907)
|
||
|
|
**Blocked by:** 04, 07
|
||
|
|
|
||
|
|
## What to build
|
||
|
|
|
||
|
|
票 04/07 改造落地后同步接口文档（文档仓 `D:/code/crm-api-docs`，生成方式 `.scratch/bruno-coldstart/gen_bruno.py` + `.scratch/bru_lib.py` 幂等脚本）：
|
||
|
|
|
||
|
|
1. **menuBindings 补条目**：`bruno-sync.config.json` 加「A7 后台管理/数据字典」绑定（现状 A7 只有客户管理设置；folder 仅 name/seq 无绑定）。
|
||
|
|
2. **.bru 漂移修正**（票 02 盘出的三处 + 新增）：
|
||
|
|
- `字典项分页.bru`：keyword 说明补 value 列（代码实际匹配 name/code/value）
|
||
|
|
- 响应表补 `parentId`、`children` 字段
|
||
|
|
- `orderBy`/`asc` 参数标注「收了不用，排序固定 sort_no 空排后 create_time」（或随代码清理）
|
||
|
|
- 票 04 改造后的行为更新：键值必填、默认项禁停文案、换组规则、分组弹窗可改状态、（若做）/item/tree 新端点文档
|
||
|
|
3. **tag 核对**：现 tag 为「A7 后台管理/数据字典-分组 / -字典项」两个方法级 tag——按 ADR-0024 菜单粒度确认是否合并为「数据字典」单一菜单 tag（对照权威树 `.scratch/api-docs-reorg/lanhu-tree-v29.md` 的 A7-5-1）。
|
||
|
|
4. **再生成与校验**：跑生成脚本，端点/参数/示例值与代码一致，12+ 端点无缺漏。
|
||
|
|
|
||
|
|
**验收**：文档端点清单 = 代码端点清单（diff 为空）；示例值合法；menuBindings 生效。
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
20260907 执行完毕。**bruno-sync 无命令行**——它是 agent skill（`C:\Users\luowj\.qoder\skills\bruno-sync\SKILL.md`），按 ADR-0024（2026-08-31 修订）为注解驱动通道唯一权威机制；本次由本会话按其铁律（结构听源码、表述听人、不做 git 操作、宁停不删）手工对账执行，退役生成器家族（gen_bruno.py 等）未运行。
|
||
|
|
|
||
|
|
**文档仓路径**：`E:\code\crm-api-docs` **不存在**（E 盘无此目录），按指示回退 **`D:\code\crm-api-docs`**（`bruno-sync.local.json` 亦指向 D 盘；ADR-0024 的「现路径 E 盘」系换机记录，本机实况为 D 盘）。
|
||
|
|
|
||
|
|
**源码侧**：
|
||
|
|
1. 两个 Controller 类级 @Tag 改为斜杠形式：`DictGroupController.java:24` → `A7 后台管理/数据字典/分组`、`DictItemController.java:25` → `A7 后台管理/数据字典/字典项`（仅动 @Tag 行）。
|
||
|
|
2. 回归：`mvn -pl crm-dict -am test -s settings.xml` → **55/55 全绿**，BUILD SUCCESS。
|
||
|
|
3. `bruno-sync.config.json` menuBindings 增加 `"A7 后台管理/数据字典": { "viewType": null, "scopeKey": null }`（仿「A4 客户管理/客户交割」写法），JSON 校验通过。
|
||
|
|
|
||
|
|
**文档仓变更**（全部留工作区，未 commit）：
|
||
|
|
- 目录：新建 `A7 后台管理/数据字典/`（folder.bru seq 2，仿 `商机规则` 惯例）；`数据字典-分组/` → `数据字典/分组/`、`数据字典-字典项/` → `数据字典/字典项/`（filesystem mv，表述原样保留；folder.bru name 改为 `分组`/`字典项`，seq 1/2）。旧两个后缀文件夹从工作区消失（git status = 旧路径 13 个 D + 新目录 ??，另有并行代理的 A4 改动未碰）。
|
||
|
|
- 端点：**13/13 全覆盖**（group 5 + item 7 + 新增 tree）。新增 `字典项/启用项两级树.bru`（`GET /api/dict/item/tree`，seq 8，generated 标记、query 传 groupCode、响应两层嵌套 children）。
|
||
|
|
- patch：对既有 12 个 .bru 及 A7 README 共 **20 处替换**，全部以「Write 载荷 JSON + python str.replace」落地，每处断言恰好命中一次（20/20 零失败）。要点：
|
||
|
|
- 字典项分页：keyword 说明补 **value** 列；响应表补 `parentId`/`children`（响应示例同步补字段）；`orderBy`/`asc` 保留列出（来自 BaseParam）并标注「收了不用：排序固定 sort_no 空排后、create_time 升序」。
|
||
|
|
- 新建编辑字典项：摘要反映新行为（键值必填、编码创建后只读、未被引用且无子项可换组、默认项禁停）；参数表补 `parentId` 行；value 改必填（空白报 63001）；status 行标注改停用撞默认项拦截（**63013**：该字典为分组默认项，请先取消默认或指定其他默认项——与代码文案一致）。
|
||
|
|
- 字典项启停：旧「停用自动取消默认」改为「分组默认项禁止停用（63013）」。
|
||
|
|
- 删除字典项：阻断条件补全为「内置、被引用（63009）或下有子项」。
|
||
|
|
- 新建编辑分组：摘要与 status 行改为「编辑时状态可改，保存即生效」（拍板 5）。
|
||
|
|
- A7 README（人工维护件）：两目录行更新为新路径、字典项 7→8、总数 61→62。
|
||
|
|
|
||
|
|
**验证**：源码 13 端点 vs 文档 13 个 generated .bru 双向差集为空；每把钥匙（METHOD+url）与 .bru url 字段逐一相符；改动文件及数据字典全树 BOM 扫描无命中；设为默认项/强制删除/分组启停/启用列表等其余文件核对与代码一致、未动表述。
|
||
|
|
|
||
|
|
**没做 / 矛盾上报**：
|
||
|
|
1. **源码注解滞后（矛盾，未修）**：`DictGroupController.saveOrUpdate` 的 `@Operation` summary 仍写「编辑时编码/内置标记/状态只读」，与票 04 已落地行为（`DictGroupServiceImpl.saveGroup` 编辑分支已放开 status）不符。本次约束只允许改 @Tag 行，故仅将文档表述更新为实际行为，源码注解建议后续顺手修正。
|
||
|
|
2. E 盘路径不存在，用 D 盘（如上，如实报告）。
|
||
|
|
3. 未 commit 主仓库与文档仓；文档仓工作区中并行代理的 A4 改动原样保留。
|