数据字典管理 PRD

文档信息

项目	内容
产品名称	PMForge - 数据字典管理
文档版本	v2.0
创建日期	2026-09-14
最后更新	2026-09-24
文档状态	评审中
优先级	P0

一、功能概述

1.1 功能定位

数据字典是 PMForge 平台的"翻译词典"——它把系统里所有"只能选、不能填"的数据（比如下拉框里的选项、状态标签的颜色、单选框里的值）统一收拢到一个地方管理。

举个例子：用户性别这个字段，前端下拉框要展示"男""女"，数据库里存的是"1""2"——这层对应关系就写在数据字典里。如果将来要加一个"未知"选项，只需要在字典里加一条记录，不需要改代码、不需要重新发布。

数据字典采用两级管理结构：

第一级：字典类型 — 相当于"词典的目录"，比如"用户性别""订单状态""通知类型"
第二级：字典数据 — 相当于"词典的条目"，比如"用户性别"下面有"男""女"两个条目

1.2 目标用户

用户类型	核心诉求	典型操作
系统管理员	维护字典类型与字典数据的增删改查，保证数据准确性	新增"订单状态"字典类型，配置"待支付/已支付/已发货/已完成/已取消"5 个选项
前端开发者	快速拿到字典数据，渲染下拉框、标签、单选框	页面加载时一次性拉取全部字典数据缓存到本地，后续直接使用
后端开发者	通过接口或 Service 获取字典值，避免在代码里写死枚举	保存订单时调用字典校验接口，确认"订单状态"值合法
运营人员	查看与导出字典配置，进行数据核查	导出所有字典数据 Excel，线下审计配置是否正确

1.3 业务价值

价值点	说明	举例
消除硬编码	所有枚举值集中在字典里管理，代码里不再出现"魔法数字"	过去代码里写 `if (status == 1)`，现在改为 `if (status == dict("order_status", "已支付"))`
运行时可改	修改字典值不需要重启服务或重新部署	紧急停用某个选项，管理员在后台点一下"停用"即可生效
高性能读取	Redis 缓存保证字典数据毫秒级响应	前端加载字典数据 50ms 内返回，不影响页面渲染速度
标准化接口	为前端提供统一的字典数据获取方式	所有下拉框都走同一个接口获取数据，前端只需对接一次
可导出可审计	支持导出 Excel，满足合规审查需求	审计人员导出全部字典配置，逐项核查系统参数是否合规

1.4 功能范围

功能分类	优先级	说明
字典类型 CRUD	P0	字典类型的创建、查询、编辑、删除
字典数据 CRUD	P0	字典数据的创建、查询、编辑、删除
字典数据排序	P0	字典数据按 sort 字段升序展示，值越小排越前
字典状态管理	P0	字典类型和字典数据都支持启用/停用
字典缓存自动刷新	P0	数据变更后自动刷新 Redis 缓存，无需人工干预
字典精简列表	P0	前端一次性获取全部字典数据并本地缓存
字典数据导出	P1	导出字典类型与字典数据 Excel
字典批量删除	P1	批量删除字典类型与字典数据
前台字典查询	P0	App 端通过字典类型直接获取字典数据列表
字典数据校验	P0	业务模块保存数据时校验字典值是否合法

二、用户场景

2.1 用户角色

角色	描述	核心诉求
系统管理员小王	后台管理人员，负责字典配置维护	字典类型和数据的增删改查准确无误，缓存自动同步
前端开发小李	应用前端开发人员	接口简单好用，一次拿到全部字典数据，减少请求次数
后端开发小张	后端开发人员	通过 Service 获取字典数据，校验业务数据的字典值合法性
运营人员小陈	运营分析人员	导出字典数据 Excel，进行数据核查与审计

2.2 使用场景

场景1：管理员新增字典类型并配置数据项

用户：系统管理员小王
背景：产品经理说新增了一个"项目优先级"字段，需要在下拉框里让用户选择"紧急/高/中/低"四个等级
操作步骤：
1. 登录后台 → 进入"数据字典"页面
2. 点击"新增字典类型" → 填写字典名称"项目优先级"、字典类型编码"project_priority"、状态"正常"、备注"项目管理的优先级选项"
3. 保存后，在字典类型列表找到"项目优先级"，点击右侧"字典数据"进入数据管理
4. 依次新增 4 条字典数据：
  - 标签"紧急"、值"1"、排序 0、颜色 danger（红色）
  - 标签"高"、值"2"、排序 1、颜色 warning（橙色）
  - 标签"中"、值"3"、排序 2、颜色 primary（蓝色）
  - 标签"低"、值"4"、排序 3、颜色 info（灰色）
期望结果：字典类型创建成功，4 条数据按排序值展示，前端通过字典类型编码"project_priority"即可获取这 4 个选项
异常处理：如果字典类型编码已存在（如之前已创建过"project_priority"），系统提示"字典类型编码已存在，请修改"

场景2：前端开发者一次性缓存字典数据

用户：前端开发小李
背景：小李在开发项目管理页面，页面上有"优先级""状态""类型"等多个下拉框，都需要字典数据
操作步骤：
1. 页面加载时，调用"字典数据精简列表"接口（/admin-api/system/dict-data/simple-list），一次性拿到全部启用状态的字典数据
2. 前端按 dictType 字段分组，构建本地字典缓存 Map：{ "project_priority": [{label:"紧急", value:"1"}, ...], ... }
3. 渲染下拉框时，直接从本地 Map 中按字典类型取出选项列表，无需再发请求
期望结果：页面加载只发一次字典请求，后续所有下拉框渲染都走本地缓存，页面切换也不重新请求
为什么这样设计：字典数据总量通常不超过 1000 条，一次全量拉取的数据量很小（几十 KB），但能避免每个下拉框都发一次请求，大幅减少网络开销

场景3：管理员停用字典数据并自动刷新缓存

用户：系统管理员小王
背景：业务方说"已取消"这个订单状态暂时不用了，先在下拉框里隐藏掉
操作步骤：
1. 进入字典数据管理 → 筛选字典类型"order_status"
2. 找到"已取消"这一条 → 点击"编辑" → 状态改为"停用" → 保存
3. 系统自动清除"order_status"对应的 Redis 缓存
4. 下次前端刷新字典缓存时，拿到的"order_status"数据里不再包含"已取消"
期望结果：缓存自动刷新，前端重新请求后"已取消"不再出现在下拉框中
注意：已使用"已取消"值的存量订单数据不受影响，字典停用只影响前端下拉框的可选项

场景4：后端开发校验字典值合法性

用户：后端开发小张
背景：小张在写订单创建接口，需要校验前端传过来的"订单状态"值是否合法
操作步骤：
1. 在订单创建 Service 中调用 dictDataService.validateDictDataList("order_status", ["1", "2"])
2. 系统查询"order_status"下所有启用状态的字典数据
3. 校验传入的值是否全部存在于字典数据中
4. 如果存在非法值（如传了一个已停用的状态值），抛出异常："字典数据不存在或已停用"
期望结果：非法字典值被拦截，不会写入数据库

场景5：运营人员导出字典数据

用户：运营人员小陈
背景：年底审计，需要核查系统里所有字典配置是否合规
操作步骤：
1. 进入字典数据管理页面
2. 不设置筛选条件（即导出全部）或按字典类型筛选
3. 点击"导出"按钮 → 下载 Excel 文件
4. Excel 包含：字典编码、字典排序、字典标签、字典键值、字典类型、状态、创建时间
期望结果：导出的 Excel 包含筛选条件下所有字典数据，状态列显示"正常/停用"而非数字

场景6：管理员修改字典类型编码

用户：系统管理员小王
背景：发现字典类型编码命名不规范，"usersex"应该改为"system_user_sex"
操作步骤：
1. 编辑字典类型 → 将字典类型编码从"usersex"改为"system_user_sex" → 保存
2. 系统自动同步更新所有关联字典数据的 dict_type 字段
3. 系统自动清除全部字典缓存
期望结果：字典类型编码更新成功，所有关联的字典数据自动跟随更新，缓存自动刷新
风险提示：修改字典类型编码是一个影响面较大的操作，所有引用旧编码的业务代码和前端缓存都需要同步更新

场景7：App 端用户获取字典数据

用户：手机端用户
背景：用户在 App 里提交表单，需要加载"用户性别"下拉选项
操作步骤：
1. App 调用 /app-api/system/dict-data/type?type=system_user_sex
2. 系统优先从 Redis 缓存读取，命中则直接返回
3. 缓存未命中则查询数据库，写入缓存后返回
4. 返回结果按 sort 升序排列，只包含启用状态的数据
期望结果：App 端 50ms 内拿到字典数据，渲染下拉框

2.3 用户故事

编号	用户故事	优先级	验收标准
US-01	作为系统管理员，我希望能创建和管理字典类型，以便统一定义系统中的枚举数据	P0	① 创建字典类型后列表中立即可见 ② 字典类型编码全局唯一，重复时提示错误 ③ 创建成功后缓存自动刷新
US-02	作为系统管理员，我希望能管理字典类型下的字典数据项，以便配置具体的可选值	P0	① 同一字典类型下字典值不可重复 ② 字典数据必须关联已存在的字典类型 ③ 创建后缓存自动刷新
US-03	作为系统管理员，我希望能对字典数据进行排序，以便控制前端展示顺序	P0	① sort 值越小排越前 ② 默认按 sort 升序展示 ③ 前端精简列表也按 sort 排序
US-04	作为系统管理员，我希望能启用/停用字典类型与字典数据，以便灵活控制数据可见性	P0	① 停用的字典数据不出现在精简列表中 ② 停用字典类型后其下数据仅返回启用项 ③ 停用操作即时生效
US-05	作为前端开发者，我希望能通过接口一次性获取全部字典数据并缓存到本地	P0	① 精简列表接口返回全部启用状态的字典数据 ② 响应时间 < 50ms（命中缓存） ③ 无需权限校验
US-06	作为后端开发者，我希望能校验字典数据的合法性，防止业务端使用无效字典值	P0	① 校验不通过时抛出明确异常 ② 只校验启用状态的字典数据 ③ 支持批量校验
US-07	作为系统管理员，我希望能导出字典类型与字典数据，以便进行数据核查与审计	P1	① 导出当前筛选条件下的全部数据 ② 状态列显示中文而非数字 ③ 文件格式为 Excel
US-08	作为系统管理员，我希望能批量删除不需要的字典类型或字典数据	P1	① 勾选多条后可一键删除 ② 删除前有二次确认 ③ 字典类型下有数据时阻止删除该类型
US-09	作为系统，我需要在字典数据变更后自动刷新 Redis 缓存	P0	① 增删改操作完成后缓存同步刷新 ② 字典数据变更刷新对应 dictType 缓存 ③ 字典类型变更刷新全部缓存
US-10	作为 App 端用户，我希望能通过字典类型直接获取字典数据列表	P0	① 无需登录即可访问 ② 只返回启用状态数据 ③ 按 sort 升序排列

三、功能需求

3.1 后台管理端 - 字典类型管理

3.1.1 功能清单

功能	优先级	权限标识	说明
字典类型列表（分页）	P0	system:dict:query	分页展示字典类型，支持搜索筛选
字典类型详情	P0	system:dict:query	查看字典类型详细信息
创建字典类型	P0	system:dict:create	创建新的字典类型
编辑字典类型	P0	system:dict:update	修改字典类型信息
删除字典类型	P0	system:dict:delete	逻辑删除字典类型
批量删除字典类型	P1	system:dict:delete	批量逻辑删除字典类型
导出字典类型 Excel	P1	system:dict:query	导出字典类型列表 Excel
字典类型精简列表	P0	免鉴权（前端全局需要）	获取全部字典类型列表，用于前端下拉选择

3.1.2 字典类型列表（分页查询）

页面描述：

字典类型列表页面线框图

业务规则：

规则编号	规则描述	为什么这样设计
R-01	默认按创建时间倒序排列	最新创建的排在前面，方便管理员快速找到刚创建的内容
R-02	支持按字典名称模糊搜索	管理员可能只记得大概名称，模糊搜索降低记忆负担
R-03	支持按字典类型编码模糊搜索	开发者更熟悉编码，方便快速定位
R-04	支持按状态筛选（正常 0 / 停用 1）	快速过滤掉停用的字典类型
R-05	支持按创建时间范围筛选	审计场景下按时间段查找变更记录
R-06	字典类型编码（type）全局唯一，不可重复	编码是字典的唯一标识，重复会导致数据混乱
R-07	字典类型名称（name）建议唯一，但不强制	名称主要用于展示，允许同名但不同编码的字典类型存在

数据字段：

字段名	类型	说明
id	Long	字典类型编号
name	String	字典名称（展示用）
type	String	字典类型编码（唯一标识）
status	Integer	状态（0-正常 1-停用）
remark	String	备注
createTime	LocalDateTime	创建时间

接口设计：

接口名称	请求方式	接口路径	说明
获取字典类型分页	GET	/admin-api/system/dict-type/page	获取字典类型分页列表
获取字典类型详情	GET	/admin-api/system/dict-type/get	获取字典类型详细信息

请求参数（分页查询）：

参数名	类型	必填	说明
name	String	否	字典名称（模糊匹配）
type	String	否	字典类型编码（模糊匹配）
status	Integer	否	状态（0-正常 1-停用）
createTime	DateTime[]	否	创建时间范围
pageNo	Integer	是	页码
pageSize	Integer	是	每页条数

返回结果（分页）：

字段名	类型	说明
list[]	DictTypeRespVO	字典类型列表
total	Long	总记录数

3.1.3 创建字典类型

页面描述：

创建字典类型对话框

业务规则：

规则编号	规则描述	为什么这样设计
R-01	字典类型编码（type）全局唯一，创建时校验是否已存在	编码是字典数据的索引键，重复会导致数据错乱
R-02	字典类型名称（name）不能为空	名称是管理员识别字典的主要依据
R-03	创建成功后自动刷新字典缓存	保证后续接口能立即获取到新字典类型
R-04	字典类型编码建议使用"模块_业务_字段"的命名规范	统一命名规范便于团队协作和后期维护，如 `system_user_sex`、`order_status`

接口设计：

接口名称	请求方式	接口路径	说明
创建字典类型	POST	/admin-api/system/dict-type/create	创建字典类型

请求参数：

参数名	类型	必填	说明
name	String	是	字典名称，最大 100 字符
type	String	是	字典类型编码，最大 100 字符
status	Integer	是	状态（0-正常 1-停用）
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Long	新创建的字典类型编号

3.1.4 编辑字典类型

业务规则：

规则编号	规则描述	为什么这样设计
R-01	字典类型编码（type）不可与其他字典类型重复（排除自身）	防止编码冲突
R-02	修改字典类型编码时，需同步更新关联字典数据的 dictType 字段	字典数据通过 dictType 字段关联字典类型，编码变了必须同步，否则数据断裂
R-03	修改字典类型信息后自动刷新字典缓存	保证缓存与数据库一致
R-04	停用字典类型后，前端精简列表仍包含该类型，但该类型下的字典数据仅返回启用状态的项	前端需要知道这个字典类型存在（否则下拉框标签都显示不出来），只是选项变少了

接口设计：

接口名称	请求方式	接口路径	说明
更新字典类型	PUT	/admin-api/system/dict-type/update	更新字典类型

请求参数：

参数名	类型	必填	说明
id	Long	是	字典类型编号
name	String	是	字典名称
type	String	是	字典类型编码
status	Integer	是	状态
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Boolean	是否成功

3.1.5 删除字典类型

业务规则：

规则编号	规则描述	为什么这样设计
R-01	逻辑删除，不物理删除	保留数据可追溯，避免误删导致不可恢复
R-02	删除前需二次确认	防止误操作
R-03	删除字典类型时，需检查该类型下是否存在字典数据项。若存在则提示"该字典类型下有 N 条字典数据，请先清空后再删除"，阻止删除	防止产生"孤儿"字典数据——类型没了但数据还在
R-04	删除后自动刷新字典缓存	保证缓存一致性
R-05	系统内置字典类型（如 common_status）不建议删除，前端可给予警告提示	内置字典被多个模块引用，删除可能导致系统异常

接口设计：

接口名称	请求方式	接口路径	说明
删除字典类型	DELETE	/admin-api/system/dict-type/delete	删除单个字典类型
批量删除字典类型	DELETE	/admin-api/system/dict-type/delete-list	批量删除字典类型

请求参数（删除）：

参数名	类型	必填	说明
id	Long	是	字典类型编号

请求参数（批量删除）：

参数名	类型	必填	说明
ids	List<Long>	是	字典类型编号列表

3.1.6 字典类型导出

业务规则：

规则编号	规则描述
R-01	支持 xls 格式
R-02	导出当前筛选条件下的全部字典类型（不分页）
R-03	导出字段包含：字典主键、字典名称、字典类型、状态、创建时间
R-04	状态字段使用字典转换显示（正常/停用），不显示数字

接口设计：

接口名称	请求方式	接口路径	说明
导出字典类型 Excel	GET	/admin-api/system/dict-type/export-excel	导出字典类型列表

请求参数：

参数名	类型	必填	说明
name	String	否	字典名称筛选
type	String	否	字典类型编码筛选
status	Integer	否	状态筛选
createTime	DateTime[]	否	创建时间范围

3.1.7 字典类型精简列表

业务规则：

规则编号	规则描述	为什么这样设计
R-01	返回全部字典类型（包括启用和停用的）	前端需要知道所有字典类型的存在，停用的类型标签仍然要展示
R-02	无需权限校验	前端全局需要，登录后就应该能拿到全部字典类型
R-03	返回字段仅包含 id、name、type 三个字段	精简传输体积，其他字段（如备注）前端不需要

接口设计：

接口名称	请求方式	接口路径	说明
字典类型精简列表	GET	/admin-api/system/dict-type/simple-list	获取全部字典类型精简列表
字典类型精简列表（别名）	GET	/admin-api/system/dict-type/list-all-simple	同上（兼容旧接口）

返回结果：

字段名	类型	说明
id	Long	字典类型编号
name	String	字典名称
type	String	字典类型编码

3.2 后台管理端 - 字典数据管理

3.2.1 功能清单

功能	优先级	权限标识	说明
字典数据列表（分页）	P0	system:dict:query	分页展示字典数据，支持搜索筛选
字典数据详情	P0	system:dict:query	查看字典数据详细信息
创建字典数据	P0	system:dict:create	创建新的字典数据项
编辑字典数据	P0	system:dict:update	修改字典数据项信息
删除字典数据	P0	system:dict:delete	逻辑删除字典数据项
批量删除字典数据	P1	system:dict:delete	批量逻辑删除字典数据
导出字典数据 Excel	P1	system:dict:export	导出字典数据列表 Excel
字典数据精简列表	P0	免鉴权（前端全局需要）	获取全部启用状态的字典数据，用于前端缓存

3.2.2 字典数据列表（分页查询）

页面描述：

字典数据列表页面线框图

业务规则：

规则编号	规则描述	为什么这样设计
R-01	默认按 sort 字段升序排列（sort 值越小越靠前）	字典数据的展示顺序由管理员控制，比如"男"排在"女"前面
R-02	支持按字典标签模糊搜索	快速找到某个具体选项
R-03	支持按字典类型模糊搜索	查看某个字典类型下的所有数据项
R-04	支持按状态筛选（正常 0 / 停用 1）	快速过滤掉已停用的选项
R-05	同一字典类型下的 value 应唯一，创建/编辑时校验	同一个下拉框里不能出现两个值相同的选项
R-06	字典数据需关联已有字典类型	不允许创建没有"归属"的字典数据

数据字段：

字段名	类型	说明
id	Long	字典数据编号
sort	Integer	字典排序（升序，值越小越靠前）
label	String	字典标签（显示文本，如"男"）
value	String	字典值（存储值，如"1"）
dictType	String	字典类型（关联字典类型编码）
status	Integer	状态（0-正常 1-停用）
colorType	String	颜色类型（前端标签渲染用）
cssClass	String	CSS 自定义样式
remark	String	备注
createTime	LocalDateTime	创建时间

接口设计：

接口名称	请求方式	接口路径	说明
获取字典数据分页	GET	/admin-api/system/dict-data/page	获取字典数据分页列表
获取字典数据详情	GET	/admin-api/system/dict-data/get	获取字典数据详细信息

请求参数（分页查询）：

参数名	类型	必填	说明
label	String	否	字典标签（模糊匹配）
dictType	String	否	字典类型编码（模糊匹配）
status	Integer	否	状态（0-正常 1-停用）
pageNo	Integer	是	页码
pageSize	Integer	是	每页条数

返回结果（分页）：

字段名	类型	说明
list[]	DictDataRespVO	字典数据列表
total	Long	总记录数

3.2.3 创建字典数据

页面描述：

创建字典数据对话框

业务规则：

规则编号	规则描述	为什么这样设计
R-01	同一字典类型（dictType）下，字典值（value）不可重复	同一个下拉框里不能有两个选项对应同一个值
R-02	字典类型必须已存在	字典数据必须归属于一个已定义的字典类型
R-03	创建成功后自动刷新字典缓存	保证前端立即能拿到新数据
R-04	颜色类型用于前端标签展示时的颜色渲染	比如"成功"用绿色、"失败"用红色，让状态一目了然
R-05	CSS 样式用于前端自定义展示样式	当预设颜色不够用时，允许通过 CSS class 自定义样式

接口设计：

接口名称	请求方式	接口路径	说明
创建字典数据	POST	/admin-api/system/dict-data/create	创建字典数据

请求参数：

参数名	类型	必填	说明
sort	Integer	是	排序值
label	String	是	字典标签，最大 100 字符
value	String	是	字典值，最大 100 字符
dictType	String	是	字典类型编码，最大 100 字符
status	Integer	是	状态（0-正常 1-停用）
colorType	String	否	颜色类型
cssClass	String	否	CSS 样式
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Long	新创建的字典数据编号

3.2.4 编辑字典数据

业务规则：

规则编号	规则描述	为什么这样设计
R-01	同一字典类型下，字典值（value）不可与其他项重复（排除自身）	防止值冲突
R-02	修改字典数据后自动刷新字典缓存	保证缓存与数据库一致
R-03	CSS 样式字段支持清空（updateStrategy = ALWAYS）	有些场景需要移除自定义样式，编辑时清空 CSS 样式应能正常保存空值

接口设计：

接口名称	请求方式	接口路径	说明
更新字典数据	PUT	/admin-api/system/dict-data/update	更新字典数据

请求参数：

参数名	类型	必填	说明
id	Long	是	字典数据编号
sort	Integer	是	排序值
label	String	是	字典标签
value	String	是	字典值
dictType	String	是	字典类型编码
status	Integer	是	状态
colorType	String	否	颜色类型
cssClass	String	否	CSS 样式
remark	String	否	备注

返回结果：

字段名	类型	说明
data	Boolean	是否成功

3.2.5 删除字典数据

业务规则：

规则编号	规则描述	为什么这样设计
R-01	逻辑删除，不物理删除	保留数据可追溯
R-02	删除前需二次确认	防止误操作
R-03	删除后自动刷新字典缓存	保证缓存一致性
R-04	批量删除时需确认提示"确定删除选中的 N 条字典数据吗？"	批量操作影响面大，需明确告知用户

接口设计：

接口名称	请求方式	接口路径	说明
删除字典数据	DELETE	/admin-api/system/dict-data/delete	删除单个字典数据
批量删除字典数据	DELETE	/admin-api/system/dict-data/delete-list	批量删除字典数据

请求参数（删除）：

参数名	类型	必填	说明
id	Long	是	字典数据编号

请求参数（批量删除）：

参数名	类型	必填	说明
ids	List<Long>	是	字典数据编号列表

3.2.6 字典数据导出

业务规则：

规则编号	规则描述
R-01	支持 xls 格式
R-02	导出当前筛选条件下的全部字典数据（不分页）
R-03	导出字段包含：字典编码、字典排序、字典标签、字典键值、字典类型、状态、创建时间
R-04	状态字段使用字典转换显示（正常/停用）

接口设计：

接口名称	请求方式	接口路径	说明
导出字典数据 Excel	GET	/admin-api/system/dict-data/export-excel	导出字典数据列表

请求参数：

参数名	类型	必填	说明
label	String	否	字典标签筛选
dictType	String	否	字典类型编码筛选
status	Integer	否	状态筛选

3.2.7 字典数据精简列表

业务规则：

规则编号	规则描述	为什么这样设计
R-01	仅返回状态为启用（status = 0）的字典数据	停用的选项不应出现在前端下拉框中
R-02	返回全部启用状态的字典数据（不限字典类型）	前端一次请求拿到所有字典数据，后续按 dictType 分组使用，避免每个下拉框都发一次请求
R-03	无需权限校验	前端全局需要，登录后就应该能拿到全部字典数据
R-04	返回字段包含：dictType、value、label、colorType、cssClass	只返回前端渲染需要的字段，减少传输体积
R-05	前端可根据 dictType 分组，按 sort 排序展示	前端在本地完成分组和排序，无需后端额外处理

接口设计：

接口名称	请求方式	接口路径	说明
字典数据精简列表	GET	/admin-api/system/dict-data/simple-list	获取全部启用字典数据精简列表
字典数据精简列表（别名）	GET	/admin-api/system/dict-data/list-all-simple	同上（兼容旧接口）

返回结果：

字段名	类型	说明
dictType	String	字典类型
value	String	字典值
label	String	字典标签
colorType	String	颜色类型
cssClass	String	CSS 样式

3.3 后台管理端 - 字典缓存机制

3.3.1 功能说明

字典缓存是数据字典模块的"加速器"。字典数据被频繁读取但很少修改（典型的"读多写少"场景），所以用 Redis 缓存起来，让每次读取都能在毫秒级完成。

缓存策略：

策略项	说明
缓存介质	Redis
缓存粒度	按字典类型（dictType）缓存对应的字典数据列表。比如"system_user_sex"对应的"男""女"两条数据作为一个整体缓存
缓存写入时机	服务启动时预加载、字典数据增删改时、字典类型增删改时
缓存失效策略	主动失效：数据变更时主动清除缓存，下次请求时自动重建
缓存穿透防护	缓存未命中时回源数据库查询，查询后回填缓存

缓存刷新流程：

场景一：字典数据变更（创建/更新/删除）
    ① 执行数据库操作（写入/更新/删除字典数据）
    ② 清除该 dictType 对应的 Redis 缓存
    ③ 下次有请求查询该 dictType 时，自动从数据库重新加载并写入缓存

场景二：字典类型变更（创建/更新/删除）
    ① 执行数据库操作（写入/更新/删除字典类型）
    ② 清除全部字典数据缓存
       （因为字典类型变更可能影响字典类型的有效性，为安全起见全量刷新）
    ③ 下次有请求时自动从数据库重新加载

业务规则：

规则编号	规则描述	为什么这样设计
R-01	服务启动时自动预加载全部字典数据到 Redis 缓存	避免服务刚启动时大量请求穿透到数据库（"缓存预热"）
R-02	字典数据的增删改操作完成后，自动刷新对应 dictType 的缓存	只刷新受影响的那一组缓存，而不是全量刷新，减少 Redis 压力
R-03	字典类型的增删改操作完成后，自动刷新全部字典缓存	字典类型变更影响面大（可能改了编码），全量刷新最安全
R-04	缓存刷新为同步操作	保证接口返回时缓存已经更新，前端立即能拿到最新数据
R-05	如果 Redis 不可用，降级为直接查询数据库	缓存是加速手段，不能因为缓存挂了就让整个系统不可用

3.4 前台使用 - App 端字典数据查询

3.4.1 功能说明

前台 App 端提供通过字典类型直接查询字典数据列表的接口，用于移动端或第三方系统获取字典数据。

3.4.2 根据字典类型查询字典数据

业务规则：

规则编号	规则描述	为什么这样设计
R-01	仅返回启用状态的字典数据	停用的选项不应出现在 App 端的下拉框中
R-02	返回结果按 sort 字段升序排列	保持与后台管理端一致的展示顺序
R-03	无需登录鉴权（@PermitAll）	字典数据是公开的配置信息，不需要登录就能获取
R-04	传入的字典类型不存在时返回空列表	不报错，让调用方自行处理空数据
R-05	优先从 Redis 缓存中读取	保证高性能响应

接口设计：

接口名称	请求方式	接口路径	说明
按字典类型查询字典数据	GET	/app-api/system/dict-data/type	根据字典类型获取字典数据列表

请求参数：

参数名	类型	必填	说明
type	String	是	字典类型编码，如"common_status"

返回结果：

字段名	类型	说明
id	Long	字典数据编号
sort	Integer	排序
label	String	字典标签
value	String	字典值
dictType	String	字典类型
colorType	String	颜色类型
cssClass	String	CSS 样式

3.5 字典数据校验

3.5.1 功能说明

在服务端提供字典数据合法性校验能力，供业务模块在保存数据时调用，确保引用的字典值合法有效。

校验规则：

规则编号	规则描述	为什么这样设计
R-01	校验字典数据是否存在于指定字典类型下	防止前端传了一个不存在的字典值进来
R-02	校验字典数据是否处于启用状态	已停用的字典值不应再被使用
R-03	不满足条件时抛出业务异常，阻止保存	在数据写入数据库之前拦截非法值

校验流程：

业务模块调用：validateDictDataList("order_status", ["1", "2", "5"])
    ① 查询"order_status"下所有启用状态的字典数据
       → 得到合法值列表：["1", "2", "3", "4"]
    ② 逐一校验传入的值
       → "1" ✓ 存在且启用
       → "2" ✓ 存在且启用
       → "5" ✗ 不存在
    ③ 发现非法值"5"，抛出异常："字典数据[order_status]的值[5]不存在或已停用"

四、非功能需求

4.1 性能要求

指标	要求	说明
字典类型分页查询	< 200ms	包含搜索筛选场景
字典数据分页查询	< 200ms	包含搜索筛选场景
字典类型精简列表	< 100ms	数据量小，应快速返回
字典数据精简列表（命中缓存）	< 50ms	前端全局缓存的核心接口，必须足够快
App 端按类型查询（命中缓存）	< 50ms	移动端对延迟更敏感
字典缓存刷新	< 100ms	同步刷新不能让用户等太久
服务启动预加载	< 2s（1000 条以内）	不能因为加载字典拖慢服务启动速度

4.2 安全要求

要求	说明
权限控制	字典管理接口严格按权限标识（system:dict:create/update/delete/query/export）控制访问
操作日志	所有字典管理操作（创建、编辑、删除、导出）记录操作日志，便于审计追溯
参数校验	所有输入参数进行合法性校验（长度、格式、非空），防止 SQL 注入与 XSS 攻击
数据一致性	字典数据变更与缓存刷新保证最终一致性——先写数据库，再刷缓存，即使缓存刷新失败也能在下次请求时自动重建

4.3 兼容性要求

端	要求
PC 浏览器	Chrome 80+、Firefox 75+、Safari 13+
数据库	MySQL 5.7+、PostgreSQL 12+、Oracle 12c+、SQL Server 2017+
Redis	Redis 5.0+

五、数据设计

5.1 数据模型

5.1.1 字典类型表（system_dict_type）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	字典类型编号（主键）
name	VARCHAR(100)	NOT NULL	字典名称（展示用）
type	VARCHAR(100)	NOT NULL	字典类型编码（全局唯一标识）
status	TINYINT	NOT NULL, DEFAULT 0	状态（0-正常 1-停用）
remark	VARCHAR(500)	-	备注
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记（0-未删除 1-已删除）
deleted_time	DATETIME	-	删除时间

重要：该表标注 @TenantIgnore，不进行租户隔离。字典数据是全局共享的——所有租户使用同一套字典。原因：字典定义的是系统级枚举值（如性别、状态），与租户无关。

索引设计：

索引名	字段	类型	说明
uk_type	type	UNIQUE	字典类型编码唯一索引，防止编码重复
idx_name	name	NORMAL	按名称查询加速
idx_status	status	NORMAL	按状态筛选加速

5.1.2 字典数据表（system_dict_data）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	字典数据编号（主键）
sort	INT	NOT NULL, DEFAULT 0	字典排序（升序排列）
label	VARCHAR(100)	NOT NULL	字典标签（显示文本）
value	VARCHAR(100)	NOT NULL	字典值（存储值）
dict_type	VARCHAR(100)	NOT NULL	字典类型（冗余字段，关联 system_dict_type.type）
status	TINYINT	NOT NULL, DEFAULT 0	状态（0-正常 1-停用）
color_type	VARCHAR(100)	-	颜色类型
css_class	VARCHAR(100)	-	CSS 自定义样式
remark	VARCHAR(500)	-	备注
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记

重要：该表标注 @TenantIgnore，不进行租户隔离，字典数据为全局共享。

索引设计：

索引名	字段	类型	说明
uk_dict_type_value	dict_type, value	UNIQUE	同字典类型下值唯一，数据库层面防止重复
idx_dict_type	dict_type	NORMAL	按字典类型查询加速（缓存读取的主要查询路径）
idx_sort	sort	NORMAL	按排序值排序加速
idx_status	status	NORMAL	按状态筛选加速

5.1.3 数据模型 ER 关系

字典ER关系图

5.2 数据字典

5.2.1 系统内置字典类型

系统预置了以下字典类型，在数据库初始化时自动写入：

字典类型编码	字典名称	字典数据项	使用场景
common_status	通用状态	0-开启, 1-关闭	全局通用的启用/停用状态
system_user_sex	用户性别	1-男, 2-女	用户管理中的性别选择
system_menu_type	菜单类型	1-目录, 2-菜单, 3-按钮	菜单管理中的类型区分
system_role_type	角色类型	1-内置, 2-自定义	角色管理中的类型区分
system_data_scope	数据范围	1-全部, 2-指定部门, 3-本部门, 4-本部门及以下, 5-仅本人	角色权限中的数据权限配置
system_notice_type	通知类型	1-通知, 2-公告	消息通知中的类型区分
system_login_result	登录结果	0-成功, 10-账号密码错误, 20-用户被禁用, 30-验证码不存在, 31-验证码不正确, 100-未知异常	登录日志中的结果记录
system_login_type	登录类型	100-账号登录, 101-社交登录, 103-短信登录, 200-主动登出, 202-强制登出	登录日志中的类型记录
system_oauth2_grant_type	OAuth2 授权类型	password-密码模式, authorization_code-授权码模式, implicit-简化模式, client_credentials-客户端模式, refresh_token-刷新模式	认证授权中的授权方式
infra_boolean_string	布尔值字符串	true-是, false-否	基础设施中的布尔值展示
infra_operate_type	操作类型	0-其它, 1-查询, 2-新增, 3-修改, 4-删除, 5-导出, 6-导入	操作日志中的操作类型
infra_job_status	定时任务状态	0-初始化/运行中, 1-正常(暂停), 2-暂停	定时任务管理中的状态
infra_config_type	参数类型	1-系统内置, 2-自定义	参数配置中的类型区分
infra_file_storage	文件存储	1-数据库, 10-本地磁盘, 11-FTP, 12-SFTP, 20-S3对象存储	文件管理中的存储方式

5.3 数据流转关系

操作	涉及的表	数据流转
创建字典类型	system_dict_type	创建字典类型记录 → 刷新全部字典缓存
编辑字典类型	system_dict_type + system_dict_data	更新字典类型信息 → 若 type 字段变更需同步更新关联字典数据的 dict_type → 刷新全部字典缓存
删除字典类型	system_dict_type	校验无关联字典数据 → 逻辑删除字典类型 → 刷新全部字典缓存
创建字典数据	system_dict_data	创建字典数据记录 → 刷新对应 dictType 的缓存
编辑字典数据	system_dict_data	更新字典数据记录 → 刷新对应 dictType 的缓存
删除字典数据	system_dict_data	逻辑删除字典数据 → 刷新对应 dictType 的缓存
前端加载字典	Redis	前端请求精简列表 → 从 Redis 缓存读取 → 缓存未命中则查库并回填
App 端查询字典	Redis + system_dict_data	按 dictType 查询 → 优先读缓存 → 缓存未命中则查库并回填

六、跨模块联动

数据字典作为平台基础模块，与多个业务模块存在紧密的数据依赖关系。以下梳理了关键的跨模块集成点。

6.1 联动模块清单

联动模块	联动方式	数据流向	说明
用户管理	字典数据被引用	字典 → 用户管理	用户性别、用户状态等下拉框使用字典数据
角色权限	字典数据被引用	字典 → 角色权限	数据范围（system_data_scope）、角色类型（system_role_type）使用字典数据
菜单管理	字典数据被引用	字典 → 菜单管理	菜单类型（system_menu_type）使用字典数据
认证授权	字典数据被引用	字典 → 认证授权	登录结果（system_login_result）、登录类型（system_login_type）、OAuth2 授权类型使用字典数据
日志审计	字典数据被引用 + 操作日志	字典 → 日志审计	操作类型（infra_operate_type）使用字典数据；字典管理的增删改操作写入操作日志
基础设施	字典数据被引用	字典 → 基础设施	定时任务状态、文件存储方式、参数类型使用字典数据
工作流	字典数据被引用	字典 → 工作流	流程状态、审批结果等下拉框使用字典数据
支付	字典数据被引用	字典 → 支付	支付渠道、支付状态等下拉框使用字典数据
前端全局	精简列表接口	字典 → 前端	前端在登录后一次性拉取全部字典数据并本地缓存

6.2 关键联动流程

6.2.1 前端字典数据加载流程

前端字典数据加载缓存流程

6.2.2 业务模块使用字典数据的流程

业务模块使用字典数据流程

6.3 数据一致性要求

一致性场景	保障措施
字典数据变更后前端展示	字典缓存自动刷新，前端下次请求获取最新数据。如需即时生效，前端可监听 WebSocket 通知主动刷新缓存
字典类型编码修改后业务引用	修改编码时同步更新关联字典数据的 dict_type 字段，但已存入业务表的历史数据不会自动更新，需评估影响范围
缓存与数据库一致性	先写数据库再刷缓存（Cache-Aside 模式），即使缓存刷新失败，下次请求也会自动从数据库重建缓存

七、附录

7.1 名词解释

术语	解释	类比
字典类型（Dict Type）	字典数据的分类标识，相当于"词典的一个词条标题"	比如"用户性别"就是一个字典类型
字典数据（Dict Data）	字典类型下的具体数据项，相当于"词条下面的具体内容"	比如"用户性别"下面的"男""女"就是字典数据
字典标签（Label）	字典数据的显示文本，给用户看的	下拉框里你看到的"男""女"
字典值（Value）	字典数据的存储值，给数据库存的	数据库里实际存的"1""2"
字典类型编码（dictType）	字典类型的唯一标识符，全局不可重复	类似于身份证号码，每个字典类型都有一个独一无二的编码
颜色类型（Color Type）	前端标签渲染时使用的颜色主题	比如"成功"显示绿色、"失败"显示红色
CSS 样式（CSS Class）	前端自定义展示的 CSS class 名称	当预设颜色不够用时，允许前端用自定义样式
排序值（Sort）	字典数据在同一字典类型下的展示排序，值越小排越前	类似于列表里的"置顶"，数字小的排前面
字典缓存	存储在 Redis 中的字典数据副本，用于加速读取	类似于把常用电话号码存在手机通讯录里，不用每次都翻电话簿
字典精简列表	只返回核心字段（dictType/value/label/colorType/cssClass）的字典数据列表	类似于"速查表"，只保留最常用的信息
@TenantIgnore	标注此注解的实体不参与租户数据隔离	字典数据是全局共享的，所有租户用同一套字典
CommonStatusEnum	通用状态枚举，0-正常（开启）、1-停用（关闭）	几乎所有模块都通用的"开关"
缓存预热	服务启动时自动将字典数据加载到 Redis 缓存	类似于开店前先把常卖的商品摆上货架，不用等顾客来了再去找
缓存穿透	请求的数据在缓存中不存在，导致请求直接打到数据库	类似于通讯录里没有这个号码，只能翻电话簿去找
dictType 冗余字段	字典数据表中存储的字典类型编码，与字典类型表的 type 字段冗余	为了查询方便，字典数据直接记住自己属于哪个字典类型

7.2 颜色类型对照表

颜色类型值	颜色主题	适用场景	举例
default	默认/灰色	普通状态、未分类	未知状态
primary	主色/蓝色	主要状态、默认选中	进行中
success	成功/绿色	正常、已通过、已完成	审核通过、已启用
info	信息/灰色	中性状态、提示	待处理
warning	警告/橙色	需注意、待处理	即将过期
danger	危险/红色	异常、失败、已停用	审核拒绝、已停用

7.3 字典命名规范

模块	命名格式	示例
系统管理	system_{业务}_	system_user_sex, system_menu_type
基础设施	infra_{业务}_	infra_job_status, infra_config_type
通用	common_	common_status
工作流	bpm_{业务}_	bpm_task_status, bpm_process_status
支付	pay_{业务}_	pay_order_status, pay_channel
商城	product_{业务}_	product_spu_status
营销	promotion_{业务}_	promotion_discount_type

7.4 接口汇总

7.4.1 字典类型管理接口

序号	接口名称	方法	路径	权限	优先级
1	创建字典类型	POST	/admin-api/system/dict-type/create	system:dict:create	P0
2	更新字典类型	PUT	/admin-api/system/dict-type/update	system:dict:update	P0
3	删除字典类型	DELETE	/admin-api/system/dict-type/delete	system:dict:delete	P0
4	批量删除字典类型	DELETE	/admin-api/system/dict-type/delete-list	system:dict:delete	P1
5	获取字典类型详情	GET	/admin-api/system/dict-type/get	system:dict:query	P0
6	获取字典类型分页	GET	/admin-api/system/dict-type/page	system:dict:query	P0
7	导出字典类型 Excel	GET	/admin-api/system/dict-type/export-excel	system:dict:query	P1
8	字典类型精简列表	GET	/admin-api/system/dict-type/simple-list	免鉴权	P0
9	字典类型精简列表（别名）	GET	/admin-api/system/dict-type/list-all-simple	免鉴权	P0

7.4.2 字典数据管理接口

序号	接口名称	方法	路径	权限	优先级
1	创建字典数据	POST	/admin-api/system/dict-data/create	system:dict:create	P0
2	更新字典数据	PUT	/admin-api/system/dict-data/update	system:dict:update	P0
3	删除字典数据	DELETE	/admin-api/system/dict-data/delete	system:dict:delete	P0
4	批量删除字典数据	DELETE	/admin-api/system/dict-data/delete-list	system:dict:delete	P1
5	获取字典数据详情	GET	/admin-api/system/dict-data/get	system:dict:query	P0
6	获取字典数据分页	GET	/admin-api/system/dict-data/page	system:dict:query	P0
7	导出字典数据 Excel	GET	/admin-api/system/dict-data/export-excel	system:dict:export	P1
8	字典数据精简列表	GET	/admin-api/system/dict-data/simple-list	免鉴权	P0
9	字典数据精简列表（别名）	GET	/admin-api/system/dict-data/list-all-simple	免鉴权	P0

7.4.3 App 端接口

序号	接口名称	方法	路径	权限	优先级
1	按字典类型查询字典数据	GET	/app-api/system/dict-data/type	PermitAll	P0

7.5 变更记录

版本	日期	修改内容	修改人
v1.0	2026-09-14	初始版本	PM Team
v2.0	2026-09-19	增强用户场景（7 个命名人物场景）、验收标准、跨模块联动（6.1-6.3）、名词解释（15 项）、ASCII 线框图、业务规则增加设计原因	PM Team

本文档为数据字典管理模块 PRD v2.0，如有问题请联系产品负责人。

数据字典管理 PRD ​

文档信息 ​

一、功能概述 ​

1.1 功能定位 ​

1.2 目标用户 ​

1.3 业务价值 ​

1.4 功能范围 ​

二、用户场景 ​

2.1 用户角色 ​

2.2 使用场景 ​

场景1：管理员新增字典类型并配置数据项 ​

场景2：前端开发者一次性缓存字典数据 ​

场景3：管理员停用字典数据并自动刷新缓存 ​

场景4：后端开发校验字典值合法性 ​

场景5：运营人员导出字典数据 ​

场景6：管理员修改字典类型编码 ​

场景7：App 端用户获取字典数据 ​

2.3 用户故事 ​

三、功能需求 ​

3.1 后台管理端 - 字典类型管理 ​

3.1.1 功能清单 ​

3.1.2 字典类型列表（分页查询） ​

3.1.3 创建字典类型 ​

3.1.4 编辑字典类型 ​

3.1.5 删除字典类型 ​

3.1.6 字典类型导出 ​

3.1.7 字典类型精简列表 ​

3.2 后台管理端 - 字典数据管理 ​

3.2.1 功能清单 ​

3.2.2 字典数据列表（分页查询） ​

3.2.3 创建字典数据 ​

3.2.4 编辑字典数据 ​

3.2.5 删除字典数据 ​

3.2.6 字典数据导出 ​

3.2.7 字典数据精简列表 ​

3.3 后台管理端 - 字典缓存机制 ​

3.3.1 功能说明 ​

3.4 前台使用 - App 端字典数据查询 ​

3.4.1 功能说明 ​

3.4.2 根据字典类型查询字典数据 ​

3.5 字典数据校验 ​

3.5.1 功能说明 ​

四、非功能需求 ​

4.1 性能要求 ​

4.2 安全要求 ​

4.3 兼容性要求 ​

五、数据设计 ​

5.1 数据模型 ​

5.1.1 字典类型表（system_dict_type） ​

5.1.2 字典数据表（system_dict_data） ​

5.1.3 数据模型 ER 关系 ​

5.2 数据字典 ​

5.2.1 系统内置字典类型 ​

5.3 数据流转关系 ​

六、跨模块联动 ​

6.1 联动模块清单 ​

6.2 关键联动流程 ​

6.2.1 前端字典数据加载流程 ​

6.2.2 业务模块使用字典数据的流程 ​

6.3 数据一致性要求 ​

七、附录 ​

7.1 名词解释 ​

7.2 颜色类型对照表 ​

7.3 字典命名规范 ​

7.4 接口汇总 ​

7.4.1 字典类型管理接口 ​

7.4.2 字典数据管理接口 ​

7.4.3 App 端接口 ​

7.5 变更记录 ​

数据字典管理 PRD

文档信息

一、功能概述

1.1 功能定位

1.2 目标用户

1.3 业务价值

1.4 功能范围

二、用户场景

2.1 用户角色

2.2 使用场景

场景1：管理员新增字典类型并配置数据项

场景2：前端开发者一次性缓存字典数据

场景3：管理员停用字典数据并自动刷新缓存

场景4：后端开发校验字典值合法性

场景5：运营人员导出字典数据

场景6：管理员修改字典类型编码

场景7：App 端用户获取字典数据

2.3 用户故事

三、功能需求

3.1 后台管理端 - 字典类型管理

3.1.1 功能清单

3.1.2 字典类型列表（分页查询）

3.1.3 创建字典类型

3.1.4 编辑字典类型

3.1.5 删除字典类型

3.1.6 字典类型导出

3.1.7 字典类型精简列表

3.2 后台管理端 - 字典数据管理

3.2.1 功能清单

3.2.2 字典数据列表（分页查询）

3.2.3 创建字典数据

3.2.4 编辑字典数据

3.2.5 删除字典数据

3.2.6 字典数据导出

3.2.7 字典数据精简列表

3.3 后台管理端 - 字典缓存机制

3.3.1 功能说明

3.4 前台使用 - App 端字典数据查询

3.4.1 功能说明

3.4.2 根据字典类型查询字典数据

3.5 字典数据校验

3.5.1 功能说明

四、非功能需求

4.1 性能要求

4.2 安全要求

4.3 兼容性要求

五、数据设计

5.1 数据模型

5.1.1 字典类型表（system_dict_type）

5.1.2 字典数据表（system_dict_data）

5.1.3 数据模型 ER 关系

5.2 数据字典

5.2.1 系统内置字典类型

5.3 数据流转关系

六、跨模块联动

6.1 联动模块清单

6.2 关键联动流程

6.2.1 前端字典数据加载流程

6.2.2 业务模块使用字典数据的流程

6.3 数据一致性要求

七、附录

7.1 名词解释

7.2 颜色类型对照表

7.3 字典命名规范

7.4 接口汇总

7.4.1 字典类型管理接口

7.4.2 字典数据管理接口

7.4.3 App 端接口

7.5 变更记录