📖 数据字典

数据字典提供可由运营维护的选项集合，例如银行类型、用户类型、来源渠道。它解决的是“页面上有哪些选项”，区别于影响系统行为的 系统配置。

🎯 本页目标

读完本章节后，应能掌握：

• 字典 / 配置 / Enum / .env 的选型边界。
• 字典类型与字典项的两层结构。
• 使用 sysDict() 读取字典的几种姿势。
• 字典缓存失效与新增字典的标准流程。

🧭 配置 / 字典 / Enum / .env 选型

场景	推荐方案	例子
部署环境相关，通常不让后台运营修改	.env / config/*.php	数据库连接、Redis、队列连接、第三方基础域名
后台可维护，会影响系统行为	配置 configs	站点开关、上传大小、存储驱动、AI 开关
后台可维护，主要给表单或页面展示选项	数据字典	银行类型、用户类型、业务状态、来源渠道
代码内稳定且不希望后台随意改	PHP Enum / 常量	支付状态、订单状态、终端类型、核心业务流转状态

经验规则：如果这个值改变后会影响“系统怎么运行”，优先考虑配置；如果它只是“页面上有哪些选项”，优先考虑字典；如果它是核心流程状态，不应被后台随意调整，优先使用 Enum。

📖 数据字典是什么

数据字典是一组可维护的选项。它通常由两层组成：

• 字典类型：定义一个选项集合，例如 bank。
• 字典项：这个集合下的具体选项，例如 ICBC、ABC、CCB。

典型用途：

• 后台表单下拉框。
• 用户端筛选项。
• 状态值展示文案。
• 可由运营维护的选项集合。

不适合做字典的场景：

• 订单状态、支付状态这类强流程状态。
• 会参与复杂分支判断的核心业务状态。
• 与数据库结构或代码流程强绑定的值。

这些更适合写成 PHP Enum 或常量。

🧾 字典接口

后台接口：

GET /adminapi/system/config/dict
GET /adminapi/system/setting/dict/type/list
GET /adminapi/system/setting/dict/data/list

用户端接口：

GET /api/system/config/dict

后台管理字典类型和字典项，用户端只读取允许公开的字典数据。涉及敏感业务选项时，不要随意通过公开接口输出。

📥 字典读取

业务代码读取字典优先使用全局 sysDict()。它底层走 DictService，会保留字典缓存。

读取一个字典：

$bank = sysDict('bank');

读取多个字典：

$dicts = sysDict('bank,user_type');
$dicts = sysDict(['bank', 'user_type']);

返回结构通常按 type 分组：

[
    'bank' => [
        ['name' => '工商银行', 'value' => 'ICBC'],
        ['name' => '农业银行', 'value' => 'ABC'],
    ],
]

如果只读取一个类型，并希望拿到 value => name 映射：

$map = sysDict('bank', false);

返回示例：

[
    'ICBC' => '工商银行',
    'ABC' => '农业银行',
]

🧊 字典缓存

字典按 type_key 缓存。

缓存 key 规则：

sunadmin:dict:type:{type}

配置：

'dict_cache' => [
    'enabled' => true,
    'ttl' => 300,
    'prefix' => 'sunadmin:dict',
],

修改字典类型或字典项后，需要清理对应缓存：

app(DictService::class)->forgetType('bank');
app(DictService::class)->forgetTypes(['bank', 'user_type']);

后台字典保存逻辑应负责清理缓存；如果通过脚本、Seeder 或 SQL 手动修改，也要同步考虑缓存失效。

🧑‍🏫 新增字典流程

1. 定义稳定的 type_key，使用英文小写和下划线，例如 user_source。
2. 新增字典类型，并明确是否启用。
3. 新增字典项，维护 name、value、sort、status。
4. 前端通过字典接口读取选项，不在页面里写死文案。
5. 后端如需展示文案，可通过 sysDict($type, false) 获取映射。
6. 修改字典项后清理对应缓存。
7. 删除或修改 value 前确认历史数据是否已经引用该值。

✅ 使用建议

• 后台可维护、主要用于表单选项或页面展示的集合使用字典。
• 字典 type_key 和 value 要稳定，不要使用中文或临时文案。
• 前端只展示字典，不把字典文案写死在页面里。
• 字典删除或改值前确认历史数据是否引用该 value。
• 影响系统行为的开关使用 系统配置，而不是字典。