# 字典系统使用指南

## 概述

字典系统提供了统一的配置数据管理功能，包括字典类型和字典数据两个核心模块。遵循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. 系统会自动维护创建者、更新者等系统字段