# 5.11 数据字典

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

上级文档：[基础平台产品设计](../基础平台产品设计.md)

## 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 功能入口与访问权限

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

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