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.
59 lines
9.5 KiB
59 lines
9.5 KiB
4 hours ago
|
# 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](issues/03-gap-matrix-grilling.md)，此清单仅留作背景）：默认项停用、必填性、编辑弹窗状态、键值被引用可改性、换组、编码唯一范围、权限口径、商机相关字典页归属、二级项形态、查询参数形态、弃用草案理念、ref_count 接线
|
||
|
|
- **执行含在图内**（用户要求改完同步文档）：票 04 实施、票 05 文档同步属本图路线。
|
||
|
|
- **编码纪律**：所有写文件 UTF-8 无 BOM（AGENTS.md）；新端点过 AGENTS.md「新模块接口接入 checklist」。
|
||
|
|
|
||
|
|
## Decisions so far
|
||
|
|
|
||
|
|
- [01 — 原型功能与接口需求清单](issues/01-prototype-feature-inventory.md) — 裁定 a7-5-1 为现行口径（a7-4-1 旧版仅作字段细则补充，a7-4-2/3/4 弃用草案）；产出 46 条功能规则 + 20 条版本 diff + 接口推导表；9 条未决疑问（Q3 编码唯一范围 / Q4 权限口径 / Q5 商机相关字典存储归属 / Q7 删除语义最优先）
|
||
|
|
- [02 — crm-dict 代码功能与接口现状盘点](issues/02-code-inventory.md) — 12 端点全部合规 ADR-0017；分页固定排序（orderBy 收而不用的参数仍在 DTO）；默认项停用=同事务自动取消默认（非阻断）；**ref_count 零接线**（业务模块只读不写，被引用阻断实际从不触发）；bruno 12/12 已生成但 menuBindings 缺条目、.bru 文档有漂移
|
||
|
|
- [03 — 差距矩阵逐条拍板](issues/03-gap-matrix-grilling.md) — 12 项全部裁定（详见票 Answer）：采 a7-5-1 现行口径为主（默认项禁停/键值始终可改/弹窗可改状态/未被引用可换组）；零改动维持仓库既定（组内唯一/权限点/keyword 单参/parentId 二级模型/软删/POST /page）；两项扩围（**ref_count 全量接线**三业务模块；商机相关字典页=同存储前端过滤视图）；唯一实质偏离=字典编码保留自动生成兵底
|
||
|
|
- [04 — crm-dict 管理端规则改造](issues/04-implement-changes.md) — 6 项全部落地：新错误码 63013 默认项禁停（/status+saveOrUpdate 双路拦截）、删 US-25 值只读、换组放开（双重唯一重校验+计数行随迁）、分组编辑解锁 status、字典键值必填、GET /item/tree 端点；crm-dict 53/53 测试全绿
|
||
|
|
- [07 — ref_count 引用计数全量接线](issues/07-refcount-wiring.md) — `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 补记](issues/06-context-adr-update.md) — CONTEXT.md 7 处词条修订（新增「二级字典项」、被引用=锁删除+换组/键值可改、默认项禁停、字典值必填、组内唯一、编码自动生成兵底）；ADR-0015 文末追加 2026-09-07 修订节 8 条（append-only，历史未重写，含票 09 对「锁定两级平铺」的追记）
|
||
|
|
- [05 — 接口文档同步](issues/05-api-docs-sync.md) — 文档仓实为 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 既有语义
|