提交
This commit is contained in:
zlwu committed
1 parent
6ca85a1b15
commit
7d4bfaecb3
45 files changed
+7015
-1762
No files matched your search
@@ -1,854 +0,0 @@
|
||||
# 学生信息管理API文档
|
||||
|
||||
## 1. 文档说明
|
||||
|
||||
### 1.1 API基础信息
|
||||
- **模块名称**: 学工管理 - 学生信息管理
|
||||
- **模块代码**: ruoyi-xg
|
||||
- **基础路径**: `/studentMsg/studentMsg`
|
||||
- **权限前缀**: `studentMsg:studentMsg`
|
||||
- **版本**: 1.0.0
|
||||
- **更新时间**: 2025-01-27（新增班级学生查询接口）
|
||||
|
||||
### 1.2 通用规范
|
||||
- **请求方式**: 支持GET、POST、PUT、DELETE
|
||||
- **数据格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
- **认证方式**: Bearer Token
|
||||
- **权限控制**: Sa-Token + 数据权限
|
||||
|
||||
### 1.3 响应格式
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {},
|
||||
"timestamp": "2025-01-27T18:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 学生信息管理接口
|
||||
|
||||
### 2.1 查询学生信息列表
|
||||
- **接口路径**: GET `/studentMsg/studentMsg/list`
|
||||
- **权限标识**: `studentMsg:studentMsg:list`
|
||||
- **功能描述**: 分页查询学生信息列表，支持多条件筛选
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| pageNum | integer | 否 | 页码，默认1 |
|
||||
| pageSize | integer | 否 | 每页大小，默认10 |
|
||||
| studentNo | string | 否 | 学号 |
|
||||
| name | string | 否 | 姓名（模糊查询） |
|
||||
| idCard | string | 否 | 身份证号 |
|
||||
| gender | string | 否 | 性别：0-男，1-女 |
|
||||
| studentStatus | string | 否 | 学籍状态 |
|
||||
| phone | string | 否 | 联系电话（模糊查询） |
|
||||
| email | string | 否 | 邮箱 |
|
||||
| classId | string | 否 | 班级ID |
|
||||
| className | string | 否 | 班级名称 |
|
||||
| majorId | string | 否 | 专业ID |
|
||||
| majorName | string | 否 | 专业名称 |
|
||||
| collegeId | string | 否 | 学院ID |
|
||||
| collegeName | string | 否 | 学院名称 |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1",
|
||||
"createTime": "2025-01-27 10:00:00",
|
||||
"updateTime": "2025-01-27 10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 根据组织ID查询学生信息列表
|
||||
- **接口路径**: POST `/studentMsg/studentMsg/listByDeptId`
|
||||
- **权限标识**: `studentMsg:studentMsg:list`
|
||||
- **功能描述**: 根据部门ID查询该组织下所有学生信息
|
||||
|
||||
#### 请求参数
|
||||
```json
|
||||
{
|
||||
"dept_id": 101,
|
||||
"name": "张",
|
||||
"studentNo": "2023001",
|
||||
"phone": "138",
|
||||
"studentStatus": "1",
|
||||
"beginTime": "2025-01-01",
|
||||
"endTime": "2025-01-27"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"rows": [...],
|
||||
"total": 10
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 查询班级中所有学生信息 ⭐ 新增
|
||||
- **接口路径**: GET `/studentMsg/studentMsg/listByClassId`
|
||||
- **权限标识**: `studentMsg:studentMsg:query`
|
||||
- **功能描述**: 查询指定班级中所有在籍学生信息
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| classId | string | 是 | 班级ID |
|
||||
| name | string | 否 | 学生姓名（模糊查询） |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1",
|
||||
"createTime": "2025-01-27 10:00:00",
|
||||
"updateTime": "2025-01-27 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 业务逻辑
|
||||
1. 在 `xg_student_msg` 表中查询：
|
||||
- `deleted = 0` (未删除)
|
||||
- `student_status = '1'` (在籍状态)
|
||||
- `class_id = 入参的classId` (班级ID)
|
||||
- `name LIKE '%入参的name%'` (姓名模糊查询，可选)
|
||||
- 按创建时间倒序排列
|
||||
|
||||
### 2.4 获取学生信息详情
|
||||
- **接口路径**: GET `/studentMsg/studentMsg/{id}`
|
||||
- **权限标识**: `studentMsg:studentMsg:query`
|
||||
- **功能描述**: 根据ID获取学生详细信息
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | long | 是 | 学生ID |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1",
|
||||
"createTime": "2025-01-27 10:00:00",
|
||||
"updateTime": "2025-01-27 10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.5 新增学生信息
|
||||
- **接口路径**: POST `/studentMsg/studentMsg`
|
||||
- **权限标识**: `studentMsg:studentMsg:add`
|
||||
- **功能描述**: 新增学生信息
|
||||
|
||||
#### 请求参数
|
||||
```json
|
||||
{
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "新增成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 修改学生信息
|
||||
- **接口路径**: PUT `/studentMsg/studentMsg`
|
||||
- **权限标识**: `studentMsg:studentMsg:edit`
|
||||
- **功能描述**: 修改学生信息
|
||||
|
||||
#### 请求参数
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.7 删除学生信息
|
||||
- **接口路径**: DELETE `/studentMsg/studentMsg/{ids}`
|
||||
- **权限标识**: `studentMsg:studentMsg:remove`
|
||||
- **功能描述**: 批量删除学生信息
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| ids | string | 是 | 学生ID列表，多个用逗号分隔 |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.8 导出学生信息
|
||||
- **接口路径**: POST `/studentMsg/studentMsg/export`
|
||||
- **权限标识**: `studentMsg:studentMsg:export`
|
||||
- **功能描述**: 导出学生信息列表
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| studentNo | string | 否 | 学号 |
|
||||
| name | string | 否 | 姓名 |
|
||||
| studentStatus | string | 否 | 学籍状态 |
|
||||
|
||||
#### 响应数据
|
||||
返回Excel文件流
|
||||
|
||||
### 2.8.1 高级检索导出学生信息
|
||||
- **接口路径**: POST `/studentMsg/studentMsg/advancedSearchExport`
|
||||
- **权限标识**: `studentMsg:studentMsg:export`
|
||||
- **功能描述**: 根据高级检索条件导出学生信息列表，支持多维度复合查询条件
|
||||
- **版本**: 1.2.1 (2025-01-07修复MapStruct转换错误)
|
||||
- **修复**: 解决 `XgStudentMsgVo` 到 `XgStudentMsgExportVo` 转换器缺失问题
|
||||
|
||||
#### 请求参数
|
||||
支持以下高级检索条件：
|
||||
|
||||
**基础信息检索**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| studentNo | string | 否 | 学号（模糊查询） |
|
||||
| name | string | 否 | 姓名（模糊查询） |
|
||||
| idCard | string | 否 | 身份证号（模糊查询） |
|
||||
| phone | string | 否 | 手机号码（模糊查询） |
|
||||
| email | string | 否 | 邮箱（模糊查询） |
|
||||
| gender | array | 否 | 性别数组：0-男，1-女 |
|
||||
| nationality | array | 否 | 民族数组 |
|
||||
| politicalStatus | array | 否 | 政治面貌数组 |
|
||||
| birthDateStart | string | 否 | 出生日期开始：yyyy-MM-dd |
|
||||
| birthDateEnd | string | 否 | 出生日期结束：yyyy-MM-dd |
|
||||
|
||||
**学籍信息检索**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| studentStatus | array | 否 | 学籍状态数组：1-在籍，2-休学，3-复学，4-退学，5-毕业 |
|
||||
| enrollmentYearStart | integer | 否 | 入学年份开始 |
|
||||
| enrollmentYearEnd | integer | 否 | 入学年份结束 |
|
||||
| admissionCategory | array | 否 | 录取类别数组 |
|
||||
|
||||
**学院专业班级检索**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| collegeName | string | 否 | 学院名称（模糊查询） |
|
||||
| majorName | string | 否 | 专业名称（模糊查询） |
|
||||
| className | string | 否 | 班级名称（模糊查询） |
|
||||
| grade | array | 否 | 年级数组 |
|
||||
| counselorName | string | 否 | 辅导员姓名（模糊查询） |
|
||||
| classTeacherName | string | 否 | 班主任姓名（模糊查询） |
|
||||
|
||||
**家庭信息检索**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| fatherName | string | 否 | 父亲姓名（模糊查询） |
|
||||
| motherName | string | 否 | 母亲姓名（模糊查询） |
|
||||
| familyEconomicStatus | array | 否 | 家庭经济状况数组 |
|
||||
| familyIncomeMin | number | 否 | 家庭收入最小值 |
|
||||
| familyIncomeMax | number | 否 | 家庭收入最大值 |
|
||||
|
||||
**特殊身份检索**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| isPoorStudent | array | 否 | 是否贫困生：0-否，1-是 |
|
||||
| isMinority | array | 否 | 是否少数民族：0-否，1-是 |
|
||||
| isDisabled | array | 否 | 是否残疾：0-否，1-是 |
|
||||
| isOrphan | array | 否 | 是否孤儿：0-否，1-是 |
|
||||
|
||||
**权限范围**
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| deptIds | array | 否 | 部门ID数组，用于权限控制 |
|
||||
|
||||
#### 响应数据
|
||||
返回Excel文件流，包含完整的学生信息数据
|
||||
|
||||
#### 修复记录
|
||||
- **2025-01-07 v1.2.1**: 修复MapStruct转换错误，解决 `XgStudentMsgVo` 到 `XgStudentMsgExportVo` 转换器缺失问题
|
||||
- **问题**: `MapstructUtils.convert()` 无法找到两个VO类之间的转换器，导致导出功能报错
|
||||
- **解决**: 在Controller中添加手动转换方法 `convertToExportVo()` 和 `convertToExportVoList()`
|
||||
- **影响**: 导出功能正常工作，所有字段完整映射
|
||||
- **2025-01-07 v1.2.0**: 修复分页限制问题，导出时pageSize设置为50000，确保能导出所有符合条件的记录
|
||||
- **问题**: 之前由于BO类默认pageSize=10，导致只能导出10条记录
|
||||
- **解决**: 取消注释Controller中的分页参数设置代码
|
||||
|
||||
### 2.9 查询学生个人信息
|
||||
- **接口路径**: GET `/studentMsg/studentMsg/personalInfo`
|
||||
- **权限标识**: `studentMsg:studentMsg:query`
|
||||
- **功能描述**: 查询当前登录学生的个人信息
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| userId | long | 否 | 用户ID，为空时使用当前登录用户ID |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1",
|
||||
"createTime": "2025-01-27 10:00:00",
|
||||
"updateTime": "2025-01-27 10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.10 根据班级ID查询学生信息列表
|
||||
- **接口路径**: GET `/studentMsg/studentMsg/listByClassId`
|
||||
- **权限标识**: `studentMsg:studentMsg:query`
|
||||
- **功能描述**: 查询指定班级中所有在籍学生信息
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| classId | string | 是 | 班级ID |
|
||||
| name | string | 否 | 学生姓名（模糊查询） |
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"studentNo": "2023001001",
|
||||
"name": "张三",
|
||||
"gender": "0",
|
||||
"birthDate": "2000-01-01",
|
||||
"idCard": "110101199901010001",
|
||||
"phone": "13800138000",
|
||||
"email": "zhangsan@example.com",
|
||||
"classId": "101",
|
||||
"className": "计算机2023-1班",
|
||||
"majorId": "CS001",
|
||||
"majorName": "计算机科学与技术",
|
||||
"collegeId": "CS",
|
||||
"collegeName": "计算机学院",
|
||||
"studentStatus": "1",
|
||||
"createTime": "2025-01-27 10:00:00",
|
||||
"updateTime": "2025-01-27 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.11 导入学生信息数据
|
||||
- **接口路径**: POST `/studentMsg/studentMsg/importData`
|
||||
- **权限标识**: `studentMsg:studentMsg:import`
|
||||
- **功能描述**: 批量导入学生信息数据，支持Excel文件上传
|
||||
|
||||
#### 请求参数
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| file | MultipartFile | 是 | Excel文件（.xlsx格式） |
|
||||
| updateSupport | boolean | 否 | 是否支持更新已存在数据，默认false |
|
||||
|
||||
#### 请求示例
|
||||
```http
|
||||
POST /studentMsg/studentMsg/importData
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: [Excel文件]
|
||||
updateSupport: true
|
||||
```
|
||||
|
||||
#### 响应数据
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "恭喜您，数据已全部导入成功！共 10 条，数据如下：",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应示例
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"msg": "很抱歉，导入失败！共 2 条数据格式不正确，错误如下：<br/>1、学号 2023001001 已存在<br/>2、学号 2023001002 导入失败：手机号码格式不正确",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 2.12 获取导入模板
|
||||
- **接口路径**: POST `/studentMsg/studentMsg/importTemplate`
|
||||
- **权限标识**: `studentMsg:studentMsg:import`
|
||||
- **功能描述**: 下载学生信息导入模板文件
|
||||
|
||||
#### 请求参数
|
||||
无
|
||||
|
||||
#### 响应数据
|
||||
返回Excel模板文件（.xlsx格式）
|
||||
|
||||
#### 模板字段说明
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| 学号 | string | 是 | 学生学号，必须唯一 |
|
||||
| 姓名 | string | 是 | 学生姓名 |
|
||||
| 性别 | string | 是 | 0-男，1-女 |
|
||||
| 身份证号 | string | 否 | 身份证号码 |
|
||||
| 手机号码 | string | 否 | 手机号码，必须唯一 |
|
||||
| 电子邮箱 | string | 否 | 邮箱地址，必须唯一 |
|
||||
| 出生日期 | date | 否 | 出生日期 |
|
||||
| 民族 | string | 否 | 民族代码 |
|
||||
| 政治面貌 | string | 否 | 政治面貌代码 |
|
||||
| 家庭地址 | string | 否 | 家庭住址 |
|
||||
| 现住址 | string | 否 | 现居住地址 |
|
||||
| 班级ID | string | 否 | 班级编号 |
|
||||
| 班级名称 | string | 否 | 班级名称 |
|
||||
| 专业ID | string | 否 | 专业编号 |
|
||||
| 专业名称 | string | 否 | 专业名称 |
|
||||
| 学院ID | string | 否 | 学院编号 |
|
||||
| 学院名称 | string | 否 | 学院名称 |
|
||||
| 学籍状态 | string | 否 | 1-在籍，2-休学，3-复学，4-退学，5-毕业 |
|
||||
|
||||
## 3. 数据字典
|
||||
|
||||
### 3.1 性别字典
|
||||
| 字典值 | 字典标签 |
|
||||
|--------|----------|
|
||||
| 0 | 男 |
|
||||
| 1 | 女 |
|
||||
|
||||
### 3.2 学籍状态字典
|
||||
| 字典值 | 字典标签 |
|
||||
|--------|----------|
|
||||
| 1 | 在籍 |
|
||||
| 2 | 休学 |
|
||||
| 3 | 复学 |
|
||||
| 4 | 退学 |
|
||||
| 5 | 毕业 |
|
||||
|
||||
### 3.3 信息状态字典
|
||||
| 字典值 | 字典标签 |
|
||||
|--------|----------|
|
||||
| 1 | 正常 |
|
||||
| 2 | 待审核 |
|
||||
| 3 | 审核中 |
|
||||
| 4 | 已驳回 |
|
||||
| 5 | 已锁定 |
|
||||
|
||||
## 4. 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 操作成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 无权限 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 5. 权限说明
|
||||
|
||||
### 5.1 数据权限控制
|
||||
- **超级管理员**: 可查看所有学生信息
|
||||
- **学工管理员**: 可查看所有学生信息
|
||||
- **二级学院管理员**: 只能查看本学院学生信息
|
||||
- **辅导员**: 只能查看负责班级的学生信息
|
||||
- **班主任**: 只能查看负责班级的学生信息
|
||||
- **学生**: 只能查看自己的信息
|
||||
|
||||
### 5.2 操作权限控制
|
||||
- **新增**: 学工管理员、二级学院管理员
|
||||
- **修改**: 学工管理员、二级学院管理员、辅导员、班主任（限制范围）
|
||||
- **删除**: 学工管理员、二级学院管理员
|
||||
- **导入**: 学工管理员、二级学院管理员
|
||||
- **导出**: 学工管理员、二级学院管理员、辅导员、班主任
|
||||
- **查询**: 所有有权限的用户
|
||||
|
||||
## 6. 注意事项
|
||||
|
||||
1. 所有接口都需要Bearer Token认证
|
||||
2. 删除操作为逻辑删除，不会物理删除数据
|
||||
3. 学号和身份证号必须唯一
|
||||
4. 新增学生时会自动创建对应的系统用户账号
|
||||
5. 支持多租户数据隔离
|
||||
6. 所有时间字段使用yyyy-MM-dd HH:mm:ss格式
|
||||
7. 数据权限按照用户角色自动过滤
|
||||
8. 班级学生查询接口只返回在籍状态的学生
|
||||
|
||||
## 7. 更新日志
|
||||
|
||||
### 2025-01-27 - 新增学生信息导入功能
|
||||
- **新增功能**: 新增学生信息批量导入功能
|
||||
- **新增接口**:
|
||||
- `POST /studentMsg/studentMsg/importData` - 学生信息导入接口
|
||||
- `POST /studentMsg/studentMsg/importTemplate` - 导入模板下载接口
|
||||
- **功能特性**:
|
||||
- 支持Excel文件批量导入
|
||||
- 支持新增和更新两种模式
|
||||
- 自动验证学号、手机号、邮箱唯一性
|
||||
- 完整的错误处理和结果统计
|
||||
- 自动创建对应的系统用户账号
|
||||
- **技术实现**:
|
||||
- 使用自定义Listener处理Excel解析
|
||||
- 事务保证数据一致性
|
||||
- 详细的导入结果反馈
|
||||
|
||||
### 2025-01-27 - 新增班级学生查询接口
|
||||
- **新增功能**: 新增 `GET /studentMsg/studentMsg/listByClassId` 接口
|
||||
- **功能描述**: 查询指定班级中所有在籍学生信息
|
||||
- **过滤条件**:
|
||||
- `deleted = 0` (未删除)
|
||||
- `student_status = '1'` (在籍状态)
|
||||
- `class_id = 入参的classId` (班级ID)
|
||||
- `name LIKE '%入参的name%'` (姓名模糊查询，可选)
|
||||
- **排序方式**: 按创建时间倒序排列
|
||||
|
||||
## 17. 获取学生信息树 ⭐ 新增
|
||||
|
||||
### 接口描述
|
||||
获取按年级、学院、专业、班级层级组织的学生信息树结构，用于宿舍分配等场景的学生选择。
|
||||
|
||||
### 接口URL
|
||||
```
|
||||
GET /studentMsg/studentMsg/getStudentTree
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
| 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
|
||||
|-------|------|---------|------|-------|
|
||||
| secondaryCollegeId | Long | 否 | 二级学院ID，默认为101 | 101 |
|
||||
|
||||
### 请求示例
|
||||
```javascript
|
||||
// GET请求
|
||||
/studentMsg/studentMsg/getStudentTree?secondaryCollegeId=101
|
||||
```
|
||||
|
||||
### 响应参数
|
||||
| 参数名 | 类型 | 说明 | 示例值 |
|
||||
|-------|------|------|-------|
|
||||
| code | Integer | 响应码，200表示成功 | 200 |
|
||||
| msg | String | 响应消息 | "操作成功" |
|
||||
| data | Array | 学生信息树数据 | 见下方详细结构 |
|
||||
|
||||
### 学生树节点结构
|
||||
| 参数名 | 类型 | 说明 | 示例值 |
|
||||
|-------|------|------|-------|
|
||||
| id | String | 节点唯一标识 | "college-101" |
|
||||
| label | String | 节点显示名称 | "计算机学院" |
|
||||
| type | String | 节点类型：college/major/class | "college" |
|
||||
| maleAssigned | Integer | 已分配男生数量 | 45 |
|
||||
| maleTotal | Integer | 男生总数 | 120 |
|
||||
| femaleAssigned | Integer | 已分配女生数量 | 25 |
|
||||
| femaleTotal | Integer | 女生总数 | 60 |
|
||||
| grade | String | 年级信息（仅班级节点有值） | "2025" |
|
||||
| collegeId | Long | 学院ID | 101 |
|
||||
| collegeName | String | 学院名称 | "计算机学院" |
|
||||
| majorId | Long | 专业ID（专业和班级节点有值） | 1001 |
|
||||
| majorName | String | 专业名称（专业和班级节点有值） | "计算机科学与技术" |
|
||||
| classId | Long | 班级ID（仅班级节点有值） | 10001 |
|
||||
| className | String | 班级名称（仅班级节点有值） | "计算机科学与技术1班" |
|
||||
| sortOrder | Integer | 排序序号 | 1 |
|
||||
| children | Array | 子节点数组 | [] |
|
||||
|
||||
### 后端实现
|
||||
```java
|
||||
// Controller
|
||||
@GetMapping("/getStudentTree")
|
||||
@SaCheckPermission("studentMsg:studentMsg:query")
|
||||
public R<List<XgStudentTreeVo>> getStudentTree(@RequestParam(defaultValue = "101") Long secondaryCollegeId) {
|
||||
List<XgStudentTreeVo> tree = studentService.getStudentTree(secondaryCollegeId);
|
||||
return R.ok(tree);
|
||||
}
|
||||
|
||||
// Service实现
|
||||
@Override
|
||||
public List<XgStudentTreeVo> getStudentTree(Long secondaryCollegeId) {
|
||||
return baseMapper.getStudentTree(secondaryCollegeId);
|
||||
}
|
||||
```
|
||||
|
||||
### 数据库查询
|
||||
```sql
|
||||
<select id="getCollegeStudentStats" resultType="java.util.Map">
|
||||
SELECT
|
||||
s.college_id,
|
||||
s.college_name,
|
||||
s.major_id,
|
||||
s.major_name,
|
||||
s.class_id,
|
||||
s.class_name,
|
||||
s.grade,
|
||||
COUNT(CASE WHEN s.gender = '1' THEN 1 END) as male_total,
|
||||
COUNT(CASE WHEN s.gender = '0' THEN 1 END) as female_total,
|
||||
COUNT(CASE WHEN s.gender = '1' AND s.is_boarder = 1 THEN 1 END) as male_assigned,
|
||||
COUNT(CASE WHEN s.gender = '0' AND s.is_boarder = 1 THEN 1 END) as female_assigned
|
||||
FROM xg_student s
|
||||
WHERE s.secondary_college_id = #{secondaryCollegeId}
|
||||
AND s.deleted = 0
|
||||
AND s.student_status = '1'
|
||||
GROUP BY s.college_id, s.college_name, s.major_id, s.major_name, s.class_id, s.class_name, s.grade
|
||||
ORDER BY s.college_id, s.major_id, s.class_id
|
||||
</select>
|
||||
```
|
||||
|
||||
### 前端调用
|
||||
```typescript
|
||||
// API定义
|
||||
export function getStudentTree(secondaryCollegeId: number = 101): AxiosPromise<R<XgStudentTreeVO[]>> {
|
||||
return request({
|
||||
url: '/studentMsg/studentMsg/getStudentTree',
|
||||
method: 'get',
|
||||
params: {
|
||||
secondaryCollegeId
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 组件中使用
|
||||
const getStudentTreeData = async () => {
|
||||
try {
|
||||
const res = await getStudentTree(101);
|
||||
if (res.data.code === 200) {
|
||||
studentTreeData.value = res.data.data || [];
|
||||
} else {
|
||||
ElMessage.error(res.data.msg || '获取学生信息树失败');
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('获取学生信息树失败:', error);
|
||||
ElMessage.error('获取学生信息树失败');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"id": "college-101",
|
||||
"label": "计算机学院",
|
||||
"type": "college",
|
||||
"collegeId": 101,
|
||||
"collegeName": "计算机学院",
|
||||
"maleAssigned": 45,
|
||||
"maleTotal": 120,
|
||||
"femaleAssigned": 25,
|
||||
"femaleTotal": 60,
|
||||
"children": [
|
||||
{
|
||||
"id": "major-1001",
|
||||
"label": "计算机科学与技术",
|
||||
"type": "major",
|
||||
"collegeId": 101,
|
||||
"collegeName": "计算机学院",
|
||||
"majorId": 1001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"maleAssigned": 45,
|
||||
"maleTotal": 80,
|
||||
"femaleAssigned": 15,
|
||||
"femaleTotal": 40,
|
||||
"children": [
|
||||
{
|
||||
"id": "class-10001",
|
||||
"label": "计算机科学与技术1班",
|
||||
"type": "class",
|
||||
"collegeId": 101,
|
||||
"collegeName": "计算机学院",
|
||||
"majorId": 1001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classId": 10001,
|
||||
"className": "计算机科学与技术1班",
|
||||
"grade": "2025",
|
||||
"maleAssigned": 20,
|
||||
"maleTotal": 40,
|
||||
"femaleAssigned": 10,
|
||||
"femaleTotal": 20
|
||||
},
|
||||
{
|
||||
"id": "class-10002",
|
||||
"label": "计算机科学与技术2班",
|
||||
"type": "class",
|
||||
"collegeId": 101,
|
||||
"collegeName": "计算机学院",
|
||||
"majorId": 1001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classId": 10002,
|
||||
"className": "计算机科学与技术2班",
|
||||
"grade": "2025",
|
||||
"maleAssigned": 25,
|
||||
"maleTotal": 40,
|
||||
"femaleAssigned": 5,
|
||||
"femaleTotal": 20
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"msg": "获取学生信息树失败",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
1. **权限控制**: 需要 `studentMsg:studentMsg:query` 权限
|
||||
2. **树结构**: 按学院->专业->班级的层级组织（移除年级分组）
|
||||
3. **统计信息**: 每个节点包含已分配和总数的男女生统计信息
|
||||
4. **排序规则**: 按学院ID、专业ID、班级ID顺序排列
|
||||
5. **应用场景**: 主要用于宿舍分配时显示各班级的入住统计
|
||||
6. **数据过滤**: 支持按二级学院过滤数据范围，默认为101
|
||||
7. **逻辑删除**: 查询时排除已删除的学生记录
|
||||
8. **学籍状态**: 只统计在籍学生（student_status='1'）
|
||||
9. **住宿统计逻辑**:
|
||||
- **total**: 需要住宿的学生总数（is_boarder=1）
|
||||
- **assigned**: 实际已分配住宿的学生数（通过xg_dorm_bed_student表关联，status='0'）
|
||||
|
||||
---
|
||||
|
||||
## 📋 更新日志
|
||||
|
||||
### 2025-01-27 - 学生信息树接口优化
|
||||
- **功能优化**: 优化 `GET /studentMsg/studentMsg/getStudentTree` 接口
|
||||
- **结构调整**: 移除年级分组，调整为学院->专业->班级的三级层级结构
|
||||
- **性能优化**: 减少嵌套层级，提升前端渲染性能
|
||||
- **统计信息**: 保持各层级男女生人数和住宿分配统计
|
||||
- **逻辑修正**: 修正住宿统计逻辑，通过xg_dorm_bed_student表准确统计已分配住宿学生数
|
||||
|
||||
### 2025-01-27 - 新增班级学生查询接口
|
||||
- **新增功能**: 新增 `GET /studentMsg/studentMsg/listByClassId` 接口
|
||||
- **功能描述**: 查询指定班级中所有在籍学生信息
|
||||
- **过滤条件**: 支持按班级ID和学生姓名查询
|
||||
- **排序方式**: 按创建时间倒序排列
|
||||
|
||||
---
|
||||
|
||||
**文档更新时间**: 2025-01-27
|
||||
**文档版本**: 1.4.0
|
||||
**维护人员**: Cursor AI
|
||||
**更新说明**:
|
||||
- 优化学生信息树接口，移除年级分组，简化层级结构
|
||||
- 新增学生信息树查询接口，支持宿舍分配场景
|
||||
- 新增高级检索导出接口文档
|
||||
- 修复高级检索导出分页限制问题
|
||||
- 之前版本：新增学生信息导入功能，完善学生信息管理API文档
|
||||
@@ -210,6 +210,7 @@
|
||||
- `phone`：手机号
|
||||
- `sex`：性别
|
||||
- `className`：班级名称
|
||||
- `classStatus`：班级状态（字典 `xg_class_status`，常用值：`0`-停用、`1`-在读）
|
||||
- **返回示例**：
|
||||
```json
|
||||
{
|
||||
@@ -220,7 +221,8 @@
|
||||
"name": "张三",
|
||||
"phone": "13800001111",
|
||||
"sex": "0",
|
||||
"className": "2025级1班"
|
||||
"className": "2025级1班",
|
||||
"classStatus": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -228,6 +230,49 @@
|
||||
- **说明**：
|
||||
- 仅返回当前“正在教学”的班主任（班级状态为1，未删除，班主任ID有效，用户状态正常）。
|
||||
- 支持姓名和手机号的模糊查询，均为可选参数。
|
||||
- `classStatus` 字段便于前端字典渲染班级状态标签。
|
||||
|
||||
## 获取全部班主任信息（按班级状态排序）
|
||||
|
||||
- **接口路径**：`/xgStudentManager/studentManager/listAllClassTeachers`
|
||||
- **请求方式**：GET
|
||||
- **权限标识**：`xgStudentManager:studentManager:list`
|
||||
- **入参**：
|
||||
- `phone`（可选，string）：手机号，模糊查询
|
||||
- `name`（可选，string）：姓名，模糊查询
|
||||
- **出参**：
|
||||
- `name`：姓名
|
||||
- `phone`：手机号
|
||||
- `sex`：性别
|
||||
- `className`：班级名称
|
||||
- `classStatus`：班级状态（字典 `xg_class_status`，常用值：`0`-停用、`1`-在读等）
|
||||
- **返回示例**：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"name": "李老师",
|
||||
"phone": "13800002222",
|
||||
"sex": "1",
|
||||
"className": "2025级2班",
|
||||
"classStatus": "0"
|
||||
},
|
||||
{
|
||||
"name": "张老师",
|
||||
"phone": "13800003333",
|
||||
"sex": "0",
|
||||
"className": "2025级1班",
|
||||
"classStatus": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- **说明**：
|
||||
- 返回所有班主任关联的班级信息，不再限定班级状态。
|
||||
- 默认按照 `class_status` 升序、`class_name` 升序排序，便于前端分组展示。
|
||||
- 同样支持姓名和手机号的模糊查询。
|
||||
|
||||
## 4. 数据结构说明
|
||||
|
||||
|
||||
@@ -1,338 +0,0 @@
|
||||
# 班级信息管理API文档
|
||||
|
||||
## 基本信息
|
||||
|
||||
- **模块名称**: 班级信息管理
|
||||
- **接口前缀**: /classMsg
|
||||
- **权限前缀**: classMsg:classMsg:
|
||||
|
||||
## API接口列表
|
||||
|
||||
### 1. 班级信息查询接口
|
||||
|
||||
#### 1.1 获取班级信息列表
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg/list`
|
||||
- **请求方式**: GET
|
||||
- **权限标识**: `classMsg:classMsg:list`
|
||||
- **请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||||
| -------- | ------ | -------- | ---------- |
|
||||
| pageNum | int | 是 | 页码 |
|
||||
| pageSize | int | 是 | 每页条数 |
|
||||
| collegeId| int | 否 | 学院ID |
|
||||
| majorId | int | 否 | 专业ID |
|
||||
| className| string | 否 | 班级名称 |
|
||||
| classType| int | 否 | 班级类型 |
|
||||
| grade | string | 否 | 年级 |
|
||||
| classStatus| int | 否 | 班级状态 |
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"collegeId": 1001,
|
||||
"collegeName": "信息学院",
|
||||
"majorId": 2001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classCode": "CS2025-01",
|
||||
"className": "计科2025-01班",
|
||||
"classType": 1,
|
||||
"grade": "2025",
|
||||
"enrollmentYear": 2025,
|
||||
"graduationYear": 2029,
|
||||
"counselorId": 102,
|
||||
"counselorName": "李老师",
|
||||
"classTeacherId": 103,
|
||||
"classTeacherName": "张老师",
|
||||
"classStatus": 1,
|
||||
"remark": "示例班级"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.2 获取班级信息详情
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg/{id}`
|
||||
- **请求方式**: GET
|
||||
- **权限标识**: `classMsg:classMsg:query`
|
||||
- **请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||||
| ------ | ---- | -------- | ------- |
|
||||
| id | int | 是 | 班级ID |
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"collegeId": 1001,
|
||||
"collegeName": "信息学院",
|
||||
"majorId": 2001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classCode": "CS2025-01",
|
||||
"className": "计科2025-01班",
|
||||
"classType": 1,
|
||||
"grade": "2025",
|
||||
"enrollmentYear": 2025,
|
||||
"graduationYear": 2029,
|
||||
"counselorId": 102,
|
||||
"counselorName": "李老师",
|
||||
"classTeacherId": 103,
|
||||
"classTeacherName": "张老师",
|
||||
"classStatus": 1,
|
||||
"remark": "示例班级"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 获取当前登录人作为班主任的班级列表
|
||||
|
||||
- 接口URL: `/classMsg/classMsg/myClassListAsTeacher`
|
||||
- 请求方式: GET
|
||||
- 权限标识: `classMsg:classMsg:list`
|
||||
- 请求参数: 无
|
||||
- 返回参数:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"className": "计科2025-01班",
|
||||
"majorId": 2001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"grade": "2025",
|
||||
"classStatus": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 班级信息维护接口
|
||||
|
||||
#### 2.1 新增班级信息
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg`
|
||||
- **请求方式**: POST
|
||||
- **权限标识**: `classMsg:classMsg:add`
|
||||
- **请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"collegeId": 1001,
|
||||
"collegeName": "信息学院",
|
||||
"majorId": 2001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classCode": "CS2025-01",
|
||||
"className": "计科2025-01班",
|
||||
"classType": 1,
|
||||
"grade": "2025",
|
||||
"enrollmentYear": 2025,
|
||||
"graduationYear": 2029,
|
||||
"classStatus": 1,
|
||||
"remark": "示例班级"
|
||||
}
|
||||
```
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.2 修改班级信息
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg`
|
||||
- **请求方式**: PUT
|
||||
- **权限标识**: `classMsg:classMsg:edit`
|
||||
- **请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"collegeId": 1001,
|
||||
"collegeName": "信息学院",
|
||||
"majorId": 2001,
|
||||
"majorName": "计算机科学与技术",
|
||||
"classCode": "CS2025-01",
|
||||
"className": "计科2025-01班",
|
||||
"classType": 1,
|
||||
"grade": "2025",
|
||||
"enrollmentYear": 2025,
|
||||
"graduationYear": 2029,
|
||||
"classStatus": 1,
|
||||
"remark": "修改后的班级"
|
||||
}
|
||||
```
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.3 设置班主任
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg`
|
||||
- **请求方式**: PUT
|
||||
- **权限标识**: `classMsg:classMsg:edit`
|
||||
- **请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"classTeacherId": 103,
|
||||
"classTeacherName": "张老师"
|
||||
}
|
||||
```
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.4 设置辅导员
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg`
|
||||
- **请求方式**: PUT
|
||||
- **权限标识**: `classMsg:classMsg:edit`
|
||||
- **请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"counselorId": 102,
|
||||
"counselorName": "李老师"
|
||||
}
|
||||
```
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.5 删除班级信息
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg/{ids}`
|
||||
- **请求方式**: DELETE
|
||||
- **权限标识**: `classMsg:classMsg:remove`
|
||||
- **请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 是否必须 | 描述 |
|
||||
| ------ | ------ | -------- | ------------------ |
|
||||
| ids | string | 是 | 班级ID，多个用逗号分隔 |
|
||||
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.6 导出班级信息
|
||||
|
||||
- **接口URL**: `/classMsg/classMsg/export`
|
||||
- **请求方式**: GET
|
||||
- **权限标识**: `classMsg:classMsg:export`
|
||||
- **请求参数**: 与查询参数相同
|
||||
- **返回参数**: 文件流
|
||||
|
||||
### 3. 班级教师关联接口
|
||||
|
||||
#### 3.1 查询有效用户列表(用于班主任/辅导员选择)
|
||||
|
||||
- **接口URL**: `/xg/sysUser/activeList`
|
||||
- **请求方式**: GET
|
||||
- **权限标识**: `xg:sysUser:list`
|
||||
- **请求参数**: 无
|
||||
- **返回参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": [
|
||||
{
|
||||
"userId": 100,
|
||||
"userName": "teacher1",
|
||||
"nickName": "张老师",
|
||||
"email": "zhang@example.com",
|
||||
"phonenumber": "13800138000",
|
||||
"sex": "0",
|
||||
"status": "0",
|
||||
"deptId": 101,
|
||||
"deptName": "计算机系"
|
||||
},
|
||||
{
|
||||
"userId": 101,
|
||||
"userName": "teacher2",
|
||||
"nickName": "李老师",
|
||||
"email": "li@example.com",
|
||||
"phonenumber": "13800138001",
|
||||
"sex": "1",
|
||||
"status": "0",
|
||||
"deptId": 102,
|
||||
"deptName": "机械系"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 数据字典
|
||||
|
||||
### 班级类型(classType)
|
||||
|
||||
| 编码 | 名称 |
|
||||
| ---- | ---------- |
|
||||
| 1 | 中级工 |
|
||||
| 2 | 高级工 |
|
||||
| 3 | 预备技师 |
|
||||
| 4 | 技师 |
|
||||
| 5 | 中高职一体 |
|
||||
|
||||
### 班级状态(classStatus)
|
||||
|
||||
| 编码 | 名称 |
|
||||
| ---- | ---- |
|
||||
| 1 | 正常 |
|
||||
| 2 | 暂停 |
|
||||
| 3 | 毕业 |
|
||||
| 4 | 解散 |
|
||||
|
||||
### 是否已毕业(isGraduation)
|
||||
|
||||
| 编码 | 名称 |
|
||||
| ---- | ------ |
|
||||
| 0 | 未毕业 |
|
||||
| 1 | 已毕业 |
|
||||
@@ -1,415 +0,0 @@
|
||||
# 班级干部信息管理API文档
|
||||
|
||||
## 📋 文档信息
|
||||
|
||||
| 项目 | 信息 |
|
||||
|------|------|
|
||||
| **模块名称** | 班级干部信息管理 |
|
||||
| **模块代码** | ruoyi-xg |
|
||||
| **基础路径** | `/xgClassPosMsg/xgClassPosMsg` |
|
||||
| **权限前缀** | `xgClassPosMsg:xgClassPosMsg` |
|
||||
| **版本** | V1.0.0 |
|
||||
| **创建时间** | 2025-01-27 |
|
||||
| **更新时间** | 2025-01-27 |
|
||||
|
||||
## 🎯 API概述
|
||||
|
||||
### 模块说明
|
||||
班级干部信息管理模块提供完整的班级干部信息管理功能，包括班级干部的任命、任期管理、状态跟踪等全生命周期管理，以及用户角色关联功能。
|
||||
|
||||
### 技术规范
|
||||
- **认证方式**: Bearer Token (Sa-Token)
|
||||
- **数据格式**: JSON
|
||||
- **响应格式**: 统一使用R类型或TableDataInfo分页格式
|
||||
- **权限控制**: 基于角色的权限管理(RBAC)
|
||||
|
||||
### 核心特性
|
||||
- **基础管理**: 班级干部信息的增删改查、导入导出
|
||||
- **任期管理**: 任职日期、任期时长、到期提醒
|
||||
- **状态跟踪**: 在任、到期、辞职、免职、调任、休学等状态
|
||||
- **用户角色关联**: 自动建立学生与角色的关联关系
|
||||
- **数据权限**: 支持按部门查询班级干部信息
|
||||
|
||||
## 📊 数据模型
|
||||
|
||||
### 班级干部信息VO (XgClassPosMsgVo)
|
||||
|
||||
```java
|
||||
{
|
||||
"id": 1, // 主键ID（雪花ID）
|
||||
"deleted": 0, // 删除标志（0代表存在 1代表删除）
|
||||
"classId": 101, // 班级ID，关联xg_class_msg.id
|
||||
"className": "计算机2023-1班", // 班级名称（联表查询获取）
|
||||
"studentId": 1001, // 学生ID，关联xg_student_msg.id
|
||||
"studentNo": "2023001", // 学号
|
||||
"studentName": "张三", // 学生姓名（冗余字段）
|
||||
"positionCode": "monitor", // 职务编码，关联xg_class_pos_dict.position_code
|
||||
"positionName": "班长", // 职务名称（联表查询获取）
|
||||
"appointmentDate": "2024-09-01", // 任职日期
|
||||
"termStartDate": "2024-09-01", // 任期开始日期
|
||||
"termEndDate": "2025-07-01", // 任期结束日期
|
||||
"termDuration": 10, // 任期时长（月）
|
||||
"isCurrent": 1, // 是否现任：0-否，1-是
|
||||
"cadreStatus": "1", // 学生职务任职状态：1-在任，2-到期，3-辞职，4-免职，5-调任，6-休学
|
||||
"appointmentReason": "综合表现优秀", // 任命原因
|
||||
"appointmentMethod": "appointment", // 学生职务任命方式：appointment-任命，election-选举，recommendation-推荐
|
||||
"dismissalDate": null, // 离任日期
|
||||
"dismissalReason": null, // 离任原因
|
||||
"remark": "备注信息", // 备注信息
|
||||
"createBy": 1, // 创建者
|
||||
"createTime": "2024-09-01 10:00:00", // 创建时间
|
||||
"updateBy": 1, // 更新者
|
||||
"updateTime": "2024-09-01 10:00:00" // 更新时间
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 API接口列表
|
||||
|
||||
### 1. 基础管理接口
|
||||
|
||||
#### 1.1 查询班级干部信息列表
|
||||
- **接口路径**: GET `/xgClassPosMsg/xgClassPosMsg/list`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:list`
|
||||
- **功能描述**: 分页查询班级干部信息列表，支持按部门查询
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| pageNum | integer | 否 | 页码，默认1 |
|
||||
| pageSize | integer | 否 | 每页大小，默认10 |
|
||||
| deptId | long | 否 | 部门ID，用于按部门查询班级干部信息 |
|
||||
| classId | long | 否 | 班级ID |
|
||||
| studentId | long | 否 | 学生ID |
|
||||
| studentNo | string | 否 | 学号（模糊查询） |
|
||||
| studentName | string | 否 | 学生姓名（模糊查询） |
|
||||
| positionCode | string | 否 | 职务编码 |
|
||||
| appointmentDate | string | 否 | 任职日期 |
|
||||
| termStartDate | string | 否 | 任期开始日期 |
|
||||
| termEndDate | string | 否 | 任期结束日期 |
|
||||
| termDuration | integer | 否 | 任期时长（月） |
|
||||
| isCurrent | integer | 否 | 是否现任：0-否，1-是 |
|
||||
| cadreStatus | string | 否 | 学生职务任职状态 |
|
||||
| appointmentReason | string | 否 | 任命原因 |
|
||||
| appointmentMethod | string | 否 | 学生职务任命方式 |
|
||||
| dismissalDate | string | 否 | 离任日期 |
|
||||
| dismissalReason | string | 否 | 离任原因 |
|
||||
|
||||
**响应数据**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"classId": 101,
|
||||
"className": "计算机2023-1班",
|
||||
"studentId": 1001,
|
||||
"studentNo": "2023001",
|
||||
"studentName": "张三",
|
||||
"positionCode": "monitor",
|
||||
"positionName": "班长",
|
||||
"appointmentDate": "2024-09-01",
|
||||
"termStartDate": "2024-09-01",
|
||||
"termEndDate": "2025-07-01",
|
||||
"termDuration": 10,
|
||||
"isCurrent": 1,
|
||||
"cadreStatus": "1",
|
||||
"appointmentReason": "综合表现优秀",
|
||||
"appointmentMethod": "appointment",
|
||||
"createTime": "2024-09-01 10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.2 获取班级干部信息详情
|
||||
- **接口路径**: GET `/xgClassPosMsg/xgClassPosMsg/{id}`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:query`
|
||||
- **功能描述**: 根据主键获取班级干部信息详细信息
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | long | 是 | 主键ID |
|
||||
|
||||
**响应数据**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"classId": 101,
|
||||
"className": "计算机2023-1班",
|
||||
"studentId": 1001,
|
||||
"studentNo": "2023001",
|
||||
"studentName": "张三",
|
||||
"positionCode": "monitor",
|
||||
"positionName": "班长",
|
||||
"appointmentDate": "2024-09-01",
|
||||
"termStartDate": "2024-09-01",
|
||||
"termEndDate": "2025-07-01",
|
||||
"termDuration": 10,
|
||||
"isCurrent": 1,
|
||||
"cadreStatus": "1",
|
||||
"appointmentReason": "综合表现优秀",
|
||||
"appointmentMethod": "appointment",
|
||||
"dismissalDate": null,
|
||||
"dismissalReason": null,
|
||||
"remark": "备注信息",
|
||||
"createTime": "2024-09-01 10:00:00",
|
||||
"updateTime": "2024-09-01 10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.3 新增班级干部信息
|
||||
- **接口路径**: POST `/xgClassPosMsg/xgClassPosMsg`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:add`
|
||||
- **功能描述**: 新增班级干部信息，同时自动建立用户角色关联
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"classId": 101,
|
||||
"studentId": 1001,
|
||||
"studentNo": "2023001",
|
||||
"studentName": "张三",
|
||||
"positionCode": "monitor",
|
||||
"appointmentDate": "2024-09-01",
|
||||
"termStartDate": "2024-09-01",
|
||||
"termEndDate": "2025-07-01",
|
||||
"termDuration": 10,
|
||||
"isCurrent": 1,
|
||||
"cadreStatus": "1",
|
||||
"appointmentReason": "综合表现优秀",
|
||||
"appointmentMethod": "appointment",
|
||||
"remark": "备注信息"
|
||||
}
|
||||
```
|
||||
|
||||
**响应数据**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "新增成功"
|
||||
}
|
||||
```
|
||||
|
||||
**重要说明**:
|
||||
- 新增班级干部信息时，系统会自动向 `sys_user_role` 表插入一条数据
|
||||
- `user_id` = 当前记录的 `studentId`
|
||||
- `role_id` = 当前记录的 `id`（班级干部信息ID）
|
||||
- 此操作在事务中进行，确保数据一致性
|
||||
|
||||
#### 1.4 修改班级干部信息
|
||||
- **接口路径**: PUT `/xgClassPosMsg/xgClassPosMsg`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:edit`
|
||||
- **功能描述**: 修改班级干部信息
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"classId": 101,
|
||||
"studentId": 1001,
|
||||
"studentNo": "2023001",
|
||||
"studentName": "张三",
|
||||
"positionCode": "monitor",
|
||||
"appointmentDate": "2024-09-01",
|
||||
"termStartDate": "2024-09-01",
|
||||
"termEndDate": "2025-07-01",
|
||||
"termDuration": 10,
|
||||
"isCurrent": 1,
|
||||
"cadreStatus": "1",
|
||||
"appointmentReason": "综合表现优秀",
|
||||
"appointmentMethod": "appointment",
|
||||
"remark": "修改后的备注信息"
|
||||
}
|
||||
```
|
||||
|
||||
**响应数据**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.5 删除班级干部信息
|
||||
- **接口路径**: DELETE `/xgClassPosMsg/xgClassPosMsg/{ids}`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:remove`
|
||||
- **功能描述**: 删除班级干部信息（支持批量删除），同时删除对应的用户角色关联
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| ids | string | 是 | 主键ID，多个用逗号分隔 |
|
||||
|
||||
**响应数据**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**重要说明**:
|
||||
- 删除班级干部信息时，系统会自动删除 `sys_user_role` 表中对应的角色关联
|
||||
- 删除操作会先清理关联数据，再删除主数据
|
||||
- 此操作在事务中进行，确保数据一致性
|
||||
|
||||
#### 1.6 导出班级干部信息
|
||||
- **接口路径**: POST `/xgClassPosMsg/xgClassPosMsg/export`
|
||||
- **权限标识**: `xgClassPosMsg:xgClassPosMsg:export`
|
||||
- **功能描述**: 导出班级干部信息列表
|
||||
|
||||
**请求参数**: 同列表查询参数
|
||||
|
||||
**响应数据**: Excel文件下载
|
||||
|
||||
## 🔐 用户角色关联功能
|
||||
|
||||
### 功能说明
|
||||
班级干部信息管理模块集成了用户角色关联功能，确保班级干部信息与系统权限管理的一致性。
|
||||
|
||||
### 关联规则
|
||||
1. **新增关联**: 新增班级干部信息时，自动建立用户角色关联
|
||||
- `sys_user_role.user_id` = `xg_class_pos_msg.student_id`
|
||||
- `sys_user_role.role_id` = `xg_class_pos_msg.id`
|
||||
|
||||
2. **删除关联**: 删除班级干部信息时，自动删除对应的用户角色关联
|
||||
- 根据 `role_id` 删除 `sys_user_role` 表中的记录
|
||||
|
||||
### 事务处理
|
||||
- 所有用户角色关联操作都在事务中进行
|
||||
- 关联操作失败不会影响主业务流程，但会记录警告日志
|
||||
- 使用 `@Transactional(rollbackFor = Exception.class)` 确保数据一致性
|
||||
|
||||
### 异常处理
|
||||
- 用户角色关联操作异常会被捕获并记录日志
|
||||
- 不会抛出异常影响主业务流程
|
||||
- 通过日志记录操作结果和异常信息
|
||||
|
||||
## 📝 数据字典
|
||||
|
||||
### 学生职务任职状态 (cadre_status)
|
||||
| 编码 | 名称 | 说明 |
|
||||
|------|------|------|
|
||||
| 1 | 在任 | 正常任职状态 |
|
||||
| 2 | 到期 | 任期已结束 |
|
||||
| 3 | 辞职 | 主动辞职 |
|
||||
| 4 | 免职 | 被免职 |
|
||||
| 5 | 调任 | 调任其他职务 |
|
||||
| 6 | 休学 | 因休学暂停职务 |
|
||||
|
||||
### 学生职务任命方式 (appointment_method)
|
||||
| 编码 | 名称 | 说明 |
|
||||
|------|------|------|
|
||||
| appointment | 任命 | 直接任命 |
|
||||
| election | 选举 | 通过选举产生 |
|
||||
| recommendation | 推荐 | 通过推荐产生 |
|
||||
|
||||
### 是否现任 (is_current)
|
||||
| 编码 | 名称 | 说明 |
|
||||
|------|------|------|
|
||||
| 0 | 否 | 非现任职务 |
|
||||
| 1 | 是 | 现任职务 |
|
||||
|
||||
## 🔒 权限说明
|
||||
|
||||
### 权限标识列表
|
||||
|
||||
| 权限标识 | 权限名称 | 说明 |
|
||||
|----------|----------|------|
|
||||
| xgClassPosMsg:xgClassPosMsg:list | 班级干部信息列表 | 查看班级干部信息列表 |
|
||||
| xgClassPosMsg:xgClassPosMsg:query | 班级干部信息查询 | 查询班级干部信息详情 |
|
||||
| xgClassPosMsg:xgClassPosMsg:add | 班级干部信息新增 | 新增班级干部信息 |
|
||||
| xgClassPosMsg:xgClassPosMsg:edit | 班级干部信息修改 | 修改班级干部信息 |
|
||||
| xgClassPosMsg:xgClassPosMsg:remove | 班级干部信息删除 | 删除班级干部信息 |
|
||||
| xgClassPosMsg:xgClassPosMsg:export | 班级干部信息导出 | 导出班级干部信息 |
|
||||
|
||||
### 数据权限
|
||||
- 支持按部门查询班级干部信息
|
||||
- 通过 `deptId` 参数控制数据权限范围
|
||||
- 自动包含子部门的数据
|
||||
|
||||
## 🚨 错误码说明
|
||||
|
||||
| 错误码 | 错误信息 | 说明 |
|
||||
|--------|----------|------|
|
||||
| 40001 | 学生不存在 | 指定的学生ID不存在 |
|
||||
| 40002 | 班级不存在 | 指定的班级ID不存在 |
|
||||
| 40003 | 职务不存在 | 指定的职务编码不存在 |
|
||||
| 40004 | 学生已担任该职务 | 学生已经担任该职务 |
|
||||
| 40005 | 班级干部记录不存在 | 指定的班级干部记录不存在 |
|
||||
| 40006 | 操作权限不足 | 当前用户没有操作权限 |
|
||||
| 40007 | 数据校验失败 | 提交的数据不符合规则 |
|
||||
| 40008 | 用户角色关联失败 | 用户角色关联操作失败 |
|
||||
|
||||
## 📋 使用示例
|
||||
|
||||
### 1. 查询班级干部信息
|
||||
```javascript
|
||||
// 查询指定部门的班级干部信息
|
||||
const response = await api.get('/xgClassPosMsg/xgClassPosMsg/list', {
|
||||
params: {
|
||||
deptId: 101,
|
||||
pageNum: 1,
|
||||
pageSize: 10
|
||||
}
|
||||
});
|
||||
console.log(response.data);
|
||||
```
|
||||
|
||||
### 2. 新增班级干部
|
||||
```javascript
|
||||
// 新增班级干部信息
|
||||
const addData = {
|
||||
classId: 101,
|
||||
studentId: 1001,
|
||||
studentNo: "2023001",
|
||||
studentName: "张三",
|
||||
positionCode: "monitor",
|
||||
appointmentDate: "2024-09-01",
|
||||
termStartDate: "2024-09-01",
|
||||
termEndDate: "2025-07-01",
|
||||
termDuration: 10,
|
||||
isCurrent: 1,
|
||||
cadreStatus: "1",
|
||||
appointmentReason: "综合表现优秀",
|
||||
appointmentMethod: "appointment"
|
||||
};
|
||||
const response = await api.post('/xgClassPosMsg/xgClassPosMsg', addData);
|
||||
```
|
||||
|
||||
### 3. 删除班级干部
|
||||
```javascript
|
||||
// 删除班级干部信息
|
||||
const response = await api.delete('/xgClassPosMsg/xgClassPosMsg/1,2,3');
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **数据一致性**: 班级干部信息与用户角色关联保持一致
|
||||
2. **权限控制**: 严格按照角色权限进行操作控制
|
||||
3. **事务管理**: 所有关联操作都在事务中进行
|
||||
4. **任期管理**: 注意任期时间的合理性和连续性
|
||||
5. **状态管理**: 正确维护班级干部的任职状态
|
||||
6. **并发控制**: 防止同时操作导致的数据冲突
|
||||
7. **日志记录**: 重要操作都会记录详细日志
|
||||
|
||||
## 📈 更新日志
|
||||
|
||||
| 版本 | 日期 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| V1.0.0 | 2025-01-27 | 初始版本，完整的班级干部信息管理API |
|
||||
| V1.0.1 | 2025-01-27 | 新增用户角色关联功能 |
|
||||
|
||||
---
|
||||
|
||||
**文档维护**: Cursor AI 辅助
|
||||
**最后更新**: 2025-01-27
|
||||
**文档状态**: 已完成
|
||||
Reference in new issue
Block a user