# 学员 / 教师 / 管理员首页接口 ## 1. 通用约定 - 服务:`practical-business`,所有接口均为 `GET`。 - 请求头:`Authorization: Bearer `,同时兼容项目历史裸 Token 格式。 - 响应:统一使用 `Result` 包装。 - 学员和教师接口不接收用户 ID,服务端只使用 JWT 对应的当前用户。 - 日期格式:日期为 `yyyy-MM-dd`,时间为 `yyyy-MM-dd HH:mm`,时区为 `GMT+8`。 - 空列表返回 `[]`,统计数量和比率无数据时返回 `0`,不返回 `null`。 ## 2. 学员首页 ### 2.1 欢迎区 `GET /home/student/profile` 返回:`name`、`studentNo`、`avatar`、`classId`、`className`、`level`。 当前班级优先选择正在培训的未归档班级,其次选择尚未结束的未来班级,最后回退到最近的历史班级。 ### 2.2 首页统计 `GET /home/student/statistics` 返回:`courseCount`、`pendingExamCount`、`completedExamCount`、`averageScore`。 - 课程数按当前班级不同课程名称统计。 - 已完成考试按已交卷统计。 - 平均分只统计已发布且分数非空的正式考试。 ### 2.3 未来七天考试 `GET /home/student/upcoming-exams` 每项字段:`examId`、`examName`、`type`、`examTime`、`endTime`、`duration`、`location`、`status`、`actionType`、`actionEnabled`。 - `status`:`NOT_STARTED`、`IN_PROGRESS`。 - `actionType`:理论考试为 `ENTER_EXAM`,实训考试为 `VIEW_INSTRUCTION`。 - 理论考试未到开始时间时 `actionEnabled=false`。 ### 2.4 最近成绩 `GET /home/student/recent-scores` 正式考试和理论模拟考试按时间合并后返回最近 5 条。每项字段:`recordId`、`source`、`examName`、`type`、`score`、`totalScore`、`rank`、`scoreTime`。 - `source`:`EXAM`、`SIMULATION`。 - 模拟考试没有班级排名,`rank` 返回 `null`。 ### 2.5 近三天课程 `GET /home/student/courses/next-three-days` 固定返回今天、明天、后天三个分组,即使当天没有课程也会返回空 `courses`。课程状态为 `IN_PROGRESS`、`UPCOMING` 或 `PENDING`;距离首个时段开始不超过 60 分钟为 `UPCOMING`。 ## 3. 教师首页 | 接口 | 说明 | |---|---| | `GET /home/teacher/profile` | 姓名、工号、头像、任教课程集合、授课班级数 | | `GET /home/teacher/statistics` | 任教课程数、班级数、待阅卷数、本月参与考试数 | | `GET /home/teacher/pending-reviews` | 当前教师作为首席考评员的前 5 个待阅卷任务 | | `GET /home/teacher/upcoming-exams` | 当前教师未来 7 天参与的考试 | | `GET /home/teacher/attendance/today` | 今日授课班级出勤人次汇总 | 考试安排状态:存在 `exam_student` 分配记录为 `SCHEDULED`,否则为 `PENDING_PUBLICATION`。出勤率分子为 `NORMAL + LATE`,分母为授课课次对应的应到人次。 ## 4. 管理员首页 | 接口 | 说明 | |---|---| | `GET /home/admin/statistics` | 学员、班级、教师、考试 KPI | | `GET /home/admin/classes` | 理论掌握率可筛选的未归档班级 | | `GET /home/admin/theory-mastery?classId=1` | 最多 6 个一级知识点掌握率;不传班级统计全平台 | | `GET /home/admin/todos` | 教案、请假、设备维护三类管理员待办 | | `GET /home/admin/class-status` | 待开班、进行中、已结课、已结业分布 | | `GET /home/admin/student-activity` | 最近 7 天登录/答题人数及活跃摘要 | 待办类型固定为:`TEACHING_PLAN`、`LEAVE_APPROVAL`、`EQUIPMENT_MAINTENANCE`。试卷批阅只出现在教师首页,管理员首页不返回该待办。 班级状态固定为:`NOT_STARTED`、`ONGOING`、`FINISHED`、`GRADUATED`。有学员且所有学员账户均为 `GRADUATED/ARCHIVED` 时优先判定为已结业。 ## 5. 旧接口兼容 下列旧地址暂时保留在管理员兼容 Controller 中,并增加管理员角色校验: - `/home/recent/train/Plan` - `/home/year/plan/complete` - `/home/current/course/situation` - `/home/today/course` 新页面不得继续接入上述接口。 ## 6. 数据库发布 执行 `sql/home_dashboard.sql`。脚本会增加 `class.archived_flag`、创建设备维护表并补充首页聚合索引;脚本可重复执行,不会伪造设备维护记录。