字典管理

字典管理提供树形字典的完整 CRUD 操作，支持父子层级结构和分类管理。字典用于管理系统中的枚举数据（如性别、状态、分类等），提供统一的字典值-标签翻译能力。

功能说明

• 字典分页查询（支持父级筛选、分类筛选、关键词搜索）
• 字典列表查询（不分页，支持父级和分类筛选）
• 字典树查询（返回树形结构）
• 字典新增 / 修改 / 删除（带子节点保护）
• 字典详情查看
• 字典标签翻译（根据编码+值获取标签）
• 字典子节点查询（根据编码获取子列表）
• Redis 缓存同步（每次修改后自动更新缓存）
• 数据导出（Excel）
• 导入模板下载
• 数据导入（Excel）

API 接口

所有接口均需要 sys:dict:* 权限。

方法	路径	权限标识	说明
GET	/api/v1/sys/dict/page	sys:dict:page	获取字典分页
GET	/api/v1/sys/dict/list	sys:dict:list	获取字典列表（不分页）
GET	/api/v1/sys/dict/tree	sys:dict:tree	获取字典树
POST	/api/v1/sys/dict/create	sys:dict:create	添加字典
POST	/api/v1/sys/dict/modify	sys:dict:modify	编辑字典
POST	/api/v1/sys/dict/remove	sys:dict:remove	删除字典（有子节点则禁止删除）
GET	/api/v1/sys/dict/detail	sys:dict:detail	获取字典详情
GET	/api/v1/sys/dict/get-label	sys:dict:get-label	根据编码和值获取标签
GET	/api/v1/sys/dict/get-children	sys:dict:get-children	根据编码获取子字典列表
GET	/api/v1/sys/dict/export	sys:dict:export	导出字典数据
GET	/api/v1/sys/dict/template	sys:dict:template	下载导入模板
POST	/api/v1/sys/dict/import	sys:dict:import	导入字典数据

数据模型

sys_dict 表主要字段：

字段	类型	说明
id	VARCHAR(32)	主键（雪花ID）
code	VARCHAR(32)	字典编码（唯一索引）
label	VARCHAR(255)	字典标签（显示名，如"男"）
value	VARCHAR(255)	字典值（如"M"）
color	VARCHAR(32)	颜色（前端展示用）
category	VARCHAR(64)	字典分类（如 BIZ、SYS）
parent_id	VARCHAR(32)	父字典 ID（根节点为 "0" 或 NULL）
status	VARCHAR(16)	状态
sort_code	INT	排序

字典结构

字典采用父子层级结构：

根字典 (parent_id = "0" 或 NULL)
├── code = "gender", label = "性别", value = "gender"
│   ├── 子字典: label = "男", value = "M", sort_code = 1
│   └── 子字典: label = "女", value = "F", sort_code = 2
├── code = "status", label = "状态", value = "status"
│   ├── 子字典: label = "启用", value = "ACTIVE"
│   └── 子字典: label = "禁用", value = "DISABLED"

字典翻译

通过 get-label 接口，将字典值翻译为可读标签：

GET /api/v1/sys/dict/get-label?type_code=gender&value=M
→ {"type_code": "gender", "value": "M", "label": "男"}

常用于表格列中显示人类可读的文本。

Redis 缓存

每次字典数据变更（create/modify/remove/import）后，自动将完整字典树同步到 Redis：

• 缓存 Key: hei:dict:tree
• 缓存格式: { "gender": [{ "label": "男", "value": "M", "color": null }, ...], ... }
• 读取方式: DictService.get_cached_dicts() 静态方法

新增/编辑校验

• 同一父字典下，label 和 value 不能重复
• 删除时检查是否有子节点，有子节点则拒绝删除