all-project/docs/开发文档/API/学生信息收集批次API.md

学生信息收集批次API文档

📋 文档信息

项目	信息
项目名称	校园管理系统 - 学生信息收集批次
API模块	学生信息收集批次管理
文档版本	V1.1.0
创建时间	2025-01-03
基础路径	/XgStuColBatch/stuColBatch

🎯 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"  // 更新时间
}

🔧 API接口列表

1. 基础管理接口

1.1 查询学生信息收集批次列表

• 接口路径: GET /XgStuColBatch/stuColBatch/list
• 权限标识: XgStuColBatch:stuColBatch:list
• 功能描述: 分页查询学生信息收集批次列表
• 排序方式: 按创建时间倒序排列（最新创建的批次在前）

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | integer | 否 | 页码，默认1 | | pageSize | integer | 否 | 每页大小，默认10 | | batchName | string | 否 | 批次名称（模糊查询） | | status | string | 否 | 状态（0正常 1停用） | | collectionType | string | 否 | 收集类型（1-新学期收集 2-其他） |

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 2,
      "batchName": "2025年春季学期信息收集",
      "description": "收集学生基本信息",
      "startTime": "2025-02-01 00:00:00",
      "endTime": "2025-02-28 23:59:59",
      "status": "0",
      "collectionType": "1",
      "createTime": "2025-01-27 15:30:00"
    },
    {
      "id": 1,
      "batchName": "2024年秋季学期信息收集",
      "description": "收集学生基本信息",
      "startTime": "2024-09-01 00:00:00",
      "endTime": "2024-09-30 23:59:59",
      "status": "1",
      "collectionType": "1",
      "createTime": "2024-08-15 10:00:00"
    }
  ],
  "total": 2
}

1.2 获取学生信息收集批次详细信息

• 接口路径: GET /XgStuColBatch/stuColBatch/{id}
• 权限标识: XgStuColBatch:stuColBatch:query
• 功能描述: 根据主键获取学生信息收集批次详细信息

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | long | 是 | 批次主键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"
  }
}

1.3 新增学生信息收集批次

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

请求参数:

{
  "batchName": "2025年春季学期信息收集",
  "description": "收集学生基本信息",
  "startTime": "2025-02-01 00:00:00",
  "endTime": "2025-02-28 23:59:59",
  "status": "0",
  "collectionType": "1",
  "remark": "备注信息"
}

响应数据:

{
  "code": 200,
  "msg": "操作成功"
}

1.4 修改学生信息收集批次

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

请求参数:

{
  "id": 1,
  "batchName": "2025年春季学期信息收集",
  "description": "收集学生基本信息",
  "startTime": "2025-02-01 00:00:00",
  "endTime": "2025-02-28 23:59:59",
  "status": "0",
  "collectionType": "1",
  "remark": "备注信息"
}

响应数据:

{
  "code": 200,
  "msg": "操作成功"
}

1.5 删除学生信息收集批次

• 接口路径: DELETE /XgStuColBatch/stuColBatch/{ids}
• 权限标识: XgStuColBatch:stuColBatch:remove
• 功能描述: 批量删除学生信息收集批次

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

响应数据:

{
  "code": 200,
  "msg": "操作成功"
}

1.6 导出学生信息收集批次

• 接口路径: POST /XgStuColBatch/stuColBatch/export
• 权限标识: XgStuColBatch:stuColBatch:export
• 功能描述: 导出学生信息收集批次列表到Excel

请求参数: 同查询列表接口，用于筛选导出数据。

响应数据: 返回Excel文件流。

📝 更新历史

日期	版本	更新内容	更新人
2025-01-03	V1.1.0	重要更新：修改列表接口排序方式，从按ID升序改为按创建时间倒序，确保最新创建的批次显示在前面	系统管理员
2025-01-27	V1.0.0	初始版本，创建学生信息收集批次管理API文档	系统管理员

🚨 重要说明

排序变更说明

• 变更时间: 2025-01-03
• 变更内容: 列表查询接口的排序方式从按ID升序(orderByAsc(XgStuColBatch::getId))改为按创建时间倒序(orderByDesc(XgStuColBatch::getCreateTime))
• 变更原因: 提升用户体验，确保最新创建的批次显示在列表前面，便于用户快速找到最近的批次
• 影响范围: 仅影响列表查询接口的数据排序，不影响其他功能

技术实现

• 后端实现: 修改XgStuColBatchServiceImpl.buildQueryWrapper()方法中的排序逻辑
• 数据库字段: 使用create_time字段进行排序
• 继承关系: XgStuColBatch → TenantEntity → BaseEntity（createTime字段在BaseEntity中定义）