luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
149 Commits
1 Branch
0 Tags
405 MiB
 
 
 
 
 
 
Tree: a9f708f205
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a9f708f205'
${ noResults }
crm-backend-matt/.scratch/dict-alignment/issues/05-api-docs-sync.md

5.4 KiB
Raw Blame History

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 改动原样保留。