zd_product_document/40-平台与架构/基础平台/功能模块/11-数据字典.md

5.11 数据字典

本文档从《基础平台产品设计》第 5 章拆分而来，用于独立描述基础平台功能模块的业务需求、规则和验收标准。

上级文档：基础平台产品设计

5.11.1 功能说明

数据字典用于维护基础平台和各业务应用可复用的枚举、状态值、颜色和展示顺序，为前端页面、后端接口、查询条件、状态标签和下拉选项提供统一值域来源。

数据字典解决以下问题：

• 统一维护字典编号和字典名称。
• 统一维护字典值编码、名称、排序、颜色、状态和备注。
• 支持按归属业务系统筛选字典。
• 支持业务系统按字典编号查询字典值。
• 支持停用字典或字典值后不影响历史数据展示。

数据字典不负责：

• 多语言文案维护。
• 字典审批、发布和版本管理。
• 字典值被业务引用后的统一反查。
• 字典自动同步到其他系统。
• 复杂业务规则配置。

5.11.2 功能范围

• 字典列表查询
• 字典详情查询
• 新增字典
• 编辑字典
• 删除字典
• 字典值维护
• 字典值新增
• 字典值删除
• 字典值启用 / 停用
• 字典值排序
• 字典值颜色维护
• 按归属业务系统筛选
• 按字典编号查询字典值

5.11.3 管理对象

数据字典首版只维护一个管理对象：字典。

每条字典记录归属于一个业务系统，并包含一组字典值。字典值不单独作为顶层管理对象，在字典新增 / 编辑抽屉内维护。

对象关系：

• 一个业务系统可拥有多个字典。
• 一个字典拥有多个字典值。
• 字典编号在未删除数据内唯一。
• 字典值编码在同一字典内唯一。

5.11.4 字段要求

5.11.4.1 字典字段

字典信息至少包括：

字段	说明	是否必填
字典编号	字典唯一编号	是
字典名称	字典展示名称	是
归属业务系统	字典归属系统	是
启用状态	启用、停用	是
备注	字典说明	否
字典值列表	当前字典包含的值列表	是
创建时间	字典创建时间	是
更新时间	字典最近更新时间	是

5.11.4.2 字典值字段

字典值信息至少包括：

字段	说明	是否必填
字典值编码	字典值唯一编码	是
字典值名称	字典值展示名称	是
排序	字典值展示顺序	是
展示颜色	字典值在标签、状态等场景中的展示颜色	否
启用状态	启用、停用	是
备注	字典值说明	否

5.11.5 编码与校验规则

5.11.5.1 字典编号规则

字典编号用于业务系统查询字典值，是前后端共同使用的稳定标识。

规则：

• 字典编号必填。
• 字典编号保存前统一去除首尾空格并转小写。
• 字典编号建议采用“表名_字段名”的蛇形命名方式。
• 示例：system_dictionary_status、system_user_status、system_app_type。
• 未删除数据内字典编号唯一。
• 字典编号创建后原则上不允许修改。

5.11.5.2 字典字段校验

字段	校验规则
字典编号	必填，符合蛇形命名规则，未删除数据内唯一
字典名称	必填，长度 2-32 个字符
归属业务系统	必填，必须选择已存在业务系统
启用状态	必填，只允许启用、停用
备注	可空，最长 256 个字符
字典值列表	必填，至少包含一个字典值

5.11.5.3 字典值校验

字段	校验规则
字典值编码	必填，同一字典内忽略大小写后不得重复
字典值名称	必填
排序	必填，必须大于 0
展示颜色	可空，非空时必须符合十六进制颜色格式
启用状态	必填，只允许启用、停用
备注	可空

5.11.6 业务规则

• 字典必须归属于一个业务系统。
• 字典编号未删除数据内唯一。
• 字典值列表不能为空。
• 同一字典内字典值编码不可重复。
• 新增字典默认启用。
• 新增字典值默认启用。
• 停用字典后，业务系统默认不应继续读取该字典作为可选值。
• 停用字典值后，不影响历史数据展示，但新增或编辑业务数据时不应再作为可选项。
• 删除字典采用软删除。
• 删除字典前，首版不做统一引用反查；后续接入业务引用关系后，应支持引用阻断删除。
• 字典值排序由用户维护，拖拽排序后按顺序重建排序号。
• 字典保存成功后，前端按编号查询的缓存应失效，重新查询应返回最新字典值。
• 数据字典变更需要记录操作日志。

5.11.7 界面设计

5.11.7.1 功能入口与访问权限

数据字典作为基础平台基础资料管理功能，建议放置在基础平台左侧菜单：

基础平台
└── 数据字典

页面访问规则：

• 平台超级管理员可维护全部字典。
• 产品管理员可维护其负责业务系统的字典。
• 实施人员可按授权范围查看或维护字典。
• 客户管理员默认不可维护系统级数据字典。
• 普通业务用户不可访问数据字典页面。
• 无数据字典权限的用户不展示数据字典菜单。

5.11.7.2 数据字典列表页

数据字典列表页用于查询和维护字典。

展示方式：

• 查询区域 + 数据表格 + 分页。
• 新增 / 编辑采用右侧抽屉。
• 查询条件较多时支持展开 / 收起。
• 查询按钮作为查询区域最后一个表单元素。

查询条件：

查询项	控件类型	值来源 / 录入方式	说明
关键字	文本输入框	人工录入	匹配字典编号、字典名称、备注、字典值
启用状态	下拉框	全部、启用、停用	默认全部
归属业务系统	下拉框 / 应用选择器	应用管理中已启用业务系统	可为空
查询	按钮	用户点击	作为查询区域最后一个表单元素
重置	按钮	用户点击	清空查询条件

列表字段：

字段	说明
字典编号	字典唯一编号
字典名称	字典展示名称
归属业务系统	字典归属系统
启用状态	启用、停用
字典值预览	最多展示前三个字典值，超出部分显示数量提示
备注	字典说明
更新时间	最近更新时间
操作	编辑、删除

页面规则：

• 默认分页大小为 20。
• 字典值预览最多展示前三个值。
• 删除必须二次确认。
• 删除成功后刷新列表并失效对应缓存。

5.11.7.3 字典新增 / 编辑抽屉

字典新增 / 编辑抽屉用于维护字典基础信息和字典值列表。

展示方式：

• 右侧抽屉。
• 上方为基础信息表单。
• 下方为字典值列表。
• 底部固定操作按钮：取消、保存。

基础信息字段：

字段	控件类型	值来源 / 录入方式	说明
字典编号	文本输入框	人工录入	必填，编辑时只读
字典名称	文本输入框	人工录入	必填
归属业务系统	下拉框 / 应用选择器	应用管理中已启用业务系统	必填
启用状态	Switch	人工选择	默认启用
备注	多行文本框	人工录入	选填

字典值列表字段：

字段	控件类型	值来源 / 录入方式	说明
字典值编码	文本输入框	人工录入	必填，同一字典内唯一
字典值名称	文本输入框	人工录入	必填
排序	数字输入框 / 拖拽排序	人工录入或拖拽生成	必填
展示颜色	颜色选择器 / 文本输入框	人工选择或录入	选填
启用状态	Switch	人工选择	默认启用
备注	文本输入框	人工录入	选填
操作	按钮	用户点击	新增、删除、上移、下移

页面规则：

• 字典值列表不能为空。
• 支持新增字典值。
• 支持删除字典值。
• 支持拖拽排序或上移、下移。
• 支持启用、停用单个字典值。
• 保存前前端先做基础校验，后端再次执行同等或更严格校验。
• 保存失败时保留表单输入并展示中文错误信息。

5.11.7.4 字典详情页 / 弹窗

字典详情用于查看字典基础信息和字典值列表。

展示方式：

• 采用详情弹窗或右侧抽屉展示。

详情内容：

区域	展示内容
基础信息	字典编号、字典名称、归属业务系统、启用状态、备注
字典值列表	字典值编码、字典值名称、排序、颜色、启用状态、备注
审计信息	创建时间、更新时间、创建人、更新人

5.11.8 使用导航

5.11.8.1 查询数据字典

操作路径：

基础平台 > 数据字典

操作步骤：

1. 进入数据字典列表页。
2. 按关键字、启用状态、归属业务系统查询。
3. 查看字典列表和字典值预览。

5.11.8.2 新增数据字典

操作路径：

基础平台 > 数据字典 > 新增

操作步骤：

1. 进入数据字典列表页。
2. 点击新增。
3. 系统打开字典新增 / 编辑抽屉。
4. 填写字典编号、字典名称、归属业务系统、启用状态和备注。
5. 新增至少一个字典值。
6. 填写字典值编码、字典值名称、排序、颜色、状态和备注。
7. 保存字典。
8. 系统校验字典编号唯一性、字典值唯一性和颜色格式。
9. 保存成功后刷新列表并记录操作日志。

5.11.8.3 编辑数据字典

操作路径：

基础平台 > 数据字典 > 编辑

操作步骤：

1. 查询目标字典。
2. 点击编辑。
3. 系统打开字典新增 / 编辑抽屉。
4. 修改字典名称、归属业务系统、启用状态、备注或字典值列表。
5. 保存字典。
6. 系统校验字典值唯一性和颜色格式。
7. 保存成功后刷新列表、失效按编号查询缓存，并记录操作日志。

5.11.8.4 删除数据字典

操作路径：

基础平台 > 数据字典 > 删除

操作步骤：

1. 查询目标字典。
2. 点击删除。
3. 系统二次确认删除操作。
4. 删除成功后刷新列表、失效对应缓存，并记录操作日志。

5.11.8.5 按编号使用数据字典

使用场景：

业务系统页面 / 接口 > 按字典编号查询字典值

业务步骤：

1. 业务系统按字典编号请求字典详情。
2. 基础平台返回字典基础信息和字典值列表。
3. 业务系统可按需要只使用启用状态字典值。
4. 字典被编辑或删除后，对应编号缓存失效。

5.11.9 权限资源

数据字典建议纳入应用菜单与按钮资源治理。

资源编码建议：

操作	权限资源
查看列表	system.dictionary.view
新增字典	system.dictionary.create
编辑字典	system.dictionary.update
删除字典	system.dictionary.delete

前端按钮显隐只消费后端授权结果；后端接口仍必须做真实权限校验，不能只依赖前端隐藏按钮。

5.11.10 验收标准

• 数据字典列表默认分页大小为 20。
• 可按关键字、启用状态、归属业务系统查询数据字典。
• 新增字典时，非法编号、空名称、空归属业务系统、空字典值必须被阻断。
• 字典编号重复时，后端必须阻断保存。
• 同一字典内重复字典值编码时，前端和后端均需阻断保存。
• 非法颜色格式必须被前端和后端阻断。
• 字典值支持新增、删除、启用、停用、排序、颜色和备注维护。
• 字典值预览最多展示前三个值，超出部分以数量提示。
• 编辑后按编号查询缓存必须失效，重新查询应返回最新字典值。
• 删除字典必须二次确认。
• 删除成功后列表刷新；删除不存在的字典应提示字典不存在。
• 停用字典值不影响历史数据展示。
• 数据字典新增、编辑、删除、字典值变更均生成操作日志。