更新功能

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

@@ -4,26 +4,369 @@
 
 上级文档：[基础平台产品设计](../基础平台产品设计.md)
 
-
 ## 5.11.1 功能说明
 
-数据字典用于维护基础枚举类数据，供各业务系统复用。
+数据字典用于维护基础平台和各业务应用可复用的枚举、状态值、颜色和展示顺序，为前端页面、后端接口、查询条件、状态标签和下拉选项提供统一值域来源。
+
+数据字典解决以下问题：
+
+- 统一维护字典编号和字典名称。
+- 统一维护字典值编码、名称、排序、颜色、状态和备注。
+- 支持按归属业务系统筛选字典。
+- 支持业务系统按字典编号查询字典值。
+- 支持停用字典或字典值后不影响历史数据展示。
+
+数据字典不负责：
+
+- 多语言文案维护。
+- 字典审批、发布和版本管理。
+- 字典值被业务引用后的统一反查。
+- 字典自动同步到其他系统。
+- 复杂业务规则配置。
 
 ## 5.11.2 功能范围
 
-- 字典分类
-- 字典项
-- 启用 / 停用字典项
-- 字典项排序
+- 字典列表查询
+- 字典详情查询
+- 新增字典
+- 编辑字典
+- 删除字典
+- 字典值维护
+- 字典值新增
+- 字典值删除
+- 字典值启用 / 停用
+- 字典值排序
+- 字典值颜色维护
+- 按归属业务系统筛选
+- 按字典编号查询字典值
 
-## 5.11.3 业务规则
+## 5.11.3 管理对象
 
-- 字典编码唯一。
-- 停用字典项后，不影响历史数据展示。
-- 字典变更需记录日志。
+数据字典首版只维护一个管理对象：字典。
 
-## 5.11.4 验收标准
+每条字典记录归属于一个业务系统，并包含一组字典值。字典值不单独作为顶层管理对象，在字典新增 / 编辑抽屉内维护。
 
-- 可维护字典分类和字典项。
-- 业务系统可使用启用状态的字典项。
-- 停用字典项不影响历史数据。
+对象关系：
+
+- 一个业务系统可拥有多个字典。
+- 一个字典拥有多个字典值。
+- 字典编号在未删除数据内唯一。
+- 字典值编码在同一字典内唯一。
+
+## 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 功能入口与访问权限
+
+数据字典作为基础平台基础资料管理功能，建议放置在基础平台左侧菜单：
+
+```text
+基础平台
+└── 数据字典
+```
+
+页面访问规则：
+
+- 平台超级管理员可维护全部字典。
+- 产品管理员可维护其负责业务系统的字典。
+- 实施人员可按授权范围查看或维护字典。
+- 客户管理员默认不可维护系统级数据字典。
+- 普通业务用户不可访问数据字典页面。
+- 无数据字典权限的用户不展示数据字典菜单。
+
+### 5.11.7.2 数据字典列表页
+
+数据字典列表页用于查询和维护字典。
+
+展示方式：
+
+- 查询区域 + 数据表格 + 分页。
+- 新增 / 编辑采用右侧抽屉。
+- 查询条件较多时支持展开 / 收起。
+- 查询按钮作为查询区域最后一个表单元素。
+
+查询条件：
+
+| 查询项 | 控件类型 | 值来源 / 录入方式 | 说明 |
+| --- | --- | --- | --- |
+| 关键字 | 文本输入框 | 人工录入 | 匹配字典编号、字典名称、备注、字典值 |
+| 启用状态 | 下拉框 | 全部、启用、停用 | 默认全部 |
+| 归属业务系统 | 下拉框 / 应用选择器 | 应用管理中已启用业务系统 | 可为空 |
+| 查询 | 按钮 | 用户点击 | 作为查询区域最后一个表单元素 |
+| 重置 | 按钮 | 用户点击 | 清空查询条件 |
+
+列表字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| 字典编号 | 字典唯一编号 |
+| 字典名称 | 字典展示名称 |
+| 归属业务系统 | 字典归属系统 |
+| 启用状态 | 启用、停用 |
+| 字典值预览 | 最多展示前三个字典值，超出部分显示数量提示 |
+| 备注 | 字典说明 |
+| 更新时间 | 最近更新时间 |
+| 操作 | 编辑、删除 |
+
+页面规则：
+
+- 默认分页大小为 20。
+- 字典值预览最多展示前三个值。
+- 删除必须二次确认。
+- 删除成功后刷新列表并失效对应缓存。
+
+### 5.11.7.3 字典新增 / 编辑抽屉
+
+字典新增 / 编辑抽屉用于维护字典基础信息和字典值列表。
+
+展示方式：
+
+- 右侧抽屉。
+- 上方为基础信息表单。
+- 下方为字典值列表。
+- 底部固定操作按钮：取消、保存。
+
+基础信息字段：
+
+| 字段 | 控件类型 | 值来源 / 录入方式 | 说明 |
+| --- | --- | --- | --- |
+| 字典编号 | 文本输入框 | 人工录入 | 必填，编辑时只读 |
+| 字典名称 | 文本输入框 | 人工录入 | 必填 |
+| 归属业务系统 | 下拉框 / 应用选择器 | 应用管理中已启用业务系统 | 必填 |
+| 启用状态 | Switch | 人工选择 | 默认启用 |
+| 备注 | 多行文本框 | 人工录入 | 选填 |
+
+字典值列表字段：
+
+| 字段 | 控件类型 | 值来源 / 录入方式 | 说明 |
+| --- | --- | --- | --- |
+| 字典值编码 | 文本输入框 | 人工录入 | 必填，同一字典内唯一 |
+| 字典值名称 | 文本输入框 | 人工录入 | 必填 |
+| 排序 | 数字输入框 / 拖拽排序 | 人工录入或拖拽生成 | 必填 |
+| 展示颜色 | 颜色选择器 / 文本输入框 | 人工选择或录入 | 选填 |
+| 启用状态 | Switch | 人工选择 | 默认启用 |
+| 备注 | 文本输入框 | 人工录入 | 选填 |
+| 操作 | 按钮 | 用户点击 | 新增、删除、上移、下移 |
+
+页面规则：
+
+- 字典值列表不能为空。
+- 支持新增字典值。
+- 支持删除字典值。
+- 支持拖拽排序或上移、下移。
+- 支持启用、停用单个字典值。
+- 保存前前端先做基础校验，后端再次执行同等或更严格校验。
+- 保存失败时保留表单输入并展示中文错误信息。
+
+### 5.11.7.4 字典详情页 / 弹窗
+
+字典详情用于查看字典基础信息和字典值列表。
+
+展示方式：
+
+- 采用详情弹窗或右侧抽屉展示。
+
+详情内容：
+
+| 区域 | 展示内容 |
+| --- | --- |
+| 基础信息 | 字典编号、字典名称、归属业务系统、启用状态、备注 |
+| 字典值列表 | 字典值编码、字典值名称、排序、颜色、启用状态、备注 |
+| 审计信息 | 创建时间、更新时间、创建人、更新人 |
+
+## 5.11.8 使用导航
+
+### 5.11.8.1 查询数据字典
+
+操作路径：
+
+```text
+基础平台 > 数据字典
+```
+
+操作步骤：
+
+1. 进入数据字典列表页。
+2. 按关键字、启用状态、归属业务系统查询。
+3. 查看字典列表和字典值预览。
+
+### 5.11.8.2 新增数据字典
+
+操作路径：
+
+```text
+基础平台 > 数据字典 > 新增
+```
+
+操作步骤：
+
+1. 进入数据字典列表页。
+2. 点击新增。
+3. 系统打开字典新增 / 编辑抽屉。
+4. 填写字典编号、字典名称、归属业务系统、启用状态和备注。
+5. 新增至少一个字典值。
+6. 填写字典值编码、字典值名称、排序、颜色、状态和备注。
+7. 保存字典。
+8. 系统校验字典编号唯一性、字典值唯一性和颜色格式。
+9. 保存成功后刷新列表并记录操作日志。
+
+### 5.11.8.3 编辑数据字典
+
+操作路径：
+
+```text
+基础平台 > 数据字典 > 编辑
+```
+
+操作步骤：
+
+1. 查询目标字典。
+2. 点击编辑。
+3. 系统打开字典新增 / 编辑抽屉。
+4. 修改字典名称、归属业务系统、启用状态、备注或字典值列表。
+5. 保存字典。
+6. 系统校验字典值唯一性和颜色格式。
+7. 保存成功后刷新列表、失效按编号查询缓存，并记录操作日志。
+
+### 5.11.8.4 删除数据字典
+
+操作路径：
+
+```text
+基础平台 > 数据字典 > 删除
+```
+
+操作步骤：
+
+1. 查询目标字典。
+2. 点击删除。
+3. 系统二次确认删除操作。
+4. 删除成功后刷新列表、失效对应缓存，并记录操作日志。
+
+### 5.11.8.5 按编号使用数据字典
+
+使用场景：
+
+```text
+业务系统页面 / 接口 > 按字典编号查询字典值
+```
+
+业务步骤：
+
+1. 业务系统按字典编号请求字典详情。
+2. 基础平台返回字典基础信息和字典值列表。
+3. 业务系统可按需要只使用启用状态字典值。
+4. 字典被编辑或删除后，对应编号缓存失效。
+
+## 5.11.9 权限资源
+
+数据字典建议纳入应用菜单与按钮资源治理。
+
+资源编码建议：
+
+| 操作 | 权限资源 |
+| --- | --- |
+| 查看列表 | system.dictionary.view |
+| 新增字典 | system.dictionary.create |
+| 编辑字典 | system.dictionary.update |
+| 删除字典 | system.dictionary.delete |
+
+前端按钮显隐只消费后端授权结果；后端接口仍必须做真实权限校验，不能只依赖前端隐藏按钮。
+
+## 5.11.10 验收标准
+
+- 数据字典列表默认分页大小为 20。
+- 可按关键字、启用状态、归属业务系统查询数据字典。
+- 新增字典时，非法编号、空名称、空归属业务系统、空字典值必须被阻断。
+- 字典编号重复时，后端必须阻断保存。
+- 同一字典内重复字典值编码时，前端和后端均需阻断保存。
+- 非法颜色格式必须被前端和后端阻断。
+- 字典值支持新增、删除、启用、停用、排序、颜色和备注维护。
+- 字典值预览最多展示前三个值，超出部分以数量提示。
+- 编辑后按编号查询缓存必须失效，重新查询应返回最新字典值。
+- 删除字典必须二次确认。
+- 删除成功后列表刷新；删除不存在的字典应提示字典不存在。
+- 停用字典值不影响历史数据展示。
+- 数据字典新增、编辑、删除、字典值变更均生成操作日志。