zijing/study-api-v2

Fork 0

zijing b43bf56e8e 新增学校、校区、班级和学生管理功能，包括控制器、请求验证、服务层和模型，完善CRUD操作及统计功能，更新路由以支持新功能。

2025-07-15 17:35:13 +08:00

9.1 KiB

Raw Permalink Blame History

字典系统使用指南

概述

字典系统提供了统一的配置数据管理功能，包括字典类型和字典数据两个核心模块。遵循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接口

获取字典类型详情

POST /admin/system/dict/type/detail
Content-Type: application/json

{
  "id": 1
}

创建字典类型

POST /admin/system/dict/type/create
Content-Type: application/json

{
  "name": "性别",
  "type": "sys_gender",
  "status": 0,
  "remark": "用户性别字典"
}

更新字典类型

POST /admin/system/dict/type/update
Content-Type: application/json

{
  "id": 1,
  "name": "性别",
  "type": "sys_gender",
  "status": 0,
  "remark": "用户性别字典"
}

删除字典类型

POST /admin/system/dict/type/delete
Content-Type: application/json

{
  "id": 1
}

获取字典类型列表

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"
}

获取简单列表

POST /admin/system/dict/type/simple/list

批量操作接口

批量删除字典类型

POST /admin/system/dict/type/batch/delete
Content-Type: application/json

{
  "ids": [1, 2, 3]
}

更新字典类型状态

POST /admin/system/dict/type/status
Content-Type: application/json

{
  "id": 1,
  "status": 1
}

批量更新状态

POST /admin/system/dict/type/batch/status
Content-Type: application/json

{
  "ids": [1, 2, 3],
  "status": 1
}

业务扩展接口

获取统计信息

POST /admin/system/dict/type/statistics

获取选项列表
```
POST /admin/system/dict/type/options
```

根据类型获取详情

POST /admin/system/dict/type/get-by-type
Content-Type: application/json

{
  "type": "sys_gender"
}

字典数据接口

基础CRUD接口

获取字典数据详情

POST /admin/system/dict/data/detail
Content-Type: application/json

{
  "id": 1
}

创建字典数据

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": "男性"
}

更新字典数据

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": "男性"
}

删除字典数据

POST /admin/system/dict/data/delete
Content-Type: application/json

{
  "id": 1
}

获取字典数据列表

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"
}

获取简单列表

POST /admin/system/dict/data/simple/list
Content-Type: application/json

{
  "dict_type": "sys_gender"
}

批量操作接口

批量删除字典数据

POST /admin/system/dict/data/batch/delete
Content-Type: application/json

{
  "ids": [1, 2, 3]
}

更新状态

POST /admin/system/dict/data/status
Content-Type: application/json

{
  "id": 1,
  "status": 1
}

批量更新状态

POST /admin/system/dict/data/batch/status
Content-Type: application/json

{
  "ids": [1, 2, 3],
  "status": 1
}

更新排序

POST /admin/system/dict/data/sort
Content-Type: application/json

{
  "id": 1,
  "sort": 10
}

批量更新排序

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}
  ]
}

业务查询接口

根据字典类型获取数据列表

POST /admin/system/dict/data/get-by-type
Content-Type: application/json

{
  "dict_type": "sys_gender",
  "only_active": true
}

获取选项列表

POST /admin/system/dict/data/options
Content-Type: application/json

{
  "dict_type": "sys_gender",
  "only_active": true
}

根据类型和值获取标签

POST /admin/system/dict/data/get-label
Content-Type: application/json

{
  "dict_type": "sys_gender",
  "value": "1"
}

根据类型和值获取字典数据

POST /admin/system/dict/data/get-by-type-value
Content-Type: application/json

{
  "dict_type": "sys_gender",
  "value": "1"
}

获取统计信息

POST /admin/system/dict/data/statistics
Content-Type: application/json

{
  "dict_type": "sys_gender"
}

获取分组统计信息

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 - 学生状态（在读、转学、毕业、退学）

数据库操作

运行迁移

php artisan migrate

填充测试数据

# 填充字典类型数据
php artisan db:seed --class=SystemDictTypeSeeder

# 填充字典数据
php artisan db:seed --class=SystemDictDataSeeder

# 或者运行所有填充器
php artisan db:seed

使用示例

在代码中使用字典

获取字典选项

use App\Models\System\SystemDictData;

// 获取性别选项
$genderOptions = SystemDictData::getOptionsByType('sys_gender');
// 返回：['1' => '男', '2' => '女', '0' => '未知']

获取字典标签

// 根据值获取标签
$label = SystemDictData::getLabelByTypeAndValue('sys_gender', '1');
// 返回：'男'

获取字典数据列表

// 获取某类型的所有数据
$genderList = SystemDictData::getByType('sys_gender', true);

系统字段配置

字典表启用了系统字段自动维护：

tenant_id - 租户ID（如果启用多租户）
creator - 创建者
create_time - 创建时间
updater - 更新者
update_time - 更新时间
deleted - 删除标识

注意事项

字典类型的type字段必须唯一
同一字典类型下的value字段必须唯一
删除字典类型时会级联删除对应的字典数据
字典数据按sort字段升序排列
所有接口都支持软删除功能
系统会自动维护创建者、更新者等系统字段

9.1 KiB Raw Permalink Blame History Unescape Escape

字典系统使用指南

概述

数据表结构

字典类型表 (system_dict_type)

字典数据表 (system_dict_data)

API接口说明

字典类型接口

基础CRUD接口

批量操作接口

业务扩展接口

字典数据接口

基础CRUD接口

批量操作接口

业务查询接口

预置字典数据

系统通用字典

教育相关字典

数据库操作

运行迁移

填充测试数据

使用示例

在代码中使用字典

系统字段配置

注意事项

9.1 KiB

Raw Permalink Blame History