# 出勤管理接口 所有人员均由登录令牌解析出的用户 `id` 标识;响应中的学员、教师展示字段使用完整手机号,不使用学号或教师号。 ## 教师端 - `POST /attendance/teacher/course/{subjectId}/start`:到达计划开始时间后开始上课。首次调用生成6位验证码;后续调用返回同一课次原验证码。 - `GET /attendance/teacher/course/{subjectId}/roster`:查询学员姓名、完整手机号、签到时间、方式、IP和状态。 - `PUT /attendance/teacher/status`:教师手动设置 `NORMAL`、`LATE` 或 `ABSENT`。 状态调整请求示例: ```json { "subjectId": 1001, "studentId": "190000000000000001", "status": "LATE" } ``` ## 学员端 - `POST /attendance/student/check-in`:课程开始15分钟内同时校验IP和验证码;超过15分钟且未到课程结束时间时只校验IP并自动记为 `LATE`。 - `POST /attendance/student/records`:查询当前登录学员的出勤记录。 签到请求示例: ```json { "subjectId": 1001, "verificationCode": "123456" } ``` ## 管理端 - `POST /attendance/admin/records/page`:按班级、课程、状态、日期范围分页查询。 - `POST /attendance/admin/statistics`:按班级、课程和日期范围返回班级人数、课程数、应到、正常签到、迟到、缺勤、请假、异常人次及出勤率;`studentStatistics` 的每行包含 `className`,跨班级统计时用顿号连接班级名称。管理员接口不修改出勤状态。 管理端班级看板口径:`出勤率 = 正常签到 ÷ 应到人次 × 100%`;迟到、请假、缺勤均归入异常人次。因此图片示例中的 250 次正常签到、15 次迟到、12 次请假、3 次缺勤,得到应到 280 次、异常 30 次、出勤率 `250 ÷ 280 = 89.3%`。 ## IP网段配置 在配置中心为业务服务补充: ```yaml attendance: verification-code-valid-minutes: 15 allowed-ip-cidrs: - 192.168.10.0/24 trust-forwarded-headers: false ``` `allowed-ip-cidrs` 为空时系统会拒绝签到。只有入口网关会清洗并重写转发头时,才能把 `trust-forwarded-headers` 设为 `true`。 审批通过的请假会把所关联课程的出勤状态同步为 `LEAVE`。统计时,请假计入应到和异常人次,但不计入正常签到,因此会降低管理端出勤率。