|
|
@@ -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 无整批事务；失败明细需清晰展示，由操作人决定是否对失败学生重试
|
|
|
+- **与「审批」的关系**：设计文档中曾有「未处理/已处理」状态字段，实际无人工审批；「处理」指后台脚本执行。本需求不改变该模型
|
