字典管理 ★
一句话：字典 = 下拉框里那些选项的源头（性别、状态、类型…）。本页是「左树右表」结构：左边维护字典分类（分组与字典两级概念），右边维护选中字典的字典数据（选项值）。本项目对上游做了整体重做，故标 ★。
两个层级，别混
- 分组：只用于归拢字典（如「系统管理」「基础设施」），本身不能挂字典数据；
- 字典：真正承载选项值的节点（如
system_user_sex），全站下拉框按编码取它。
左树里文件夹图标 = 分组，文档图标 = 字典，带分叉的图标 = 树形字典（选项值自身还有层级）。
功能在哪
- 菜单路径：系统管理 → 字典管理
- 地址栏路由：
/system/dict（旧地址/system/dict/type/data/:dictType会自动重定向到/system/dict?dictType=…并定位到对应字典） - 主要权限：
system:dict:query/create/update/delete/import/export
界面认识
左：分类树（约 280px 宽）
| 部件 | 作用 |
|---|---|
| 搜索框「搜索分类名称/编码」 | 回车或点清除触发过滤；搜索时整棵树自动全展开，否则命中项藏在折叠分组里看不见 |
| 「新增」下拉 | 新增分组 / 新增字典（需要 system:dict:create）；当前选中的是分组时，新节点挂在它下面 |
| 四个图标按钮 | 刷新数据（提示「已刷新」）/ 展开全部 / 折叠全部 / 分类管理（打开抽屉，见下） |
| 树本体 | 点节点 = 选中它并在右侧显示数据；支持拖拽调整归属与顺序（需要 system:dict:update，成功提示「移动成功」） |
默认只展开「当前选中项所在的那一条分支」
分类有 270+ 个，全展开等于没分组。想看全貌用「展开全部」，想定位用搜索框。
右：字典数据区（两张卡片）
| 部件 | 作用 |
|---|---|
| 标题行 | 字典名称 + 编码标签；树形标签 = 选项值有层级；懒加载标签 = 缓存模式为按需加载 |
| 查询区 | 「关键字」搜标签/键值；「状态」仅在平铺字典下出现 |
| 工具条 | 新增 / 导入（Excel）/ 导出（Excel，导的是整份字典而非筛选结果）/ 批量删除 |
| 列表 | 平铺字典：多选 / 序号 / 字典标签 / 字典键值 / 字典排序 / 状态 / 颜色类型 / 备注 / 创建时间 / 操作，带分页；树形字典：无序号无分页，默认全展开，行内多一个「新增下级」 |
| 状态列 | 开关即时启停该选项（提示「已开启 / 已关闭」），走与编辑表单相同的保存接口 |
改完字典，全站下拉框什么时候生效
保存后本页会主动刷新前端字典缓存，当前浏览器立刻生效；其他已登录用户要等字典版本号变化后下次取数才更新。若发现别的页面还是旧选项，整页刷新一次即可。
常用操作
新建一个字典
- 左树「新增」→「新增字典」（或先选中某个分组再新增，自动挂在它下面）；
- 填「字典名称」与「字典类型」（编码，如
demo_order_source）——保存后不可修改，因为全站下拉框按它取数； - 需要层级就打开「树形字典」开关：创建后不可切换（改成平铺会让已有子节点变成孤儿，确需调整请导出后重建）；
- 「缓存模式」：选项少选「全量下发」；节点极多（如行政区划）选「按需懒加载」，该字典不进前端全量缓存、展开时才取子级；
- 填排序、状态、备注，点「确定」；
- 回到左树选中新字典，在右侧用「新增」逐条加选项值。
新增 / 修改字典数据
点右侧「新增」（树形字典还可在行内点「新增下级」指定父节点）：
| 字段 | 说明 |
|---|---|
| 字典类型 | 只读，就是当前选中的字典 |
| 上级节点 | 仅树形字典出现；不选 = 顶层节点 |
| 数据标签 | 界面上显示的文字（如「男」） |
| 数据键值 | 存进业务表的值（如 1），同一字典内不可重复 |
| 显示排序 / 状态 | 排序决定下拉框先后；状态关闭后该选项不再出现在下拉框 |
| 颜色类型 | 决定 字典标签 的颜色（默认 / 主要 / 成功 / 警告 / 危险…） |
| CSS Class / 备注 | 附加样式与说明 |
删除字典数据
- 行内「删除」：有子节点时确认框会明说「「X」下还有子节点，删除会连同整棵子树一起删除，是否继续？」；
- 勾选后「批量删除」：确认框为通用的「是否删除所选中数据？」。
分类管理抽屉：集中增删改与迁移包
左树第四个图标按钮打开「字典分类管理」抽屉（900px 宽）：把整棵分类树摊成一张表，一行一个分组/字典，行内「新增下级（仅分组）/ 修改 / 导出 / 删除」，适合批量整理——左树只有 280px，摆不下这些按钮。
行内「导出」导的是 JSON 迁移包，不是 Excel
点某行「导出」会下载 分类名.json：该分类及其全部子分类、连同这些字典下的所有数据打成一个包（抽屉底部有原话说明）。用途是环境间搬运与备份，配合下面的「导入分类」使用。
导入迁移包（JSON）
抽屉里点「导入分类」：
| 字段 | 说明 |
|---|---|
| 导入到 | 不选 = 挂到分类树根节点；只影响包里的顶层分类，包内部层级原样保留 |
| 冲突处理 | 跳过（默认）：已存在的分类和字典值一律保持原样，只补上缺的，三种里唯一不会改动现有数据的选项；覆盖：按包里的内容更新已存在项，节点类型/树形开关不会被改动，不一致会直接报错；建副本：整棵子树新建一份，编码和名称自动加后缀，适合拿现有字典改造出一套新的 |
| 迁移包 | 仅接受本系统「导出分类」产出的 .json；批量改选项值请走字典数据的 Excel 导入，两条通道各管一件事 |
导入完成后按分类逐行给出结果：新增 / 更新 / 已存在 / 副本 / 失败，并列出每个分类「新增 N / 更新 N / 跳过 N / 失败 N」与失败原因——只报总数的话，你知道有东西没进去，却不知道是哪一个。
导入 / 导出字典数据（Excel）
- 右侧「导出」：确认「是否确认导出数据项？」后下载
字典数据.xls，内容是整份字典（不是当前筛选结果）——导出的文件要能改完直接导回来； - 右侧「导入」：上传
.xls/.xlsx，可勾选「是否更新已经存在的字典数据（“字典键值”重复）」；树形字典的层级用「上级键值」列表达，留空表示顶层，父行排在子行后面也没关系；可先「下载模板」拿字典数据导入模板.xls； - 导入结果给出「新增 N / 更新 N / 失败 N」三个标签，失败明细按行列出键值与原因。
字段说明（分类表单）
| 字段 | 必填 | 取值 / 校验 | 说明 |
|---|---|---|---|
| 上级分组 | 否 | 分组节点 | 不选 = 根节点下；字典不能挂字典下面 |
| 节点类型 | 是 | 分组 / 字典 | 编辑时禁用 |
| 分组名称 / 字典名称 | 是 | 「名称不能为空」 | 显示名 |
| 分组编码 / 字典类型 | 是 | 「编码不能为空」；编辑时禁用 | 全站按编码取字典 |
| 树形字典 | — | 开关 | 仅字典；创建后不可切换 |
| 缓存模式 | — | 全量下发 / 按需懒加载 | 仅字典 |
| 排序 / 状态 / 备注 | 状态必填 | 「状态不能为空」 | — |
拖拽移动时后端会校验：字典只能拖进分组内部或作为兄弟节点（字典下面挂的是数据，不能再挂分类）。
视角对照
| 视角 | 看到什么 |
|---|---|
超管 admin / 租户管理员 docadmin | 本租户全部分类与数据（含 270+ 存量字典） |
无 system:dict:create/update 的角色 | 树与列表照常看，但「新增」下拉、拖拽、状态开关、行内修改均不可用 |
进阶
- 通用操作约定 · 字典标签：颜色类型如何影响列表标签；
- 菜单管理：按钮级权限标识与本页权限的关系；
- 角色资源授权：把
system:dict:*授给角色。
常见问题
Q：左树搜不到某个字典？ A：搜索同时匹配名称与编码；确认没被停用隐藏（字典没有隐藏态，搜不到通常是编码记错了）。也可打开「分类管理」抽屉用它的搜索框，命中后整表展开。
Q：为什么我的字典右侧没有「状态」筛选和分页？ A：它是树形字典。树形字典一次取回整棵树，没有分页概念，关键字过滤也会连同祖先节点一起返回。
Q：「树形字典」开关是灰的点不动？ A：编辑已有字典时该开关禁用——创建后不可切换。确需把平铺改树形（或反之），请导出迁移包、重建后导入。
Q：导入迁移包后编码变了（多了后缀）？ A：你选了「建副本」策略：整棵子树新建一份并自动加后缀，原字典不受影响。想原地更新请选「覆盖」，只想补缺请选「跳过」。
Q：导出再导入，能当作「批量改选项值」用吗？ A：不推荐。迁移包面向分类子树搬运；批量改选项值请走字典数据的 Excel 导入（勾选「更新已存在」），一条通道一件事。
Q：删了字典，引用它的下拉框会怎样？ A：下拉框取不到选项、显示为空；已存进业务表的键值不受影响，但列表里的字典标签会失去文字。删除前请在「分类管理」里确认引用面。