数据字典（Data Dictionary）使用手册

一、概述

数据字典是系统的基础数据管理模块，采用三层结构：分类 → 字典 → 字典项。它用于统一管理系统中的枚举值、下拉选项、状态码等结构化常量数据，方便其他业务模块通过统一的 API 获取选项列表。

二、三层数据模型

分类 (Category) ──1:N──> 字典 (Dictionary) ──1:N──> 字典项 (Item)

数据库表结构

实体关系

SysDataDicCategory (1) ──< (N) SysDataDic
    - 删除分类时，如果其下存在字典，则不允许删除

SysDataDic (1) ──< (N) SysDataDicItem
    - 删除字典时，会级联删除其下所有字典项
    - 字典项必须属于一个字典（dicId 必填）
    - 字典项按 orderNo 升序排列

三、功能页面

系统提供三个管理页面，路径均为 /:lang/dashboard/sys/ 下：

3.1 数据字典主页面 (/sys/data-dic)

布局：左侧分类树 + 右侧字典表格的分栏设计。

字典编号规则：只能包含大写字母、小写字母、数字或 ._-（正则：/^[A-Za-z0-9.\-_]+$/）。

3.2 字典项管理（在字典管理弹窗中操作）

从数据字典表格中点击某行的"字典管理"按钮打开：

3.3 字典分类页面 (/sys/data-dic-category)

独立管理字典分类的页面，以全表格形式展示。支持新增、编辑、删除分类。

3.4 字典项页面 (/sys/data-dic-item)

独立的字典项列表页面，需要指定 dicId 参数来筛选某个字典下的所有项。

四、如何在其他模块中使用数据字典

4.1 API 接口

前端通过 getSysDataDicItemByCodeApi 获取字典项列表：

import { getSysDataDicItemByCodeApi } from '~/api/sys/sysDataDicItem';

// 根据字典编号获取所有字典项
const items = await getSysDataDicItemByCodeApi('ORDER_STATUS');
// 返回: [{ id: 'ORDER_STATUS@PENDING', code: 'PENDING', name: '待处理' }, ...]

对应的后端接口：GET /system/dic/item/bydic?code={字典编号}

• 无需权限，所有模块可直接调用
• 返回的 id 是组合键格式：字典编号@字典项编号（用 @ 分隔）
• 结果按 orderNo 升序排列
• 带缓存（基于租户 ID + 字典编号）

4.2 典型使用场景

// 在表单中渲染下拉选项
<Select>
  {(items || []).map(item => (
    <Select.Option key={item.code} value={item.code}>{item.name}</Select.Option>
  ))}
</Select>

4.3 选择器接口

系统还提供了通用的选择器接口供下拉框组件使用：

五、重要规则与约束

六、权限控制

七、常见操作流程示例

场景：需要新建一个"发票类型"下拉选项供销售模块使用

1. 进入 数据字典分类 页面，新建分类（如："财务"）
2. 进入 数据字典 主页面，点击"新增"，编号填 INVOICE_TYPE，名称填"发票类型"，分类选"财务"
3. 点击该字典行的"字典管理"按钮，依次新增字典项：
   • 编号 VAT_SPECIAL，名称"增值税专用发票"，排序 1
   • 编号 VAT_NORMAL，名称"增值税普通发票"，排序 2
   • 编号 ELECTRONIC，名称"电子发票"，排序 3
4. 在销售模块中调用 getSysDataDicItemByCodeApi('INVOICE_TYPE') 即可获取全部选项

八、前端文件清单

九、后端文件清单