# 管理员端班级管理接口 接口统一使用 `/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` 或空字符串。 ## 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` 的数值返回并最多保留两位小数,空值由页面展示为“—”。 ### 学员字段示例 ```json { "relationId": 1801, "userId": "1900000000000000101", "name": "张三", "phone": "13800000000", "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` 完全一致,可直接复用账户管理的详情组件。 ### 7.2 编辑名单资料 `PUT /class/admin/{classId}/students/{userId}` ```json { "name": "张三", "phone": "13800000000", "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 节接口;点击编辑提交第 7.2 节接口,成功后替换当前行。 4. 打开转班弹窗时调用第 8 节接口,提交成功后重新获取班级详情和左侧班级树。 5. 移除成功后重新获取详情和树,不在前端自行推算班级人数。 6. 结业弹窗用名单中的理论/实训分和 `graduationEligible` 展示达标摘要;提交后按响应展示跳过项, 然后刷新详情。 7. 下载文件时必须按二进制处理,不要把CSV响应交给统一JSON响应拦截器。 所有JSON接口使用项目统一 `Result` 包装;业务失败由统一异常处理器返回中文 `msg`。发生失败时 前端保留当前选择,展示 `msg` 并重新拉取详情,以处理其他管理员并发修改关系的情况。 ## 14. 常见业务错误 | 场景 | 服务端提示 | 前端处理 | |---|---|---| | 未选择学员 | 请至少选择一名学员 | 不发请求并高亮选择区 | | 超过批量上限 | 单次批量操作不能超过500名学员 | 拆分选择或减少人数 | | 成员并发变化 | 部分学员已不在当前班级,请刷新后重试 | 刷新详情并清空失效选择 | | 转入当前班 | 目标班级不能是当前班级 | 保持弹窗并重新选择 | | 转入已结课班 | 目标班级必须是待开课或进行中状态 | 刷新目标班选项 | | 手机号重复 | 手机号已被其他账户使用 | 保持编辑弹窗并定位手机号 | | 重复结业 | 当前账户状态不支持结业 | 在结果明细中展示跳过原因 | ## 15. 数据库部署 部署应用前执行 `sql/class_management.sql`。新增表: - `class_student_change_log`:保存移除/转班历史,不影响当前班级权限判断。 - `student_graduation_record`:保存班级维度结业批次、说明、证书和通知请求。 脚本使用 `create table if not exists`,可重复执行;所有建表语句均不指定字符集或排序规则,沿用 目标数据库默认配置。上线顺序为:备份数据库 → 执行脚本 → 部署后端 → 前端联调验证。