Commit 72627bfe authored by 王蔡翾's avatar 王蔡翾
Browse files

签到码优化

parent dedf77a4
...@@ -49,7 +49,7 @@ public class ClassSubjectAttendanceSessionEntity { ...@@ -49,7 +49,7 @@ public class ClassSubjectAttendanceSessionEntity {
private Date startedAt; private Date startedAt;
@TableField("code_expires_at") @TableField("code_expires_at")
@ApiModelProperty("验证码截止时间,以计划开始时间加配置分钟数计算") @ApiModelProperty("签到码失效时间,与当前课程停止签到时间一致")
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date codeExpiresAt; private Date codeExpiresAt;
......
...@@ -36,7 +36,7 @@ public class AttendanceSessionVO { ...@@ -36,7 +36,7 @@ public class AttendanceSessionVO {
/** 教师首次点击开始上课时间。 */ /** 教师首次点击开始上课时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date startedAt; private Date startedAt;
/** 验证码校验截止时间;超过后只校验IP并记为迟到。 */ /** 签到码失效时间,与当前课程停止签到时间一致。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date codeExpiresAt; private Date codeExpiresAt;
} }
...@@ -8,13 +8,16 @@ import java.util.ArrayList; ...@@ -8,13 +8,16 @@ import java.util.ArrayList;
import java.util.Arrays; import java.util.Arrays;
import java.util.List; import java.util.List;
/** 绑定attendance前缀下的签到时限、允许网段和代理头信任配置。 */ /** 绑定attendance前缀下的正常签到时限、允许网段和代理头信任配置。 */
@Data @Data
@Component @Component
@ConfigurationProperties(prefix = "attendance") @ConfigurationProperties(prefix = "attendance")
public class AttendanceProperties { public class AttendanceProperties {
/** 计划开始后的验证码有效分钟数。 */ /**
* 计划开始后仍记为正常签到的分钟数。
* 配置名为兼容现有部署继续沿用 verification-code-valid-minutes;签到码本身有效至课程停止签到。
*/
private int verificationCodeValidMinutes = 15; private int verificationCodeValidMinutes = 15;
/** /**
......
...@@ -21,7 +21,7 @@ public interface AttendanceService { ...@@ -21,7 +21,7 @@ public interface AttendanceService {
AttendanceSessionVO startClass(Integer subjectId, String teacherId); AttendanceSessionVO startClass(Integer subjectId, String teacherId);
/** /**
* 学员签到。计划开始后的验证码窗口内校验IP和验证码,窗口结束后只校验IP并记为迟到。 * 学员签到。整个课程签到时段均校验IP和本课次唯一验证码,超过正常签到时限后记为迟到。
*/ */
AttendanceRecordVO checkIn(AttendanceCheckInDTO request, String studentId, String clientIp); AttendanceRecordVO checkIn(AttendanceCheckInDTO request, String studentId, String clientIp);
......
...@@ -81,15 +81,6 @@ public class AttendanceServiceImpl implements AttendanceService { ...@@ -81,15 +81,6 @@ public class AttendanceServiceImpl implements AttendanceService {
ClassSubjectEntity subject = requireSubject(subjectId); ClassSubjectEntity subject = requireSubject(subjectId);
requireTeacher(subject, teacherId); requireTeacher(subject, teacherId);
// 课程与会话是一对一关系:已经开始过的课程始终返回原验证码,不重新生成。
ClassSubjectAttendanceSessionEntity existing = findSession(subjectId);
if (existing != null) {
if (existing.getVerificationCode() == null) {
throw new BusinessException("课程已结束,不能开始上课");
}
return toSessionVO(existing, subject);
}
ClassSubjectTimeUtils.TimeWindow window = ClassSubjectTimeUtils.resolve(subject); ClassSubjectTimeUtils.TimeWindow window = ClassSubjectTimeUtils.resolve(subject);
Date now = new Date(); Date now = new Date();
if (now.before(window.getStart())) { if (now.before(window.getStart())) {
...@@ -99,6 +90,17 @@ public class AttendanceServiceImpl implements AttendanceService { ...@@ -99,6 +90,17 @@ public class AttendanceServiceImpl implements AttendanceService {
throw new BusinessException("课程已结束,不能开始上课"); throw new BusinessException("课程已结束,不能开始上课");
} }
// 一次排课只允许存在一个签到码:课程仍可签到时,重复点击开始或刷新均返回原会话。
// SESSION_ENDED 表示该课次已被关闭,即使计划结束时间尚未到,也不能再次暴露或生成签到码。
ClassSubjectAttendanceSessionEntity existing = findSession(subjectId);
if (existing != null) {
if (!AttendanceConstants.SESSION_ACTIVE.equals(existing.getStatus())
|| existing.getVerificationCode() == null) {
throw new BusinessException("当前课程已停止签到");
}
return toSessionVO(existing, subject);
}
ClassSubjectAttendanceSessionEntity session = new ClassSubjectAttendanceSessionEntity(); ClassSubjectAttendanceSessionEntity session = new ClassSubjectAttendanceSessionEntity();
session.setSubjectId(subjectId); session.setSubjectId(subjectId);
session.setTeacherId(teacherId); session.setTeacherId(teacherId);
...@@ -107,8 +109,8 @@ public class AttendanceServiceImpl implements AttendanceService { ...@@ -107,8 +109,8 @@ public class AttendanceServiceImpl implements AttendanceService {
session.setScheduledStartTime(window.getStart()); session.setScheduledStartTime(window.getStart());
session.setScheduledEndTime(window.getEnd()); session.setScheduledEndTime(window.getEnd());
session.setStartedAt(now); session.setStartedAt(now);
// 验证码窗口以计划开始时间计算,与教师实际点击开始上课时间无关。 // 签到码与本课次签到窗口同生共灭,教师刷新页面不会缩短有效期或生成新码。
session.setCodeExpiresAt(addMinutes(window.getStart(), attendanceProperties.getVerificationCodeValidMinutes())); session.setCodeExpiresAt(window.getEnd());
session.setStatus(AttendanceConstants.SESSION_ACTIVE); session.setStatus(AttendanceConstants.SESSION_ACTIVE);
session.setCreatedTime(now); session.setCreatedTime(now);
session.setUpdateTime(now); session.setUpdateTime(now);
...@@ -119,6 +121,11 @@ public class AttendanceServiceImpl implements AttendanceService { ...@@ -119,6 +121,11 @@ public class AttendanceServiceImpl implements AttendanceService {
if (session == null) { if (session == null) {
throw new BusinessException("开始上课失败,请稍后重试"); throw new BusinessException("开始上课失败,请稍后重试");
} }
// 并发请求读取到的会话也必须仍处于活动状态,避免与自动关课同时发生时返回失效签到码。
if (!AttendanceConstants.SESSION_ACTIVE.equals(session.getStatus())
|| session.getVerificationCode() == null) {
throw new BusinessException("当前课程已停止签到");
}
} }
return toSessionVO(session, subject); return toSessionVO(session, subject);
} }
...@@ -159,24 +166,19 @@ public class AttendanceServiceImpl implements AttendanceService { ...@@ -159,24 +166,19 @@ public class AttendanceServiceImpl implements AttendanceService {
throw new BusinessException("当前出勤状态为" + existing.getStatus() + ",不能重复签到"); throw new BusinessException("当前出勤状态为" + existing.getStatus() + ",不能重复签到");
} }
// 超过计划开始+配置分钟数后不再要求验证码,但初始状态固定为迟到。 // 整个可签到时段都校验同一个验证码;配置分钟数只划分正常签到与迟到,不再让验证码提前失效。
boolean afterCodeWindow = now.after(session.getCodeExpiresAt()); String code = request.getVerificationCode() == null ? "" : request.getVerificationCode().trim();
String status; if (!code.matches("\\d{6}")) {
String method; throw new BusinessException("请输入教师提供的6位数字验证码");
if (afterCodeWindow) { }
status = AttendanceConstants.STATUS_LATE; if (!constantTimeEquals(code, session.getVerificationCode())) {
method = AttendanceConstants.METHOD_IP_ONLY; throw new BusinessException("签到验证码不正确");
} else {
String code = request.getVerificationCode() == null ? "" : request.getVerificationCode().trim();
if (!code.matches("\\d{6}")) {
throw new BusinessException("请输入教师提供的6位数字验证码");
}
if (!constantTimeEquals(code, session.getVerificationCode())) {
throw new BusinessException("签到验证码不正确");
}
status = AttendanceConstants.STATUS_NORMAL;
method = AttendanceConstants.METHOD_IP_CODE;
} }
Date normalCheckInDeadline = addMinutes(window.getStart(),
attendanceProperties.getVerificationCodeValidMinutes());
String status = now.after(normalCheckInDeadline)
? AttendanceConstants.STATUS_LATE : AttendanceConstants.STATUS_NORMAL;
String method = AttendanceConstants.METHOD_IP_CODE;
ClassSubjectAttendanceEntity record = new ClassSubjectAttendanceEntity(); ClassSubjectAttendanceEntity record = new ClassSubjectAttendanceEntity();
record.setSubjectId(subject.getId()); record.setSubjectId(subject.getId());
......
...@@ -20,7 +20,7 @@ ...@@ -20,7 +20,7 @@
## 学员端 ## 学员端
- `POST /attendance/student/check-in`:课程开始15分钟内同时校验IP和验证码;超过15分钟且未到课程结束时间时只校验IP并自动记为 `LATE`。 - `POST /attendance/student/check-in`:当前课程允许签到期间始终校验IP和本课次唯一验证码;超过正常签到时限后自动记为 `LATE`,但验证码不变。
- `POST /attendance/student/records`:查询当前登录学员的出勤记录。 - `POST /attendance/student/records`:查询当前登录学员的出勤记录。
签到请求示例: 签到请求示例:
...@@ -45,6 +45,7 @@ ...@@ -45,6 +45,7 @@
```yaml ```yaml
attendance: attendance:
# 为兼容现有配置保留原字段名;该值只控制超过多少分钟记为迟到,签到码有效至课程停止签到。
verification-code-valid-minutes: 15 verification-code-valid-minutes: 15
allowed-ip-cidrs: allowed-ip-cidrs:
- 192.168.10.0/24 - 192.168.10.0/24
......
...@@ -40,6 +40,7 @@ server: ...@@ -40,6 +40,7 @@ server:
# 出勤签到配置。allowed-ip-cidrs 为空时会安全拒绝签到,当前按教学网络实际范围配置。 # 出勤签到配置。allowed-ip-cidrs 为空时会安全拒绝签到,当前按教学网络实际范围配置。
attendance: attendance:
# 兼容历史配置名:该值控制正常签到时限,签到码本身有效至课程停止签到。
verification-code-valid-minutes: 15 verification-code-valid-minutes: 15
# 教学网络地址范围为192.168.10.0至192.168.10.255,对应CIDR前缀/24。 # 教学网络地址范围为192.168.10.0至192.168.10.255,对应CIDR前缀/24。
allowed-ip-cidrs: allowed-ip-cidrs:
......
package com.platform.business.service.impl;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.platform.business.config.AttendanceProperties;
import com.platform.business.constant.AttendanceConstants;
import com.platform.business.mapper.ClassSubjectAttendanceMapper;
import com.platform.business.mapper.ClassSubjectAttendanceSessionMapper;
import com.platform.business.model.dto.AttendanceCheckInDTO;
import com.platform.business.model.entity.ClassSubjectAttendanceEntity;
import com.platform.business.model.entity.ClassSubjectAttendanceSessionEntity;
import com.platform.business.model.entity.ClassSubjectEntity;
import com.platform.business.model.vo.AttendanceRecordVO;
import com.platform.business.model.vo.AttendanceSessionVO;
import com.platform.business.service.ClassService;
import com.platform.business.service.ClassStudentService;
import com.platform.business.service.ClassSubjectAttendanceService;
import com.platform.business.service.ClassSubjectAttendanceSessionService;
import com.platform.business.service.ClassSubjectService;
import com.platform.business.service.UserService;
import com.platform.exception.BusinessException;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.test.util.ReflectionTestUtils;
import java.util.Calendar;
import java.util.Collections;
import java.util.Date;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/** 验证同一课次的签到码只生成一次,并与课程可签到时段保持一致。 */
@ExtendWith(MockitoExtension.class)
class AttendanceSessionServiceImplTest {
@Mock
private ClassSubjectService classSubjectService;
@Mock
private ClassSubjectAttendanceSessionService attendanceSessionService;
@Mock
private ClassSubjectAttendanceSessionMapper attendanceSessionMapper;
@Mock
private ClassStudentService classStudentService;
@Mock
private ClassSubjectAttendanceService attendanceRecordService;
@Mock
private ClassSubjectAttendanceMapper attendanceMapper;
@Mock
private ClassService classService;
@Mock
private UserService userService;
private AttendanceServiceImpl service;
@BeforeEach
void setUp() {
service = new AttendanceServiceImpl();
ReflectionTestUtils.setField(service, "classSubjectService", classSubjectService);
ReflectionTestUtils.setField(service, "attendanceSessionService", attendanceSessionService);
ReflectionTestUtils.setField(service, "attendanceSessionMapper", attendanceSessionMapper);
ReflectionTestUtils.setField(service, "classStudentService", classStudentService);
ReflectionTestUtils.setField(service, "attendanceRecordService", attendanceRecordService);
ReflectionTestUtils.setField(service, "attendanceMapper", attendanceMapper);
ReflectionTestUtils.setField(service, "classService", classService);
ReflectionTestUtils.setField(service, "userService", userService);
AttendanceProperties properties = new AttendanceProperties();
properties.setVerificationCodeValidMinutes(0);
properties.setAllowedIpCidrs(Collections.singletonList("127.0.0.1/32"));
ReflectionTestUtils.setField(service, "attendanceProperties", properties);
}
@Test
void repeatedStartShouldReturnOriginalVerificationCode() {
ClassSubjectEntity subject = activeSubject();
ClassSubjectAttendanceSessionEntity existing = activeSession("123456");
when(classSubjectService.getById(10)).thenReturn(subject);
when(attendanceSessionService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(existing);
AttendanceSessionVO result = service.startClass(10, "teacher-1");
assertEquals("123456", result.getVerificationCode());
assertEquals("session-1", result.getSessionId());
// 已有会话时不能再次执行插入,否则刷新操作可能产生新的签到码。
verify(attendanceSessionMapper, never()).insertIgnore(any());
}
@Test
void newVerificationCodeShouldExpireWhenCourseStopsAcceptingCheckIn() {
ClassSubjectEntity subject = activeSubject();
when(classSubjectService.getById(10)).thenReturn(subject);
when(attendanceSessionService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(null);
when(attendanceSessionMapper.insertIgnore(any())).thenReturn(1);
AttendanceSessionVO result = service.startClass(10, "teacher-1");
ArgumentCaptor<ClassSubjectAttendanceSessionEntity> captor =
ArgumentCaptor.forClass(ClassSubjectAttendanceSessionEntity.class);
verify(attendanceSessionMapper).insertIgnore(captor.capture());
ClassSubjectAttendanceSessionEntity saved = captor.getValue();
assertEquals(saved.getScheduledEndTime(), saved.getCodeExpiresAt());
assertEquals(saved.getScheduledEndTime(), result.getCodeExpiresAt());
assertTrue(saved.getVerificationCode().matches("\\d{6}"));
}
@Test
void endedCourseShouldNotReturnOrRegenerateVerificationCode() {
ClassSubjectEntity subject = activeSubject();
subject.setDate(addDays(new Date(), -1));
when(classSubjectService.getById(10)).thenReturn(subject);
BusinessException error = assertThrows(BusinessException.class,
() -> service.startClass(10, "teacher-1"));
assertEquals("课程已结束,不能开始上课", error.getMessage());
// 课程已不可签到时直接拒绝,不再读取旧码,也不创建新码。
verify(attendanceSessionService, never()).getOne(any(LambdaQueryWrapper.class), eq(false));
verify(attendanceSessionMapper, never()).insertIgnore(any());
}
@Test
void lateCheckInShouldStillRequireAndUseOriginalVerificationCode() {
ClassSubjectEntity subject = activeSubject();
ClassSubjectAttendanceSessionEntity existing = activeSession("123456");
when(classSubjectService.getById(10)).thenReturn(subject);
when(classStudentService.count(any(LambdaQueryWrapper.class))).thenReturn(1L);
when(attendanceSessionService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(existing);
when(attendanceRecordService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(null);
when(attendanceMapper.insertIgnore(any())).thenReturn(1);
AttendanceRecordVO saved = new AttendanceRecordVO();
saved.setStatus(AttendanceConstants.STATUS_LATE);
saved.setCheckInMethod(AttendanceConstants.METHOD_IP_CODE);
when(attendanceMapper.queryRecords(any())).thenReturn(Collections.singletonList(saved));
AttendanceCheckInDTO request = new AttendanceCheckInDTO();
request.setSubjectId(10);
request.setVerificationCode("123456");
AttendanceRecordVO result = service.checkIn(request, "student-1", "127.0.0.1");
assertEquals(AttendanceConstants.STATUS_LATE, result.getStatus());
assertEquals(AttendanceConstants.METHOD_IP_CODE, result.getCheckInMethod());
ArgumentCaptor<ClassSubjectAttendanceEntity> recordCaptor =
ArgumentCaptor.forClass(ClassSubjectAttendanceEntity.class);
verify(attendanceMapper).insertIgnore(recordCaptor.capture());
assertEquals(AttendanceConstants.METHOD_IP_CODE, recordCaptor.getValue().getCheckInMethod());
}
@Test
void lateCheckInShouldRejectMissingVerificationCode() {
ClassSubjectEntity subject = activeSubject();
when(classSubjectService.getById(10)).thenReturn(subject);
when(classStudentService.count(any(LambdaQueryWrapper.class))).thenReturn(1L);
when(attendanceSessionService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(activeSession("123456"));
when(attendanceRecordService.getOne(any(LambdaQueryWrapper.class), eq(false)))
.thenReturn(null);
AttendanceCheckInDTO request = new AttendanceCheckInDTO();
request.setSubjectId(10);
BusinessException error = assertThrows(BusinessException.class,
() -> service.checkIn(request, "student-1", "127.0.0.1"));
assertEquals("请输入教师提供的6位数字验证码", error.getMessage());
verify(attendanceMapper, never()).insertIgnore(any());
}
/** 构造当天几乎全天有效的课程,避免测试依赖固定日期。 */
private static ClassSubjectEntity activeSubject() {
ClassSubjectEntity subject = new ClassSubjectEntity();
subject.setId(10);
subject.setClassId(5);
subject.setTeacherId("teacher-1");
subject.setSubjectName("测试课程");
subject.setDate(new Date());
subject.setTimeFrame("00:00-23:59");
return subject;
}
/** 构造数据库中已经存在的活动签到会话,用于模拟教师刷新页面。 */
private static ClassSubjectAttendanceSessionEntity activeSession(String code) {
ClassSubjectAttendanceSessionEntity session = new ClassSubjectAttendanceSessionEntity();
session.setId("session-1");
session.setSubjectId(10);
session.setTeacherId("teacher-1");
session.setVerificationCode(code);
session.setStatus(AttendanceConstants.SESSION_ACTIVE);
return session;
}
private static Date addDays(Date date, int days) {
Calendar calendar = Calendar.getInstance();
calendar.setTime(date);
calendar.add(Calendar.DAY_OF_MONTH, days);
return calendar.getTime();
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment