# 管理员端班级管理接口 接口统一使用 `/class/admin` 前缀。所有请求都必须携带 `Authorization`,服务端会从 JWT 解析当前用户并校验 `phone_role.role_name=管理员`,不接受客户端传入管理员用户 ID。 部署新版服务前先执行 `src/main/resources/sql/class_management.sql`。脚本可重复执行,并会尽力 从旧等级、排课和班级成员数据回填新增字段;无法推断的旧记录在页面显示“信息待补全”。 ## 1. 班级卡片分页 `POST /class/admin/page` ```json { "pageNum": 1, "pageSize": 20, "keyword": "污水处理", "occupation": "污水", "trainingYear": 2026, "levelId": 1, "status": "ONGOING" } ``` - `pageNum` 默认 1;`pageSize` 默认 20、最大 100。 - `occupation` 只支持 `污水`、`污泥`。 - `status` 支持 `UPCOMING`、`ONGOING`、`ENDED`、`UNKNOWN`,不区分大小写。 - 返回项目统一的 `TableDataInfo`,每条记录包含 `levelId/levelName`、计划/实际人数和状态中文名。 班级状态不写入数据库:开始日前为待开课,起止日期内为进行中,结束日后为已结课;缺少日期的 旧数据为信息待补全。 ## 2. 班级导航树 `GET /class/admin/tree?keyword=污水` 返回 `OCCUPATION → YEAR → LEVEL → CLASS` 四层节点。分组节点的 `count` 为后代班级数, 班级节点返回 `classId` 和 `studentCount`。关键字只模糊匹配班级名称。 ## 3. 表单选项 `GET /class/admin/options` 返回: - `occupations`:污水、污泥。 - `years`:数据库已有年度,加当前年度及前两年,倒序排列。 - `levels`:`sys_level` 中未隐藏且名称以“污水”或“污泥”开头的等级。 - `headTeachers`:未删除且在 `phone_role` 中具有教师角色的用户,`extra` 为完整手机号。 ## 4. 新增班级 `POST /class/admin` ```json { "name": "污水处理一级三班", "occupation": "污水", "trainingYear": 2026, "levelId": 1, "startDate": "2026-09-01", "endDate": "2027-01-31", "headTeacherId": "1900000000000000001", "location": "实训基地A栋301教室", "capacity": 35, "remark": "采用理论与实训混合模式" } ``` 班级名称、工种、年度、等级和起止日期必填。同一培训年度内班级名称不能重复;计划人数选填, 填写时必须为 1~200;班主任选填,但有值时必须是有效教师。成功后返回完整班级详情。 ## 5. 编辑班级 `PUT /class/admin/{id}` 请求体与新增相同。编辑只更新班级基础信息,不删除或重建已有学员、排课、考试关系;计划人数 有值时不得小于当前实际学员数。清空班主任、地点、计划人数或备注时传 `null` 或空字符串。 班级基础资料允许在`UPCOMING`(待开课)和`ONGOING`(进行中)状态编辑;`ENDED` (已结课)班级保持只读。 ## 6. 班级详情 `GET /class/admin/{id}` 详情包含: - 基础信息、计划/实际人数、培训自然日数和动态班级状态。 - 按课程名称、类型和授课教师聚合的课程列表,课时为全部排课课时之和。 - 聚合课程在最后一节排课的具体结束时刻到达后立即更新为 `ENDED / 已完成`。 - 全班及个人出勤率;只有 `NORMAL/LATE` 计入出勤分子,`ABSENT/LEAVE` 计入分母。 - 最近一场 `exam.mark_flag=true` 的考试,以及考生侧 `mark_flag=true` 的正式成绩。 - 最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回 `null`。 - 学员名单返回姓名、手机号、所属班级、身份证号、单位名称、备注、账户状态、出勤和理论/实训成绩; 人员类别、所在单位和学历字段继续保留以兼容旧页面及导出。 - 学员状态优先采用账户真实状态;只有旧数据缺少账户状态时才按班级日期回退展示。 - `graduationEligible=true` 表示最近已发布的理论和实训成绩都存在,且两者平均分不低于 60。 - `selectable=false` 表示学员已经结业或归档,前端应禁止再次勾选办理结业。 百分比字段以 `0~100` 的数值返回并最多保留两位小数,空值由页面展示为“—”。 班级详情页的课程维护直接复用课程管理接口:查询、新增、Word导入、导出、按上午/下午调课和单节编辑 分别见`course-management-api.md`,提交的`classId`均取当前详情班级。 ### 学员字段示例 ```json { "relationId": 1801, "userId": "1900000000000000101", "name": "张三", "phone": "13800000000", "classId": 101, "className": "污水五级补考", "idCard": "310225198004075411", "companyName": "市第一污水处理厂", "remark": "", "personTypes": ["在职", "从业"], "personTypeName": "在职、从业", "workUnit": "市第一污水处理厂", "highestEducation": "本科", "attendanceRate": 92.5, "theoryScore": 78.0, "practicalScore": 82.0, "averageScore": 80.0, "graduationEligible": true, "accountStatus": "STUDYING", "accountStatusName": "在读", "learningStatus": "ACTIVE", "learningStatusName": "在读", "selectable": true } ``` ## 7. 学员详情与编辑 ### 7.1 查询当前班级学员详情 `GET /class/admin/{classId}/students/{userId}` 接口会同时校验班级和成员关系。学员已被其他管理员转班或移除时返回业务错误,不会泄露其他 班级资料。响应字段与班级详情中的单条 `students` 完全一致。编辑弹窗按图片依次绑定 `name`、`phone`、`classId/className`、`accountStatus`、`idCard`、`companyName`、`remark`。 ### 7.2 编辑名单资料 `PUT /class/admin/{classId}/students/{userId}` ```json { "name": "张三", "phone": "13800000000", "targetClassId": 101, "accountStatus": "PENDING", "idCard": "310225198004075411", "companyName": "市第一污水处理厂", "remark": "补考班学员" } ``` 图片字段与接口字段映射: | 弹窗字段 | 请求字段 | 校验与行为 | |---|---|---| | 姓名 | `name` | 必填,最多100字符 | | 手机号 | `phone` | 必填,1开头的11位数字,全系统不可重复 | | 所属班级 | `targetClassId` | 选当前班不变;选其他班复用正式转班流程 | | 账户状态 | `accountStatus` | `PENDING/STUDYING/GRADUATED/ARCHIVED`,遵循状态机 | | 身份证号 | `idCard` | 选填,15位或18位,末位允许X,全系统不可重复 | | 单位名称 | `companyName` | 选填,最多255字符 | | 备注 | `remark` | 选填,最多1000字符 | 状态下拉展示:`PENDING=待激活`、`STUDYING=在读`、`GRADUATED=已结业`、 `ARCHIVED=已归档`。状态只能按“待激活 → 在读 → 已结业 → 已归档”方向变化;结业和归档如需 完整办理证书、通知等业务,前端仍应优先使用专用结业/归档操作。 所属班级下拉的当前选中项直接使用详情返回的 `classId/className`;其余可选项调用第8节接口。 如果目标班级改变,保存时会清理原班级未开始的考试名册、写入转班日志并迁移班级关系;接口 响应中的 `classId/className` 已是新班级,前端保存成功后应关闭弹窗并刷新原班级详情和目录树。 旧字段 `personTypes/workUnit/highestEducation` 仍可提交;新弹窗未提交这些字段时后端保留原值, 不会因弹窗改版清空历史资料。 - 姓名、手机号必填;手机号必须是以 `1` 开头的 11 位数字且全系统唯一。 - 人员类别最多 10 项,单项最长 32 个字符;空数组表示清空。 - 编辑手机号会同步更新登录账号和 `phone_role` 的“学员”角色映射。 - 本接口不能修改出勤率或考试成绩;账户状态和班级关系分别通过既有状态机及转班流程修改。 ## 8. 转班目标选项 `GET /class/admin/{classId}/students/transfer-options` ```json [ { "value": "21", "label": "2026 污水一级 2 班", "parentValue": "ONGOING", "extra": "污水一级" } ] ``` 只返回待开课或进行中班级,并排除当前班。`value` 是提交转班接口所需的目标班级 ID;前端 不得把班级名称作为 ID 提交。弹窗每次打开时重新请求选项,避免使用已结课的缓存班级。 ## 9. 移除学员 `POST /class/admin/{classId}/students/remove` ```json { "studentIds": ["1900000000000000101", "1900000000000000102"] } ``` 成功响应: ```json { "affectedCount": 2 } ``` - 单人和批量使用同一接口,ID 自动去重,单次最多 500 人。 - 仅删除当前有效的 `class_student` 关系,账号、已答试卷、成绩和出勤记录保留。 - 尚未开始且没有作答、提交和正式成绩的后续考试占位名单会同步清理。 - 服务端先锁定全部成员关系;任一学员已不在本班时整个请求回滚。 ## 10. 转班 `POST /class/admin/{classId}/students/transfer` ```json { "studentIds": ["1900000000000000101", "1900000000000000102"], "targetClassId": 21 } ``` 成功响应结构与移除接口一致。源班解绑、目标班绑定、未来考试名单清理和历史记录写入在同一事务 完成。目标班不能是当前班,也不能是已结课或信息不完整班级。转回历史班级时,原班考试成绩 仍保留;新班不会继承原班成绩。 ## 11. 结业办理 `POST /class/admin/{classId}/students/graduation` ```json { "studentIds": ["1900000000000000101", "1900000000000000102"], "graduationDate": "2026-11-05", "batchNo": "2026年第4批", "remark": "完成规定课程与考核", "mode": "PASSED_ONLY", "issueCertificate": true, "notifyStudent": true } ``` `mode`: - `ALL`:把所选待激活/在读学员全部结业,不受成绩限制。 - `PASSED_ONLY`:只结业 `graduationEligible=true` 的学员,其他人员返回跳过原因。 响应示例: ```json { "graduatedCount": 1, "skippedCount": 1, "graduatedStudentIds": ["1900000000000000101"], "skippedStudents": [ { "studentId": "1900000000000000102", "name": "李四", "reason": "理论或实训成绩未达标" } ] } ``` 结业成功后账户状态更新为 `GRADUATED`,学员仍保留在名单中,但 `selectable=false`。勾选发证 时生成独立电子结业证书编号;勾选通知时只给实际成功结业的学员发送站内消息。 ## 12. 导出学员名单 `POST /class/admin/{classId}/students/export` 导出全班: ```json { "scope": "ALL" } ``` 导出勾选学员: ```json { "scope": "SELECTED", "studentIds": ["1900000000000000101"] } ``` 响应为 `text/csv;charset=UTF-8` 文件流,文件自带 UTF-8 BOM。CSV 包含班级信息、导出范围、 导出时间及“序号/姓名/手机号/人员类别/所在单位/学历”六列;逗号、换行和双引号均已转义。 前端应从 `Content-Disposition` 的 `filename*` 读取文件名。交互规则为:有勾选时提交 `SELECTED`,无勾选时提交 `ALL`。 ## 13. 前端联调流程 1. 打开班级详情时调用 `GET /class/admin/{id}`,将 `students` 渲染到“学员名单”Tab。 2. 全选仅选择 `selectable=true` 的行,并维护半选状态;选中数大于 0 时启用批量按钮。 3. 点击编辑先调用第7.1节接口回显;班级下拉用当前班级加第8节返回项,保存提交第7.2节接口。 如果响应 `classId` 与原班级不同,刷新原班级详情和左侧树;否则可直接替换当前行。 4. 打开转班弹窗时调用第 8 节接口,提交成功后重新获取班级详情和左侧班级树。 5. 移除成功后重新获取详情和树,不在前端自行推算班级人数。 6. 结业弹窗用名单中的理论/实训分和 `graduationEligible` 展示达标摘要;提交后按响应展示跳过项, 然后刷新详情。 7. 下载文件时必须按二进制处理,不要把CSV响应交给统一JSON响应拦截器。 所有JSON接口使用项目统一 `Result` 包装;业务失败由统一异常处理器返回中文 `msg`。发生失败时 前端保留当前选择,展示 `msg` 并重新拉取详情,以处理其他管理员并发修改关系的情况。 ## 14. 常见业务错误 | 场景 | 服务端提示 | 前端处理 | |---|---|---| | 未选择学员 | 请至少选择一名学员 | 不发请求并高亮选择区 | | 超过批量上限 | 单次批量操作不能超过500名学员 | 拆分选择或减少人数 | | 成员并发变化 | 部分学员已不在当前班级,请刷新后重试 | 刷新详情并清空失效选择 | | 转入当前班 | 目标班级不能是当前班级 | 保持弹窗并重新选择 | | 转入已结课班 | 目标班级必须是待开课或进行中状态 | 刷新目标班选项 | | 手机号重复 | 手机号已被其他账户使用 | 保持编辑弹窗并定位手机号 | | 身份证号格式错误 | 身份证号需为15位或18位有效格式 | 保持编辑弹窗并定位身份证号 | | 身份证号重复 | 身份证号已被其他账户使用 | 保持编辑弹窗并定位身份证号 | | 状态逆向修改 | 学员状态只能按待激活→在读→已结业→已归档方向变更 | 恢复原状态并提示 | | 重复结业 | 当前账户状态不支持结业 | 在结果明细中展示跳过原因 | ## 15. 数据库部署 部署应用前执行 `sql/class_management.sql`。新增表: - `class_student_change_log`:保存移除/转班历史,不影响当前班级权限判断。 - `student_graduation_record`:保存班级维度结业批次、说明、证书和通知请求。 脚本使用 `create table if not exists`,可重复执行;所有建表语句均不指定字符集或排序规则,沿用 目标数据库默认配置。上线顺序为:备份数据库 → 执行脚本 → 部署后端 → 前端联调验证。