docs: 新增批量学生换班级设计说明

确认采用前端循环现有单条接口方案，供后续实现计划引用。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 16:48:12 +08:00
1 parent 66d8769020
commit 33e207e466
@@ -0,0 +1,135 @@
+# 批量学生换班级 — 设计说明
+
+**日期**: 2026-09-15  
+**状态**: 已确认  
+**范围**: 学生信息页「换班级」支持多人批量提交  
+**方案**: A — 前端循环调用现有单条接口
+
+---
+
+## 1. 背景与目标
+
+### 现状
+
+- 页面：`web` → `/student/studentmsg/studentMsg`（学生信息）
+- 「换班级」按钮当前仅支持选中 **1** 名学生（`ids.length !== 1` 时拦截）
+- 提交后调用 `POST /studentMsg/studentClassChange`，写入一条 `xg_student_class_change` 记录，`status='0'`
+- **无审批流程**；后台脚本 `学生换班级/process_student_class_change_fixed.sh` 扫描未处理记录，更新学生班级并将 `status` 置为 `'1'`
+
+### 目标
+
+- 支持勾选多名学生，一次操作换到 **同一目标班级**
+- 每人一条异动记录，走与单人完全相同的后续处理链路
+- 不改后端接口、表结构、后台处理脚本
+
+### 非目标
+
+- 不引入 Warm-Flow / 审批
+- 不新增批量 API
+- 不在前端/接口层立即更新 `xg_student_msg` 班级字段（仍由后台脚本执行）
+- 不做「每人不同目标班级」
+
+---
+
+## 2. 需求确认摘要
+
+| 项 | 结论 |
+|----|------|
+| 目标班级 | 多人共用同一套：新学院 / 新专业 / 新班级 / 生效时间 / 原因 |
+| 原班级约束 | 不限制，任意原班级可一起选 |
+| 生效方式 | 与现在一致：只写 `status=0` 记录，由后台脚本处理 |
+| 实现方式 | 前端串行循环现有单条接口 |
+
+---
+
+## 3. 整体流程
+
+```
+勾选 N 名学生 → 点击「换班级」
+  → 弹窗：学生列表 + 共用目标班级表单
+  → 确定后，对每人依次 POST /studentMsg/studentClassChange
+  → 提示成功/失败汇总
+  → 现有后台脚本照常处理 status=0 记录
+```
+
+---
+
+## 4. UI 与交互
+
+### 4.1 按钮
+
+- 权限：`studentMsg:class:change`（不变）
+- 启用条件：至少勾选 1 人（去掉「只能选 1 人」限制）
+
+### 4.2 弹窗
+
+- 标题：
+  - 1 人：`换班级申请`
+  - 多人：`批量换班级（N 人）`
+- **上半区**：学生表格（学号、姓名、原学院、原专业、原班级），可滚动
+- **下半区**：共用目标表单（新学院 / 新专业 / 新班级 / 生效时间 / 换班级原因），字段与校验与现单人一致
+
+### 4.3 提交反馈
+
+- 提交中禁用「确定」，可显示进度（如 `3/10`）
+- 结束后汇总：`成功 X 人`；失败则列出学号 + 原因
+- **全部成功**：关闭弹窗并刷新列表
+- **存在失败**：保留弹窗并展示失败明细
+
+---
+
+## 5. 校验与错误处理
+
+### 5.1 提交前
+
+- 表单必填：新学院、新专业、新班级、生效时间、原因
+- 若某人当前 `classId` 已等于目标 `newClassId`：该人跳过，记入失败明细「已在目标班级」，其余人继续
+- 不校验「是否已有未处理换班级申请」（与现单人行为一致）
+
+### 5.2 提交中
+
+- 串行调用现有接口（避免并发压力）
+- 每人 payload：该生原学院/专业/班级信息 + 共用新班级信息；`changeType='1'`，`status='0'`
+- 单人接口失败不中断整批；记录后继续下一人
+- 不回滚已成功写入的记录（方案 A 无服务端事务）
+
+### 5.3 边界
+
+- 暂不设人数硬上限（后续如需可加，例如 100）
+
+---
+
+## 6. 改动范围
+
+### 改
+
+| 位置 | 内容 |
+|------|------|
+| `web/src/views/xg/xsjcxx/studentMsg/studentMsg/index.vue` | 按钮禁用逻辑、`openChangeClassModal`、弹窗结构、`submitChangeClass` 批量循环与结果汇总 |
+
+### 不改
+
+- 后端 `XgStudentClassChangeController` / Service / 表结构
+- `学生换班级/process_student_class_change_fixed.sh`
+- `web/src/views/xg/xsjcxx/studentClassChange/index.vue`（记录列表页）
+
+### 文档同步
+
+- 在 `docs/开发文档/API/学生学籍异动与换班级API.md`（或业务模块文档）补充说明：学生信息页支持批量换班级，前端循环写入多条记录，处理链路不变
+
+---
+
+## 7. 测试要点
+
+1. 选 1 人：与现行为一致，写出 1 条 `status=0`
+2. 选多人、不同原班级：写出 N 条，目标班级字段相同
+3. 含「已在目标班」的学生：该人跳过，其他人成功
+4. 模拟单人接口失败：其余仍提交，弹窗保留并显示失败明细
+5. 后台脚本执行后：成功记录变 `status=1`，对应学生班级信息更新
+
+---
+
+## 8. 风险与说明
+
+- **部分成功**：方案 A 无整批事务；失败明细需清晰展示，由操作人决定是否对失败学生重试
+- **与「审批」的关系**：设计文档中曾有「未处理/已处理」状态字段，实际无人工审批；「处理」指后台脚本执行。本需求不改变该模型