# 学生学籍异动与换班级API

## 模块说明

本文档用于说明学生学籍异动（退学、休学、复学、毕业）与换班级相关接口，重点包含“复学并换班级”事务化组合接口。

- 基础路径：`/studentMsg/studentStatusChange`
- 关联模块：`/studentMsg/studentClassChange`

## 1. 批量新增学籍异动

- 请求方式：`POST`
- 请求路径：`/studentMsg/studentStatusChange/batch`
- 功能描述：批量提交学籍异动记录（适用于退学、休学、毕业、普通复学）

## 2. 复学并换班级（事务化组合接口）

- 请求方式：`POST`
- 请求路径：`/studentMsg/studentStatusChange/resume-with-class-change`
- 功能描述：一次提交同时写入
  - 学籍异动表 1 条（`changeType=FU_XUE`）
  - 换班级表 1 条（新学院/新专业/新班级）
- 事务说明：任一写入失败则整体回滚，避免“只复学未换班”或“只换班未复学”的数据不一致

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| studentId | Long | 是 | 学生ID |
| studentNo | String | 是 | 学号 |
| studentName | String | 否 | 学生姓名 |
| originalCollegeId | Long | 否 | 原学院ID |
| originalCollegeName | String | 否 | 原学院名称 |
| originalMajorId | Long | 否 | 原专业ID |
| originalMajorName | String | 否 | 原专业名称 |
| originalClassId | Long | 否 | 原班级ID |
| originalClassName | String | 否 | 原班级名称 |
| newCollegeId | Long | 是 | 新学院ID |
| newCollegeName | String | 否 | 新学院名称 |
| newMajorId | Long | 是 | 新专业ID |
| newMajorName | String | 否 | 新专业名称 |
| newClassId | Long | 是 | 新班级ID |
| newClassName | String | 否 | 新班级名称 |
| effectiveDate | Date | 是 | 生效日期（复学与换班级共用） |
| reason | String | 是 | 原因（复学原因，同时写入换班级原因） |
| operatorId | Long | 否 | 经办人ID |
| operatorName | String | 否 | 经办人姓名 |

### 请求示例

```json
{
  "studentId": 197001010001,
  "studentNo": "20240001",
  "studentName": "张三",
  "originalCollegeId": 201,
  "originalCollegeName": "信息工程学院",
  "originalMajorId": 301,
  "originalMajorName": "软件技术",
  "originalClassId": 401,
  "originalClassName": "软技2401",
  "newCollegeId": 202,
  "newCollegeName": "智能制造学院",
  "newMajorId": 302,
  "newMajorName": "机电一体化技术",
  "newClassId": 402,
  "newClassName": "机电2402",
  "effectiveDate": "2026-03-13",
  "reason": "学生复学并调整到新班级",
  "operatorId": 100,
  "operatorName": "管理员"
}
```

### 响应说明

- 成功响应：`R<Void>`，`code=200`
- 失败响应：`R<Void>`，`code!=200`，并返回错误信息

## 3. 学生信息页批量换班级（前端）

- 入口：学生信息页「换班级」按钮（权限 `studentMsg:class:change`）
- 行为：勾选 1～N 名学生，共用同一目标学院/专业/班级/生效时间/原因
- 实现：前端串行多次调用 `POST /studentMsg/studentClassChange`，每人一条记录，`status=0`
- 后端：无新接口；班级实际变更仍由后台脚本 `学生换班级/process_student_class_change_fixed.sh` 处理
- 边界：已在目标班级的学生跳过并计入失败明细；部分失败不回滚已成功记录

## 更新记录

| 日期 | 更新内容 | 更新人 |
|---|---|---|
| 2026-09-15 | 补充学生信息页批量换班级说明 | Cursor |
| 2026-03-13 | 新增“复学并换班级”事务化组合接口文档 | Cursor |