学生信息收集批次管理API文档

📋 文档信息

项目	信息
项目名称	校园管理系统 - 学生信息收集批次管理
API模块	学生信息收集批次班级权限管理
文档版本	V1.0.0
创建时间	2025-01-27
基础路径	`/stuColBatchClass/stuColBatchClass`

🎯 API概述

模块说明

学生信息收集批次管理系统提供完整的批次权限配置、批次查询、权限范围管理等API接口，支持按班级权限控制学生信息收集范围。

技术规范

认证方式: Bearer Token (Sa-Token)
数据格式: JSON
响应格式: 统一使用R类型或TableDataInfo分页格式
权限控制: 基于角色的权限管理(RBAC)

权限角色

学生管理员: 查看权限范围内的批次信息
班主任: 查看所带班级的批次信息
全校学生管理员: 查看全校范围的批次信息
系统管理员: 完整的批次权限配置管理

📊 数据模型

批次信息VO (XgStuColBatchVo)

{
  "id": 1,                           // 批次ID
  "batchName": "2025年春季学期信息收集", // 批次名称
  "description": "收集学生基本信息",    // 批次描述
  "startTime": "2025-02-01 00:00:00", // 开始时间
  "endTime": "2025-02-28 23:59:59",   // 结束时间
  "status": "0",                      // 状态（0正常 1停用）
  "collectionType": "1",              // 收集类型（1-新学期收集 2-其他）
  "remark": "备注信息",                // 备注
  "createBy": 1,                      // 创建者
  "createTime": "2025-01-27 10:00:00", // 创建时间
  "updateBy": 1,                      // 更新者
  "updateTime": "2025-01-27 10:00:00"  // 更新时间
}

批次班级权限VO (XgStuColBatchClassVo)

{
  "id": 1,                    // 主键ID
  "batchId": 1,               // 批次ID
  "classId": 101,             // 班级ID
  "className": "计算机2023-1", // 班级名称
  "majorId": 10,              // 专业ID
  "majorName": "计算机科学与技术", // 专业名称
  "collegeId": 1,             // 院系ID
  "collegeName": "计算机学院",  // 院系名称
  "remark": "备注",           // 备注
  "deleted": 0,               // 删除标志
  "createBy": 1,              // 创建者
  "createTime": "2025-01-27 10:00:00", // 创建时间
  "updateBy": 1,              // 更新者
  "updateTime": "2025-01-27 10:00:00"  // 更新时间
}

🔧 API接口列表

1. 基础管理接口

1.1 查询批次班级权限列表

接口路径: GET /stuColBatchClass/stuColBatchClass/list
权限标识: stuColBatchClass:stuColBatchClass:list
功能描述: 分页查询学生信息收集批次班级权限列表

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | integer | 否 | 页码，默认1 | | pageSize | integer | 否 | 每页大小，默认10 | | batchId | long | 否 | 批次ID | | classId | long | 否 | 班级ID | | className | string | 否 | 班级名称（模糊查询） | | majorName | string | 否 | 专业名称（模糊查询） | | collegeName | string | 否 | 院系名称（模糊查询） |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "batchId": 1,
      "classId": 101,
      "className": "计算机2023-1",
      "majorId": 10,
      "majorName": "计算机科学与技术",
      "collegeId": 1,
      "collegeName": "计算机学院"
    }
  ],
  "total": 1
}

1.2 获取批次班级权限详细信息

接口路径: GET /stuColBatchClass/stuColBatchClass/{id}
权限标识: stuColBatchClass:stuColBatchClass:query
功能描述: 根据主键获取批次班级权限详细信息

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | long | 是 | 主键ID |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "batchId": 1,
    "classId": 101,
    "className": "计算机2023-1",
    "majorId": 10,
    "majorName": "计算机科学与技术",
    "collegeId": 1,
    "collegeName": "计算机学院",
    "remark": "备注",
    "deleted": 0
  }
}

1.3 新增批次班级权限

接口路径: POST /stuColBatchClass/stuColBatchClass
权限标识: stuColBatchClass:stuColBatchClass:add
功能描述: 新增学生信息收集批次班级权限

请求参数:

{
  "batchId": 1,
  "classId": 101,
  "className": "计算机2023-1",
  "majorId": 10,
  "majorName": "计算机科学与技术",
  "collegeId": 1,
  "collegeName": "计算机学院",
  "remark": "备注"
}

响应数据:

{
  "code": 200,
  "msg": "新增成功"
}

1.4 修改批次班级权限

接口路径: PUT /stuColBatchClass/stuColBatchClass
权限标识: stuColBatchClass:stuColBatchClass:edit
功能描述: 修改学生信息收集批次班级权限

请求参数:

{
  "id": 1,
  "batchId": 1,
  "classId": 101,
  "className": "计算机2023-1",
  "majorId": 10,
  "majorName": "计算机科学与技术",
  "collegeId": 1,
  "collegeName": "计算机学院",
  "remark": "修改后的备注"
}

响应数据:

{
  "code": 200,
  "msg": "修改成功"
}

1.5 删除批次班级权限

接口路径: DELETE /stuColBatchClass/stuColBatchClass/{ids}
权限标识: stuColBatchClass:stuColBatchClass:remove
功能描述: 删除学生信息收集批次班级权限（支持批量删除）

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | ids | string | 是 | 主键ID，多个用逗号分隔 |

响应数据:

{
  "code": 200,
  "msg": "删除成功"
}

1.6 导出批次班级权限

接口路径: POST /stuColBatchClass/stuColBatchClass/export
权限标识: stuColBatchClass:stuColBatchClass:export
功能描述: 导出学生信息收集批次班级权限列表

请求参数:

{
  "batchId": 1,
  "classId": 101,
  "className": "计算机",
  "majorName": "计算机科学",
  "collegeName": "计算机学院"
}

响应数据:

直接返回Excel文件流

2. 权限范围管理接口

2.1 获取批次收集范围

接口路径: GET /stuColBatchClass/stuColBatchClass/getScope/{batchId}
权限标识: stuColBatchClass:stuColBatchClass:query
功能描述: 获取指定批次配置的班级权限范围

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchId | long | 是 | 批次ID |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": [101, 102, 103]  // 班级ID列表
}

2.2 获取批次权限范围详情

接口路径: GET /stuColBatchClass/stuColBatchClass/getScopeDetail/{batchId}
权限标识: stuColBatchClass:stuColBatchClass:query
功能描述: 获取批次配置的权限范围详细信息

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchId | long | 是 | 批次ID |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "batchId": 1,
      "classId": 101,
      "className": "计算机2023-1",
      "majorId": 10,
      "majorName": "计算机科学与技术",
      "collegeId": 1,
      "collegeName": "计算机学院"
    }
  ]
}

2.3 设置批次收集范围

接口路径: POST /stuColBatchClass/stuColBatchClass/setScope
权限标识: stuColBatchClass:stuColBatchClass:setScope
功能描述: 设置学生信息收集批次班级权限范围

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchId | long | 是 | 批次ID | | deptIds | array | 是 | 授权的班级ID列表 |

响应数据:

{
  "code": 200,
  "msg": "权限设置成功，共设置 3 个班级权限"
}

3. 用户相关接口

3.1 查询学生可参与的批次

接口路径: GET /stuColBatchClass/stuColBatchClass/getStudentAvailableBatches
权限标识: 无需权限（基于当前登录用户）
功能描述: 查询当前登录学生可参与的批次信息

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchName | string | 否 | 批次名称（模糊查询） |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "batchId": 1,
      "batchName": "2025年春季学期信息收集",
      "description": "收集学生基本信息",
      "startTime": "2025-02-01 00:00:00",
      "endTime": "2025-02-28 23:59:59",
      "status": "0",
      "collectionType": "1",
      "remark": "备注信息",
      "classId": 101,
      "className": "计算机2023-1",
      "majorId": 10,
      "majorName": "计算机科学与技术",
      "collegeId": 1,
      "collegeName": "计算机学院"
    }
  ]
}

3.2 查询老师关联的批次信息 🆕

接口路径: GET /stuColBatchClass/stuColBatchClass/getTeacherRelatedBatches
权限标识: stuColBatchClass:stuColBatchClass:query
功能描述: 查询当前登录老师有权限管理的批次信息

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchName | string | 否 | 批次名称（模糊查询） |

业务逻辑:

调用 XgStudentManagerSourceServiceImpl.getCurrentUserAuthDeptTree() 获取当前用户有权限的部门树
递归提取所有部门ID
根据部门ID查询关联的批次信息
支持全校学生管理员、普通管理员、班主任三种权限模式

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "batchName": "2025年春季学期信息收集",
      "description": "收集学生基本信息",
      "startTime": "2025-02-01 00:00:00",
      "endTime": "2025-02-28 23:59:59",
      "status": "0",
      "collectionType": "1",
      "remark": "备注信息",
      "createBy": 1,
      "createTime": "2025-01-27 10:00:00",
      "updateBy": 1,
      "updateTime": "2025-01-27 10:00:00"
    }
  ]
}

3.3 获取批次组织权限范围 🆕

接口路径: GET /stuColBatchClass/stuColBatchClass/getBatchAuthScope/{batchId}
权限标识: stuColBatchClass:stuColBatchClass:query
功能描述: 获取用户对应该批次的组织权限范围，返回过滤后的组织树形结构

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | batchId | long | 是 | 批次ID |

业务逻辑:

获取用户权限: 调用 XgStudentManagerSourceServiceImpl.getCurrentUserAuthDeptTree() 获取当前用户所有的组织权限信息
查询批次班级: 通过batchId在 xg_stu_col_batch_class 中获取class_id数据（过滤条件：deleted=0）
过滤组织树: 将第一步获取的树形数据中，非第二步中存在的班级节点都剔除，只保留在第二步中存在的班级ID以及其上级节点，直到树形数据的顶点

核心算法:

使用递归算法实现树形结构过滤
保留目标班级节点及其所有上级节点
确保组织层级关系的完整性

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "label": "计算机学院",
      "parentId": 101,
      "deptCategory": "college",
      "weight": 1,
      "disabled": false,
      "children": [
        {
          "id": 10,
          "label": "计算机科学与技术",
          "parentId": 1,
          "deptCategory": "major",
          "weight": 1,
          "disabled": false,
          "children": [
            {
              "id": 101,
              "label": "计算机2023-1班",
              "parentId": 10,
              "deptCategory": "class",
              "weight": 1,
              "disabled": false,
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

异常情况:

当批次ID无效时返回空列表
当用户无权限时返回空列表
当批次未配置班级权限时返回空列表

应用场景:

前端组织树选择器的数据源
批次权限范围可视化显示
权限验证和范围限制

🔐 权限设计

权限控制策略

1. 全校学生管理员

权限范围: 可以查看和管理所有批次信息
识别条件: xg_student_manager 表中 manager_type = '1'
部门权限: 获取 dept_id = 101 下所有部门数据

2. 普通管理员

权限范围: 基于 xg_student_manager_source 表中的授权范围
识别条件: xg_student_manager 表中 manager_type != '1'
部门权限: 根据授权的部门ID获取相关部门树

3. 班主任

权限范围: 只能查看所带班级的批次信息
识别条件: xg_class_msg 表中 class_teacher_id 等于当前用户ID
自动权限: 系统自动将班主任权限合并到部门权限中

数据查询策略

权限范围计算

-- 1. 查询用户授权的部门ID
SELECT auth_source FROM xg_student_manager_source 
WHERE manager_id IN (
  SELECT id FROM xg_student_manager WHERE user_id = #{currentUserId}
) AND status = '0' AND deleted = '0'

-- 2. 查询班主任权限
SELECT id FROM xg_class_msg 
WHERE class_teacher_id = #{currentUserId} AND deleted = '0'

-- 3. 查询批次信息
SELECT DISTINCT b.* FROM xg_stu_col_batch b
INNER JOIN xg_stu_col_batch_class bc ON b.id = bc.batch_id 
WHERE bc.class_id IN (权限范围内的部门ID)
AND b.deleted = 0 AND b.status = '0'

📝 使用示例

前端调用示例

JavaScript/Vue示例

// 查询老师关联的批次信息
async function getTeacherBatches(batchName = '') {
  try {
    const response = await request({
      url: '/stuColBatchClass/stuColBatchClass/getTeacherRelatedBatches',
      method: 'get',
      params: {
        batchName: batchName
      }
    });
    
    if (response.code === 200) {
      console.log('批次列表:', response.data);
      return response.data;
    } else {
      console.error('查询失败:', response.msg);
      return [];
    }
  } catch (error) {
    console.error('请求异常:', error);
    return [];
  }
}

// 设置批次权限范围
async function setBatchScope(batchId, deptIds) {
  try {
    const response = await request({
      url: '/stuColBatchClass/stuColBatchClass/setScope',
      method: 'post',
      data: {
        batchId: batchId,
        deptIds: deptIds
      }
    });
    
    if (response.code === 200) {
      console.log('权限设置成功:', response.msg);
      return true;
    } else {
      console.error('设置失败:', response.msg);
      return false;
    }
  } catch (error) {
    console.error('请求异常:', error);
    return false;
  }
}

移动端调用示例

uni-app示例

// 查询学生可参与的批次
async function getStudentBatches() {
  try {
    const response = await uni.request({
      url: baseURL + '/stuColBatchClass/stuColBatchClass/getStudentAvailableBatches',
      method: 'GET',
      header: {
        'Authorization': 'Bearer ' + getToken(),
        'Content-Type': 'application/json'
      }
    });
    
    if (response.data.code === 200) {
      return response.data.data;
    } else {
      uni.showToast({
        title: response.data.msg || '查询失败',
        icon: 'none'
      });
      return [];
    }
  } catch (error) {
    console.error('请求异常:', error);
    uni.showToast({
      title: '网络异常',
      icon: 'none'
    });
    return [];
  }
}

⚠️ 注意事项

数据安全

权限验证: 所有接口都进行严格的权限验证
数据过滤: 用户只能查看权限范围内的数据
SQL注入防护: 使用参数绑定防止SQL注入

性能优化

查询优化: 使用索引优化大数据量查询
缓存策略: 部门权限树适合进行缓存
分页查询: 大列表数据支持分页

错误处理

参数验证: 对所有输入参数进行验证
异常捕获: 完善的异常处理机制
友好提示: 提供用户友好的错误信息

📈 版本更新记录

V1.0.0 (2025-01-27)

🆕 新增 getTeacherRelatedBatches 接口
🔧 修复 XgStuColBatchVo 缺少基础字段的问题
📝 完善API文档和使用示例
🔐 完善权限控制策略
✨ 支持全校管理员、普通管理员、班主任三种权限模式

学生信息收集批次管理API.md 16 KB 文件历史 原始文件

学生信息收集批次管理API文档

📋 文档信息

🎯 API概述

模块说明

技术规范

权限角色

📊 数据模型

批次信息VO (XgStuColBatchVo)

批次班级权限VO (XgStuColBatchClassVo)

🔧 API接口列表

1. 基础管理接口

1.1 查询批次班级权限列表

1.2 获取批次班级权限详细信息

1.3 新增批次班级权限

1.4 修改批次班级权限

1.5 删除批次班级权限

1.6 导出批次班级权限

2. 权限范围管理接口

2.1 获取批次收集范围

2.2 获取批次权限范围详情

2.3 设置批次收集范围

3. 用户相关接口

3.1 查询学生可参与的批次

3.2 查询老师关联的批次信息 🆕

3.3 获取批次组织权限范围 🆕

🔐 权限设计

权限控制策略

1. 全校学生管理员

2. 普通管理员

3. 班主任

数据查询策略

权限范围计算

📝 使用示例

前端调用示例

JavaScript/Vue示例

移动端调用示例

uni-app示例

⚠️ 注意事项

数据安全

性能优化

错误处理

📈 版本更新记录

V1.0.0 (2025-01-27)

学生信息收集批次管理API.md 16 KB

文件历史原始文件