460 lines
9.1 KiB
Markdown
460 lines
9.1 KiB
Markdown
# 字典系统使用指南
|
||
|
||
## 概述
|
||
|
||
字典系统提供了统一的配置数据管理功能，包括字典类型和字典数据两个核心模块。遵循CRUD代码生成模板规范，统一使用功能性命名。
|
||
|
||
## 数据表结构
|
||
|
||
### 字典类型表 (system_dict_type)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 字典主键 |
|
||
| name | varchar(100) | 字典名称 |
|
||
| type | varchar(100) | 字典类型（唯一） |
|
||
| status | tinyint | 状态（0正常 1停用） |
|
||
| remark | varchar(500) | 备注 |
|
||
| creator | varchar(64) | 创建者 |
|
||
| create_time | datetime | 创建时间 |
|
||
| updater | varchar(64) | 更新者 |
|
||
| update_time | datetime | 更新时间 |
|
||
| deleted | bit(1) | 是否删除 |
|
||
| deleted_time | datetime | 删除时间 |
|
||
|
||
### 字典数据表 (system_dict_data)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 字典编码 |
|
||
| sort | int | 字典排序 |
|
||
| label | varchar(100) | 字典标签 |
|
||
| value | varchar(100) | 字典键值 |
|
||
| dict_type | varchar(100) | 字典类型 |
|
||
| status | tinyint | 状态（0正常 1停用） |
|
||
| color_type | varchar(100) | 颜色类型 |
|
||
| css_class | varchar(100) | CSS样式 |
|
||
| remark | varchar(500) | 备注 |
|
||
| creator | varchar(64) | 创建者 |
|
||
| create_time | datetime | 创建时间 |
|
||
| updater | varchar(64) | 更新者 |
|
||
| update_time | datetime | 更新时间 |
|
||
| deleted | bit(1) | 是否删除 |
|
||
|
||
## API接口说明
|
||
|
||
### 字典类型接口
|
||
|
||
#### 基础CRUD接口
|
||
|
||
1. **获取字典类型详情**
|
||
```http
|
||
POST /admin/system/dict/type/detail
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
2. **创建字典类型**
|
||
```http
|
||
POST /admin/system/dict/type/create
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"name": "性别",
|
||
"type": "sys_gender",
|
||
"status": 0,
|
||
"remark": "用户性别字典"
|
||
}
|
||
```
|
||
|
||
3. **更新字典类型**
|
||
```http
|
||
POST /admin/system/dict/type/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"name": "性别",
|
||
"type": "sys_gender",
|
||
"status": 0,
|
||
"remark": "用户性别字典"
|
||
}
|
||
```
|
||
|
||
4. **删除字典类型**
|
||
```http
|
||
POST /admin/system/dict/type/delete
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
5. **获取字典类型列表**
|
||
```http
|
||
POST /admin/system/dict/type/list
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"page": 1,
|
||
"page_size": 15,
|
||
"name": "性别",
|
||
"type": "sys_gender",
|
||
"status": 0,
|
||
"create_time_start": "2024-01-01",
|
||
"create_time_end": "2024-12-31"
|
||
}
|
||
```
|
||
|
||
6. **获取简单列表**
|
||
```http
|
||
POST /admin/system/dict/type/simple/list
|
||
```
|
||
|
||
#### 批量操作接口
|
||
|
||
7. **批量删除字典类型**
|
||
```http
|
||
POST /admin/system/dict/type/batch/delete
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
8. **更新字典类型状态**
|
||
```http
|
||
POST /admin/system/dict/type/status
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
9. **批量更新状态**
|
||
```http
|
||
POST /admin/system/dict/type/batch/status
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 业务扩展接口
|
||
|
||
10. **获取统计信息**
|
||
```http
|
||
POST /admin/system/dict/type/statistics
|
||
```
|
||
|
||
11. **获取选项列表**
|
||
```http
|
||
POST /admin/system/dict/type/options
|
||
```
|
||
|
||
12. **根据类型获取详情**
|
||
```http
|
||
POST /admin/system/dict/type/get-by-type
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"type": "sys_gender"
|
||
}
|
||
```
|
||
|
||
### 字典数据接口
|
||
|
||
#### 基础CRUD接口
|
||
|
||
1. **获取字典数据详情**
|
||
```http
|
||
POST /admin/system/dict/data/detail
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
2. **创建字典数据**
|
||
```http
|
||
POST /admin/system/dict/data/create
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"label": "男",
|
||
"value": "1",
|
||
"dict_type": "sys_gender",
|
||
"sort": 1,
|
||
"status": 0,
|
||
"color_type": "primary",
|
||
"css_class": "",
|
||
"remark": "男性"
|
||
}
|
||
```
|
||
|
||
3. **更新字典数据**
|
||
```http
|
||
POST /admin/system/dict/data/update
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"label": "男",
|
||
"value": "1",
|
||
"dict_type": "sys_gender",
|
||
"sort": 1,
|
||
"status": 0,
|
||
"color_type": "primary",
|
||
"css_class": "",
|
||
"remark": "男性"
|
||
}
|
||
```
|
||
|
||
4. **删除字典数据**
|
||
```http
|
||
POST /admin/system/dict/data/delete
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1
|
||
}
|
||
```
|
||
|
||
5. **获取字典数据列表**
|
||
```http
|
||
POST /admin/system/dict/data/list
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"page": 1,
|
||
"page_size": 15,
|
||
"label": "男",
|
||
"value": "1",
|
||
"dict_type": "sys_gender",
|
||
"status": 0,
|
||
"color_type": "primary"
|
||
}
|
||
```
|
||
|
||
6. **获取简单列表**
|
||
```http
|
||
POST /admin/system/dict/data/simple/list
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender"
|
||
}
|
||
```
|
||
|
||
#### 批量操作接口
|
||
|
||
7. **批量删除字典数据**
|
||
```http
|
||
POST /admin/system/dict/data/batch/delete
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
8. **更新状态**
|
||
```http
|
||
POST /admin/system/dict/data/status
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
9. **批量更新状态**
|
||
```http
|
||
POST /admin/system/dict/data/batch/status
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"ids": [1, 2, 3],
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
10. **更新排序**
|
||
```http
|
||
POST /admin/system/dict/data/sort
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"id": 1,
|
||
"sort": 10
|
||
}
|
||
```
|
||
|
||
11. **批量更新排序**
|
||
```http
|
||
POST /admin/system/dict/data/batch/sort
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"sort_data": [
|
||
{"id": 1, "sort": 1},
|
||
{"id": 2, "sort": 2},
|
||
{"id": 3, "sort": 3}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 业务查询接口
|
||
|
||
12. **根据字典类型获取数据列表**
|
||
```http
|
||
POST /admin/system/dict/data/get-by-type
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender",
|
||
"only_active": true
|
||
}
|
||
```
|
||
|
||
13. **获取选项列表**
|
||
```http
|
||
POST /admin/system/dict/data/options
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender",
|
||
"only_active": true
|
||
}
|
||
```
|
||
|
||
14. **根据类型和值获取标签**
|
||
```http
|
||
POST /admin/system/dict/data/get-label
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender",
|
||
"value": "1"
|
||
}
|
||
```
|
||
|
||
15. **根据类型和值获取字典数据**
|
||
```http
|
||
POST /admin/system/dict/data/get-by-type-value
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender",
|
||
"value": "1"
|
||
}
|
||
```
|
||
|
||
16. **获取统计信息**
|
||
```http
|
||
POST /admin/system/dict/data/statistics
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"dict_type": "sys_gender"
|
||
}
|
||
```
|
||
|
||
17. **获取分组统计信息**
|
||
```http
|
||
POST /admin/system/dict/data/group-statistics
|
||
```
|
||
|
||
## 预置字典数据
|
||
|
||
系统预置了以下常用字典类型：
|
||
|
||
### 系统通用字典
|
||
- `sys_gender` - 性别（男、女、未知）
|
||
- `sys_status` - 状态（正常、停用）
|
||
- `sys_yes_no` - 是否（是、否）
|
||
- `sys_show_hide` - 显示状态（显示、隐藏）
|
||
- `sys_switch` - 系统开关（开启、关闭）
|
||
- `sys_menu_type` - 菜单类型（目录、菜单、按钮）
|
||
- `sys_user_type` - 用户类型（系统用户、学生、家长）
|
||
- `sys_operation_type` - 操作类型（新增、修改、删除、查询）
|
||
|
||
### 教育相关字典
|
||
- `edu_grade` - 年级（一年级~六年级）
|
||
- `edu_student_status` - 学生状态（在读、转学、毕业、退学）
|
||
|
||
## 数据库操作
|
||
|
||
### 运行迁移
|
||
```bash
|
||
php artisan migrate
|
||
```
|
||
|
||
### 填充测试数据
|
||
```bash
|
||
# 填充字典类型数据
|
||
php artisan db:seed --class=SystemDictTypeSeeder
|
||
|
||
# 填充字典数据
|
||
php artisan db:seed --class=SystemDictDataSeeder
|
||
|
||
# 或者运行所有填充器
|
||
php artisan db:seed
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 在代码中使用字典
|
||
|
||
1. **获取字典选项**
|
||
```php
|
||
use App\Models\System\SystemDictData;
|
||
|
||
// 获取性别选项
|
||
$genderOptions = SystemDictData::getOptionsByType('sys_gender');
|
||
// 返回：['1' => '男', '2' => '女', '0' => '未知']
|
||
```
|
||
|
||
2. **获取字典标签**
|
||
```php
|
||
// 根据值获取标签
|
||
$label = SystemDictData::getLabelByTypeAndValue('sys_gender', '1');
|
||
// 返回：'男'
|
||
```
|
||
|
||
3. **获取字典数据列表**
|
||
```php
|
||
// 获取某类型的所有数据
|
||
$genderList = SystemDictData::getByType('sys_gender', true);
|
||
```
|
||
|
||
## 系统字段配置
|
||
|
||
字典表启用了系统字段自动维护：
|
||
- **tenant_id** - 租户ID（如果启用多租户）
|
||
- **creator** - 创建者
|
||
- **create_time** - 创建时间
|
||
- **updater** - 更新者
|
||
- **update_time** - 更新时间
|
||
- **deleted** - 删除标识
|
||
|
||
## 注意事项
|
||
|
||
1. 字典类型的`type`字段必须唯一
|
||
2. 同一字典类型下的`value`字段必须唯一
|
||
3. 删除字典类型时会级联删除对应的字典数据
|
||
4. 字典数据按`sort`字段升序排列
|
||
5. 所有接口都支持软删除功能
|
||
6. 系统会自动维护创建者、更新者等系统字段
|