字典管理

概述

字典管理用于维护系统中通用的「键值映射」数据，例如性别、状态、渠道等枚举选项。它将原本硬编码在代码里的常量集中到后台配置，使前端下拉框、单选、标签等组件能够统一、动态地读取，无需发版即可调整文案与取值。

模块对应后端 backend/app/api/v1/module_system/dict，前端页面位于 apps/web-ele/src/views/system/dict。

整体设计

字典分为两层：字典类型（分组）与字典数据（具体键值项）。一个类型下可挂载多条数据。

典型关系示意：

后端实现

后端接口

接口分为两组路由：/system/dict-type（字典类型）与 /system/dict-data（字典数据）。常见操作如下：

能力	字典类型	字典数据
分页查询	GET /dict-type/page	GET /dict-data/page
详情	GET /dict-type/get	GET /dict-data/get
精简全量列表	GET /dict-type/list-all-simple	GET /dict-data/simple-list
新增	POST /dict-type/create	POST /dict-data/create
修改	PUT /dict-type/update	PUT /dict-data/update
删除	DELETE /dict-type/delete	DELETE /dict-data/delete
批量删除	DELETE /dict-type/delete-list	DELETE /dict-data/delete-list
导出 Excel	GET /dict-type/export-excel	GET /dict-data/export-excel

权限标识统一为 system:dict:query / create / update / delete / export，写操作（增删改、导出）会同时清除或刷新对应 Redis 缓存命名空间，保证缓存与数据库一致。

关键业务约束

• 类型唯一性：name、type 均不可重复；新增/修改时后端会做排他校验。
• 类型联动：修改字典类型编码或状态时，其下所有字典数据的 dict_type 与 status 会同步更新。
• 删除保护：字典类型下存在字典数据时不可删除；内置（备注「系统默认」）字典数据不可删除。
• 缓存键：以 system:dict:{tenant_id}:{dict_type} 存储该类型下的全部数据（租户 ID 默认 1），用于前端与运行时快速读取。

缓存与性能

字典数据读取频率高、变更频率低，因此采用「数据库为源 + Redis 缓存」模式：

• 精简列表接口（list-all-simple、simple-list）带 300 秒本地级缓存装饰，适合菜单、下拉等基础枚举初始化。
• 单类型数据缓存在类型/数据变更时实时刷新，保证展示与配置一致。

前端使用

页面布局

字典管理页采用左右分栏：左侧为字典类型列表（TypeGrid），右侧为选中类型下的字典数据列表（DataGrid）。点击左侧任意类型，右侧自动按 dictType 过滤展示对应键值项。

字典 Store 与 Hook

全局字典通过 Pinia Store（@vben/stores 的 useDictStore）加载并持久化，packages/effects/hooks 提供了便捷读取方法：

• getDictOptions(dictType, valueType)：获取字典数组，直接用于 Select、RadioGroup、Checkbox 等组件的 options。valueType 支持 string / number / boolean。
• getDictLabel(dictType, value)：根据键值反查展示标签，常用于表格中把 0/1 渲染成「启用/停用」。
• getDictObj(dictType, value)：获取完整字典对象（含 colorType、cssClass）。

import { getDictOptions, getDictLabel } from '@vben/hooks';

// 下拉选项
const statusOptions = getDictOptions('sys_common_status', 'number');

// 表格中回显标签
const text = getDictLabel('sys_user_sex', row.sex);

在表单与表格中的集成

新增/编辑字典数据时，表单的「字典类型」字段通过 ApiSelect 拉取 getSimpleDictTypeList，自动回填空类型名称、值取类型编码，并锁定不可改。字典数据与类型列表均使用 CellDict 渲染状态列，借助 sys_common_status 字典自动呈现彩色标签。

// data.ts 中状态列示例
{
  field: 'status',
  title: '状态',
  cellRender: { name: 'CellDict', props: { type: DICT_TYPE.COMMON_STATUS } },
}

新增字典值时，colorType 与 cssClass 可选，用于在前端以不同颜色/样式展示标签（如 success、warning、error 或自定义十六进制颜色），增强可读性。

常见操作

• 新增一组枚举：先在字典类型新增（填写名称与类型编码），再在右侧为该类型逐条新增键值项。
• 前端复用：在任意业务表单/表格中调用 getDictOptions(type) 即可，无需重复维护选项。
• 批量维护：类型与数据列表均支持勾选后批量删除；数据列表支持按当前筛选条件导出 Excel。
• 注意事项：类型编码一旦创建不可修改（编辑时置灰）；删除类型前需先清空其下所有字典数据。