4.5 KiB
数据字典（crm-dict）
平台级的键值字典管理，两级平铺结构（分组 → 字典项），供业务模块通过稳定编码取值。访问控制走权限点（dict:*），不依赖“超级管理员”类角色标记。
Language
字典分组: 一组同类字典项的容器，是字典的第一级。有全局唯一、创建后不可改的分组编码。停用后其字典项不再进入业务选择器，但不影响历史数据回显。 Avoid: 字典类型、字典分类、category
字典项: 分组下的一条键值条目，是字典的第二级。有全局唯一、创建后不可改的字典编码，作为业务数据保存的稳定标识。 Avoid: 字典值、字典条目、dict entry
内置字典:
builtin=true 的分组或字典项，由产品以 Excel 随版本发布、初始化脚本幂等导入，业务代码可硬依赖。管理员可改名、改描述、调排序、启停用，不可删除。
Avoid: 系统字典、固定字典
用户字典:
builtin=false 的分组或字典项，管理员在界面上自由新建、修改、删除。初始化脚本绝不触碰用户字典。
Avoid: 自定义字典、临时字典
字典编码:
字典项在其所属分组内的稳定标识（未填时按 dict_ + 32 位小写十六进制 UUID 自动生成），同分组内唯一。业务数据与系统配置只保存字典编码，从不保存字典名称。
Avoid: 字典 key、code、字典 ID
字段-分组绑定:
每个业务字段在设计期固定绑定唯一一个字典分组的约定。业务数据只存字典编码；分组由字段的绑定隐式提供，二者合成 (分组编码, 字典编码) 坐标反查唯一字典项。禁止一个字段跨多个分组取值——需合并选项时另建合并分组。
Avoid: 跨分组下拉、多分组并集字段
字典名称: 字典项的展示文案。被引用后仍可修改；改后所有历史数据统一展示最新名称。它是"展示层"，与作为"标识层"的字典编码严格分离。 Avoid: 字典标签、显示名
字典值: 字典项承载的取值，供业务规则或外部接口消费，在同一分组内唯一（空值不参与唯一校验）。与"字典编码"不同：编码是内部标识，字典值是对外取值。 Avoid: value（与"字典项"口语混用）
默认项:
分组当前选定的字典项，仅用于新建业务数据时的初始选择，从不修改已有业务数据。默认关系存于独立表 dict_group_default(group_id PK, item_id)，以主键约束保证每组最多一个；字典项自身不携带 is_default 字段。
Avoid: 默认值、缺省项、is_default 字段
被引用:
字典项已被业务数据或系统配置以其字典编码保存的状态。宏观上由 dict_ref_count 计数反映。被引用的字典项不可删除（除非管理员强制删除）、其分组与字典值不可修改，但字典名称仍可改。
Avoid: 被使用、有关联
引用计数:
(分组编码, 字典编码) 当前被业务数据引用的总次数。业务侧写入/清除字典编码与计数增减在同一个事务内完成，不走异步。计数只回答"有没有"，不回答"被谁"。
Avoid: 引用登记、引用记录
强制删除: 引用计数因业务代码漏写递减而飘高、导致实际无引用的字典项无法删除时，管理员可人工判定后绕过 ref_count 校验直接删除的兵底入口。不是常规删除路径。 Avoid: 硬删、管理员删除
业务选择器: 业务页面用于挑选字典项的下拉/选择控件。只有所属分组与字典项自身均为启用状态时，字典项才作为新可选项进入业务选择器；停用只影响新选择，不影响历史回显。 Avoid: 下拉框、选项列表
名称回显:
把已保存的字典编码换成中文字典名称在展示层显示。批量入口是读路径服务的 getNames(分组编码, 一批字典编码) → 编码 → 名称 映射，语义等同逐条 getItem（含停用项、走 Caffeine 缓存），供 crm-lead / crm-opportunity 等调用方回填 DTO；「填哪些字段」留在各调用方，字典侧只负责「编码 → 名称」这一段。
Avoid: 名称翻译、label 回填
排序号:
字典分组与字典项均可选填的非负整数，人工填写（不提供拖拽自动重排）。DB 存 NULL、不存“大数占位”；查询排序用 ORDER BY sort_no IS NULL, sort_no ASC, create_time ASC 实现 “有值升序 → 无值靠后 → 同值或都无值按创建时间升序”。
Avoid: 拖拽重排、大数占位