字典管理

字典管理负责维护系统中可枚举的业务选项，例如通用状态、用户性别、短信渠道、支付状态等。RuoYi Office 的管理端把字典拆成“字典类型”和“字典数据”两层：类型定义一组枚举的唯一编码，数据定义该编码下的标签、键值、排序、状态和展示样式。

本地实现位置

层	位置
PC 页面	ruoyi-office-vben/apps/web-antd/src/views/system/dict
PC API	src/api/system/dict/type、src/api/system/dict/data
后端 Controller	DictTypeController.java、DictDataController.java
前端使用	@vben/constants 的 DICT_TYPE、@vben/hooks 的 getDictOptions

页面结构

views/system/dict/index.vue 使用左右两栏：左侧维护字典类型，右侧显示选中类型下的字典数据。

字典类型

字典类型是业务枚举的命名空间。新增后，前端和后端通常通过 type 字段引用。

字段	说明
name	字典名称，面向管理员展示
type	字典类型编码，创建后前端禁用编辑，避免影响已有引用
status	启用/禁用
remark	备注说明

后端接口：

操作	接口	权限标识
创建类型	POST /system/dict-type/create	system:dict:create
修改类型	PUT /system/dict-type/update	system:dict:update
删除类型	DELETE /system/dict-type/delete	system:dict:delete
类型分页	GET /system/dict-type/page	页面查询使用
精简列表	GET /system/dict-type/list-all-simple、/simple-list	前端下拉使用
导出类型	GET /system/dict-type/export-excel	导出 字典类型.xls

字典数据

字典数据是某个字典类型下的具体选项。

字段	说明
dictType	归属字典类型
label	页面展示文案
value	业务存储键值，通常与后端枚举值对应
sort	展示排序
status	是否启用
colorType	Ant Design Vue 标签颜色类型
cssClass	自定义颜色或样式，例如 #108ee9

后端接口：

操作	接口	权限标识
新增数据	POST /system/dict-data/create	system:dict:create
修改数据	PUT /system/dict-data/update	system:dict:update
删除数据	DELETE /system/dict-data/delete	system:dict:delete
数据分页	GET /system/dict-data/page	页面查询使用
精简数据	GET /system/dict-data/list-all-simple、/simple-list	前端全局字典缓存使用
导出数据	GET /system/dict-data/export-excel	system:dict:export

使用建议

1. 字典类型编码要稳定：一旦被 DICT_TYPE、后端枚举或表字段引用，不建议直接修改。
2. 字典键值要和后端类型匹配：前端 getDictOptions(type, 'number') 会把值转为数字，后端字段为字符串时不要误用。
3. 禁用优先于删除：线上已有业务数据引用某个字典值时，建议禁用而不是删除。
4. 展示样式只影响前端：colorType 和 cssClass 用于标签渲染，不应承载业务含义。

排查清单

现象	排查方向
下拉没有选项	字典数据是否启用，前端 DICT_TYPE 是否与字典类型一致
标签显示原始值	字典值类型是否匹配，是否忘记加载字典缓存
修改类型后页面异常	检查前端常量和后端枚举是否仍引用旧 type
导出为空	检查筛选条件、权限和当前租户下是否有数据