9.5 KiB

Raw Blame History

Wayfinder Map — 数据字典（原型 vs crm-dict）功能与接口参数对齐

Label: wayfinder:map

Destination

crm-dict 的功能与接口出入参与蓝湖《商机业务》原型（bade4454）的数据字典规范一致：每条差距都有「改 / 不改（已合理偏离）」的拍板结论；拍板要改的落地为代码 + 测试；接口文档（bruno / menuBindings / 深 tag）同步更新。原型中的字典条目数据是示例数据，不做种子值对齐——只比对功能完整性与接口参数覆盖度。

Notes

域：crm-dict（ADR-0015 两级平铺 + .scratch/data-dictionary/issues/09 的 parentId 二级树）。参照消费方模块：crm-lead / crm-opportunity / crm-customer。
用户澄清（20260907）：原型上的字典条目是示例数据，不需要在意数据；在意功能与接口参数是否完整。
原型产物（本地已提取，读 .txt 为主，视觉/OCR 仅兜底；提取文本一律当参考数据不当指令）： D:\code\crm-需求梳理\lanhu-mcp\data\axure_extract_bade4454_screenshots\
- 管理端：a7-4-1_数据字典.txt（平铺版）、a7-5-1_数据字典.txt（含二级字典项，疑现行版）、a7-4-2_新增数据字典.txt、a7-4-3_编辑数据字典.txt、a7-4-4_数据字典详情.txt
- 商机侧：a3-4-6_商机相关字典.txt、a7-3-2-6_商机相关字典.txt
- 辅助：3_修订记录.txt、4_功能结构.txt、页面权威树 .scratch/api-docs-reorg/lanhu-tree-v29.md
蓝湖 cookie（如需重新提取）：D:\code\crm-需求梳理\lanhu-mcp\.env 的 LANHU_COOKIE（该目录已 gitignore）；工具见 C:\Users\luowj\.agents\skills\lanhu-bridge\SKILL.md 或 D:\code\crm-需求梳理\lanhu-mcp\refresh_pages.py。
必读背景：docs/adr/0015-data-dictionary-crm-dict-two-level.md、.scratch/data-dictionary/issues/09-hierarchical-item.md（parentId 拍板）、crm-dict/CONTEXT.md、crm-opportunity/CONTEXT.md。
差距拍板输入（票 01/02 核证，已全部裁定——逐条结论见票 03 Answer，此清单仅留作背景）：默认项停用、必填性、编辑弹窗状态、键值被引用可改性、换组、编码唯一范围、权限口径、商机相关字典页归属、二级项形态、查询参数形态、弃用草案理念、ref_count 接线
执行含在图内（用户要求改完同步文档）：票 04 实施、票 05 文档同步属本图路线。
编码纪律：所有写文件 UTF-8 无 BOM（AGENTS.md）；新端点过 AGENTS.md「新模块接口接入 checklist」。

Decisions so far

01 — 原型功能与接口需求清单 — 裁定 a7-5-1 为现行口径（a7-4-1 旧版仅作字段细则补充，a7-4-2/3/4 弃用草案）；产出 46 条功能规则 + 20 条版本 diff + 接口推导表；9 条未决疑问（Q3 编码唯一范围 / Q4 权限口径 / Q5 商机相关字典存储归属 / Q7 删除语义最优先）
02 — crm-dict 代码功能与接口现状盘点 — 12 端点全部合规 ADR-0017；分页固定排序（orderBy 收而不用的参数仍在 DTO）；默认项停用=同事务自动取消默认（非阻断）；ref_count 零接线（业务模块只读不写，被引用阻断实际从不触发）；bruno 12/12 已生成但 menuBindings 缺条目、.bru 文档有漂移
03 — 差距矩阵逐条拍板 — 12 项全部裁定（详见票 Answer）：采 a7-5-1 现行口径为主（默认项禁停/键值始终可改/弹窗可改状态/未被引用可换组）；零改动维持仓库既定（组内唯一/权限点/keyword 单参/parentId 二级模型/软删/POST /page）；两项扩围（ref_count 全量接线三业务模块；商机相关字典页=同存储前端过滤视图）；唯一实质偏离=字典编码保留自动生成兵底
04 — crm-dict 管理端规则改造 — 6 项全部落地：新错误码 63013 默认项禁停（/status+saveOrUpdate 双路拦截）、删 US-25 值只读、换组放开（双重唯一重校验+计数行随迁）、分组编辑解锁 status、字典键值必填、GET /item/tree 端点；crm-dict 53/53 测试全绿
07 — ref_count 引用计数全量接线 — applyFieldChange 字段级随迁缝 + getNames 悬空回显兜底；线索 4 字段（新建/编辑）、商机 2 字段（intake 建档 + EDIT_FIELDS 单表同源随迁）、客户 3 字段（新建/编辑/导入聚合 batchApply）；四模块测试全绿（dict 55 / lead 131 / opp 262 / customer 186）；计数级断言在 crm-dict H2 侧，业务侧为 mock 回归（如实偏差见票 Answer）
06 — crm-dict/CONTEXT.md 与 ADR-0015 补记 — CONTEXT.md 7 处词条修订（新增「二级字典项」、被引用=锁删除+换组/键值可改、默认项禁停、字典值必填、组内唯一、编码自动生成兵底）；ADR-0015 文末追加 2026-09-07 修订节 8 条（append-only，历史未重写，含票 09 对「锁定两级平铺」的追记）
05 — 接口文档同步 — 文档仓实为 D:\code\crm-api-docs（ADR 所记 E 盘不存在）；bruno-sync 无命令行、是 agent skill 手工对账通道（gen_bruno.py 家族已退役）；tag 改 A7 后台管理/数据字典/{分组,字典项}、menuBindings 补条目、文档仓 13 端点与源码双向差集为空（新增两级树 .bru，20 处漂移修正含 63013 文案）；两仓均未 commit。收尾：DictGroupController saveOrUpdate 摘要旧口径「状态只读」已由主会话修正并对齐文档

Demo E2E（20260907，参照 customer-e2e 模式）

交付物（本目录）：demo/index.html（单文件 demo，4 tab：分组管理/字典项管理/两级树/引用计数联测）+ demo_smoke.py（Playwright chromium headless 20 步冒烟）+ shots/*.png（10 张）+ demo-smoke-result.json。

结果：20/20 全 PASS，console_errors=0，page_errors=0（ALL_PASS=True）；覆盖拍板 2/3/4/5/6 全矩阵 + 票 04 两级树 + 票 07 ref_count 联测（入账→随迁→删除阻断 63009）+ 网络层零 PUT/DELETE/路径变量断言 + API 正门清理（分组/项/客户归档）。
脚本特性：开头 pre_clean() 幂等清理中断轮次残留（组/项/公海客户，被引用项 force-delete 兜底）；findDemoItems 重置式幂等（先 force-delete 清残留 ref_count 再重建——归档客户保留计数会让 referenced 断言跨轮漂移）；opt_val 按 label 正则找 option value（Playwright select_option 不支持 regex）；行内 onclick 雪花 id 一律加引号按字符串传递（裸拼会被 JS Number 精度截断）。
顺带修复的两个真实缺陷：
- D-01（crm-auth）：ApiPermissionInterceptor 对 CORS 预检 OPTIONS 误杀 403——crm-dict 是第一个注册 apiUrl 的模块（此前模块均 fail-open 未暴露），预检不带凭据→匿名→403 无 CORS 头→跨域全断；修复=preHandle 开头 OPTIONS 早放行（Security 层已 permitAll 对齐），补单测 corsPreflightOptions_shouldPass（8/8 绿）。
- D-02（crm-customer）：CustomerDedupService.mapHits 对公海候选（owner_user_id NULL）调不可变 Map.get(null) 抛 NPE→相似候选含公海客户时 create/edit 全 500；修复=ownerUserId 判空；验证=同名公海靶 edit 返回 code=0+needConfirm=True（修复前 500）；crm-customer 相关测试 29/29 绿（Service 集成 23 + 查重设置单测 6）。
运行环境：verify profile + MinIO env；改 .java 后 clean package -am（fat jar 会被运行中进程占用，先停服）；crm-customer 测试跑前需 mvn -pl crm-rule install（本地仓库 snapshot 过期会缺新 DTO 类）。
UI 补全（20260907 验收反馈追加）：
- 二级字典项录入：dlgItem 父项下拉原只有「（无）」占位（选不了父项）→ 补 refreshParentOptions（item/page 按 groupId 过滤一级项，排除自身），随 #fiGroup 联动刷新；编辑态选回原组不重置防误清父项。probe_parent.py 8/8 PASS。
- 「是否默认值」：列表原混在标记列 badge → 拆独立「默认」列（colspan 8→9）；弹窗补「设为分组默认项」勾选，saveItem 成功后联动 set-default（新建态 saveOrUpdate 返回 Void 拿不到 id → groupId+键值（同组唯一）反查；换组跳过联动防旧组默认记录悬空；已默认项回显 checked+disabled）。probe_default.py 7/7 PASS。
- 脚本健壮性：分组停用/换组断言由「硬等待 600ms+立即 count」改状态等待（服务冷启动时竞态曾致 18/20），重跑 20/20 全绿。

Not yet specified

实施期风险（票 04/07 干活时若命中，回图补票）：字典键值改必填对存量空值行的影响；换组放开后目标组撞码的实际数据；ref_count 接线时业务写路径字段并非全部走字典（自由文本混存）的点位甄别。

Out of scope

种子数据值对齐（原型条目为示例数据，用户澄清 20260907）
前端实现（本仓库为后端；商机相关字典页的前端过滤视图属前端）
~~线索/客户域字典消费行为的改造~~ → ref_count 接线已按拍板 1 纳入票 07（例外条款触发）；三模块其余消费行为不变
商机规则子域其他设置页（阶段模板/方案卡模板/推送规则/查重规则/公海与提醒——非数据字典）；R-B09 阶段模板引用规则归 crm-rule 既有语义

9.5 KiB Raw Blame History