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

## 📋 文档信息

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

## 🎯 API概述

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

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

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

## 📊 数据模型

### 批次信息VO (XgStuColBatchVo)

```java
{
  "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)

```java
{
  "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 | 否 | 院系名称（模糊查询） |

**响应数据**:
```json
{
  "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 |

**响应数据**:
```json
{
  "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`
- **功能描述**: 新增学生信息收集批次班级权限

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

**响应数据**:
```json
{
  "code": 200,
  "msg": "新增成功"
}
```

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

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

**响应数据**:
```json
{
  "code": 200,
  "msg": "修改成功"
}
```

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

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

**响应数据**:
```json
{
  "code": 200,
  "msg": "删除成功"
}
```

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

**请求参数**:
```json
{
  "batchId": 1,
  "classId": 101,
  "className": "计算机",
  "majorName": "计算机科学",
  "collegeName": "计算机学院"
}
```

**响应数据**:
- 直接返回Excel文件流

### 2. 权限范围管理接口

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

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

**响应数据**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [101, 102, 103]  // 班级ID列表
}
```

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

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

**响应数据**:
```json
{
  "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列表 |

**响应数据**:
```json
{
  "code": 200,
  "msg": "权限设置成功，共设置 3 个班级权限"
}
```

### 3. 用户相关接口

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

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

**响应数据**:
```json
{
  "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 | 否 | 批次名称（模糊查询） |

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

**响应数据**:
```json
{
  "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 |

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

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

**响应数据**:
```json
{
  "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
- **自动权限**: 系统自动将班主任权限合并到部门权限中

### 数据查询策略

#### 权限范围计算
```sql
-- 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示例
```javascript
// 查询老师关联的批次信息
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示例
```javascript
// 查询学生可参与的批次
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 [];
  }
}
```

## ⚠️ 注意事项

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

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

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

## 📈 版本更新记录

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