字典
受众：开发者 / 运维 摘要：Core Dict 字典底座，负责字典、字典项、来源治理、展示文案解析和 Admin 运维。
Dict 用于维护可枚举业务元数据，例如状态、类型、分类和前端下拉选项。它只保存通用字典事实，不替代业务模块自己的状态机，也不承载多语言资源文件本身。
能力范围
| 能力 | 说明 |
|---|---|
| 字典管理 | 字典分页、创建、更新、启停、删除和批量删除 |
| 字典项管理 | 字典项分页、创建、更新、启停、删除和批量删除 |
| Options 查询 | 按字典 code 查询 label / value / disabled / sort |
| 来源治理 | 区分 framework / module / custom，系统托管记录只读 |
| 文案解析 | 通过 DictTextResolver 和模块私有 message key 解析展示文本 |
API 路径
| API | 说明 |
|---|---|
GET /api/v1/admin/dict/dicts | 分页查询字典 |
POST /api/v1/admin/dict/dicts/query | 按条件查询字典 |
GET /api/v1/admin/dict/dicts/{code}/options | 查询单个字典 options |
POST /api/v1/admin/dict/dicts/options | 批量查询字典 options |
GET /api/v1/admin/dict/dict-items | 分页查询字典项 |
POST /api/v1/admin/dict/dict-items | 创建字典项 |
权限前缀为 dict:dict:* 和 dict:dict-item:*。Admin 页面入口为 /#/dicts。
数据模型
| 表 | 说明 |
|---|---|
dict | 字典定义、来源、系统托管标记和状态 |
dict_item | 字典项、展示 key、排序、状态和来源 |
迁移归属：
| 文件 | 说明 |
|---|---|
spring-open-core/spring-open-core-dict/src/main/resources/db/changelog/migrations/0000_00_00_012000_core_dict_create_tables.xml | 建表 |
spring-open-core/spring-open-core-dict/src/main/resources/db/changelog/migrations/0000_00_00_012100_core_dict_seed_data.xml | 权限、菜单、内置字典和角色绑定 |
与其他模块的边界
- 业务模块可以 seed 自己的模块字典，但应标明
source_module。 - 系统托管字典可复制为自定义字典后再调整，不允许直接编辑内置记录。
- 多语言资源仍放各模块 i18n 文件；Dict 只保存展示 key 或展示值。
- 不把业务状态流转逻辑写进 Dict，状态机仍归 owning module。
验证命令
bash
./mvnw -pl spring-open-core/spring-open-core-dict -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
./.ai/scripts/check i18n
./.ai/scripts/check migrations
git diff --check