# 管理员端班级管理接口 接口统一使用 `/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}` 详情包含: - 基础信息、计划/实际人数、培训自然日数和动态班级状态。 - 按课程名称、类型和授课教师聚合的课程列表,课时为全部排课课时之和。 - 全班及个人出勤率;只有 `NORMAL/LATE` 计入出勤分子,`ABSENT/LEAVE` 计入分母。 - 最近一场 `exam.mark_flag=true` 的考试,以及考生侧 `mark_flag=true` 的正式成绩。 - 最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回 `null`。 - 完整学员姓名和手机号。个人学习状态按班级日期派生为待开课、在读或已结业。 百分比字段以 `0~100` 的数值返回并最多保留两位小数,空值由页面展示为“—”。