Commit 0b2419f1 authored by 王蔡翾's avatar 王蔡翾
Browse files

消息中心,消息队列和websocket,以及请假注释

parent 1ea1a030
......@@ -5,24 +5,38 @@ import lombok.Data;
import java.util.Date;
/** 教师开始上课后返回的签到会话信息。 */
@Data
public class AttendanceSessionVO {
/** 签到会话ID。 */
private String sessionId;
/** 课程排课ID。 */
private Integer subjectId;
/** 课程名称。 */
private String subjectName;
/** 班级名称。 */
private String className;
/** 授课教师用户ID。 */
private String teacherId;
/** 授课教师姓名。 */
private String teacherName;
/** 授课教师完整手机号。 */
private String teacherPhone;
/** 本课次首次开始上课时生成且只生成一次的6位验证码。 */
private String verificationCode;
/** 会话状态:ACTIVE进行中、ENDED已结束。 */
private String status;
/** 课程计划开始时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date scheduledStartTime;
/** 课程计划结束时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date scheduledEndTime;
/** 教师首次点击开始上课时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date startedAt;
/** 验证码校验截止时间;超过后只校验IP并记为迟到。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date codeExpiresAt;
}
......@@ -4,15 +4,25 @@ import lombok.Data;
import java.math.BigDecimal;
/** 管理端按学员维度汇总的出勤统计。 */
@Data
public class AttendanceStudentStatisticsVO {
/** 学员用户ID。 */
private String studentId;
/** 学员姓名。 */
private String studentName;
/** 学员完整手机号。 */
private String studentPhone;
/** 应出勤课次,包含请假。 */
private long requiredCount;
/** 正常签到课次。 */
private long normalCount;
/** 迟到签到课次。 */
private long lateCount;
/** 缺勤课次。 */
private long absentCount;
/** 请假课次;计算出勤率时按未出勤处理。 */
private long leaveCount;
/** 出勤率百分比:(正常+迟到)/应出勤×100。 */
private BigDecimal attendanceRate;
}
......@@ -5,14 +5,23 @@ import lombok.Data;
import java.math.BigDecimal;
import java.util.List;
/** 管理端出勤统计总览,同时包含按学员和按课程两个明细维度。 */
@Data
public class AttendanceSummaryVO {
/** 应出勤总人次,包含请假。 */
private long requiredCount;
/** 正常签到总人次。 */
private long normalCount;
/** 迟到签到总人次。 */
private long lateCount;
/** 缺勤总人次。 */
private long absentCount;
/** 请假总人次;计算出勤率时不计入出勤。 */
private long leaveCount;
/** 总出勤率百分比:(正常+迟到)/应出勤×100。 */
private BigDecimal attendanceRate;
/** 按学员汇总的统计列表。 */
private List<AttendanceStudentStatisticsVO> studentStatistics;
/** 按课程汇总的统计列表。 */
private List<AttendanceCourseStatisticsVO> courseStatistics;
}
......@@ -6,31 +6,53 @@ import lombok.Data;
import java.util.Date;
import java.util.List;
/** 请假申请详情及三端列表展示对象,人员联系方式均返回完整手机号。 */
@Data
public class LeaveApplicationVO {
/** 请假申请ID。 */
private String id;
/** 申请学员用户ID。 */
private String studentId;
/** 申请学员姓名。 */
private String studentName;
/** 申请学员完整手机号,教师端和管理端用其替代学号。 */
private String studentPhone;
/** 请假类型:SICK/PERSONAL/OTHER。 */
private String leaveType;
/** 请假开始时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date startTime;
/** 请假结束时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date endTime;
/** 请假总时长,单位:分钟。 */
private Long durationMinutes;
/** 请假原因。 */
private String reason;
/** 紧急联系人姓名,可为空。 */
private String emergencyContactName;
/** 紧急联系人手机号,可为空。 */
private String emergencyContactPhone;
/** 申请状态:PENDING/APPROVED/REJECTED/WITHDRAWN。 */
private String status;
/** 最终审批人用户ID。 */
private String approverId;
/** 最终审批人姓名。 */
private String approverName;
/** 最终审批人完整手机号。 */
private String approverPhone;
/** 最终审批人角色:TEACHER或ADMIN。 */
private String approverRole;
/** 审批意见。 */
private String approvalOpinion;
/** 申请提交时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date appliedAt;
/** 批准或拒绝时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date reviewedAt;
/** 按请假时间自动匹配的全部课程。 */
private List<LeaveSubjectVO> subjects;
/** 申请关联的证明材料。 */
private List<LeaveAttachmentVO> attachments;
}
......@@ -2,8 +2,11 @@ package com.platform.business.model.vo;
import lombok.Data;
/** 请假证明材料的展示信息。文件内容通过统一文件下载接口获取。 */
@Data
public class LeaveAttachmentVO {
/** 文件表ID,也是下载接口所需ID。 */
private Integer fileId;
/** 上传时的原始文件名。 */
private String fileName;
}
......@@ -5,16 +5,26 @@ import lombok.Data;
import java.util.Date;
/** 请假申请自动关联课程的展示信息。 */
@Data
public class LeaveSubjectVO {
/** 课程排课ID。 */
private Integer subjectId;
/** 课程名称。 */
private String subjectName;
/** 班级ID。 */
private Integer classId;
/** 班级名称。 */
private String className;
/** 授课教师用户ID。 */
private String teacherId;
/** 授课教师姓名。 */
private String teacherName;
/** 授课教师完整手机号。 */
private String teacherPhone;
/** 课程日期。 */
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date subjectDate;
/** 课程排课时段原始文本。 */
private String timeFrame;
}
package com.platform.business.model.vo;
import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.Data;
import java.util.Date;
/** 管理端、教师端和学员端共用的消息展示对象。 */
@Data
public class NotificationMessageVO {
/** 消息ID。 */
private String id;
/** 业务事件ID,可用于前端或日志进行链路排查。 */
private String eventId;
/** 消息类型。 */
private String messageType;
/** 消息标题。 */
private String title;
/** 消息摘要。 */
private String summary;
/** 完整正文;列表页面可忽略,详情页面展示。 */
private String content;
/** 发送用户ID。 */
private String senderId;
/** 发送人名称。 */
private String senderName;
/** 来源业务类型。 */
private String businessType;
/** 来源业务ID。 */
private String businessId;
/** 站内跳转地址。 */
private String actionUrl;
/** 消息优先级。 */
private String priority;
/** 当前登录用户是否已经阅读。 */
private Boolean readFlag;
/** 当前用户首次阅读时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date readAt;
/** 消息创建时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date createdAt;
/** 消息过期时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date expiresAt;
}
package com.platform.business.model.vo;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 浏览器建立消息WebSocket前申请的一次性短票据。
*
* <p>浏览器原生WebSocket无法添加Authorization请求头,因此先使用JWT调用HTTP接口申请短票据,
* 再用票据完成握手。票据存放在Redis中,过期时间短且消费后立即删除。</p>
*/
@Data
@AllArgsConstructor
public class NotificationSocketTicketVO {
/** 随机一次性票据,不包含用户明文信息。 */
private String ticket;
/** 对应当前用户的WebSocket相对路径。 */
private String endpoint;
/** 票据剩余有效秒数,便于前端决定是否重新申请。 */
private long expiresInSeconds;
}
......@@ -42,6 +42,22 @@
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
<!-- RabbitMQ:业务事件可靠投递、TTL重试、死信和节点级在线推送。 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
<!-- Redis:一次性WebSocket票据、在线节点目录和可降级的未读数缓存。 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<!-- 消息中心关键流程使用JUnit 5 + Mockito进行单元测试。 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- Apache POI for Excel handling -->
<dependency>
<groupId>org.apache.poi</groupId>
......
......@@ -5,8 +5,10 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
/** 绑定attendance前缀下的签到时限、允许网段和代理头信任配置。 */
@Data
@Component
@ConfigurationProperties(prefix = "attendance")
......@@ -18,7 +20,7 @@ public class AttendanceProperties {
/**
* 允许签到的IPv4网段,例如 192.168.10.0/24。为空时安全拒绝签到,等待部署时补充。
*/
private List<String> allowedIpCidrs = new ArrayList<>();
private List<String> allowedIpCidrs = Arrays.asList();
/** 只有网关已清洗转发头时才应开启。 */
private boolean trustForwardedHeaders = false;
......
package com.platform.business.config;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.platform.business.constant.NotificationConstants;
import com.platform.business.service.NotificationNodeIdentity;
import org.springframework.amqp.core.Binding;
import org.springframework.amqp.core.BindingBuilder;
import org.springframework.amqp.core.DirectExchange;
import org.springframework.amqp.core.Queue;
import org.springframework.amqp.core.QueueBuilder;
import org.springframework.amqp.core.TopicExchange;
import org.springframework.amqp.support.converter.Jackson2JsonMessageConverter;
import org.springframework.amqp.support.converter.MessageConverter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Qualifier;
/**
* 消息中心RabbitMQ拓扑定义。
*
* <p>持久化事件和死信使用Quorum Queue以获得多副本一致性;消费失败先进入带TTL的普通重试队列,
* 到期后通过死信路由返回事件交换机;实时推送使用每个服务节点一个临时队列,队列数量不会随用户增长。</p>
*/
@Configuration
public class NotificationRabbitConfig {
/** 持久业务事件使用Topic Exchange,便于按消息类型扩展独立消费者。 */
@Bean
public TopicExchange notificationEventExchange() {
return new TopicExchange(NotificationConstants.EVENT_EXCHANGE, true, false);
}
/** 所有消息类型共用的持久化Quorum Queue。 */
@Bean
public Queue notificationEventQueue() {
return QueueBuilder.durable(NotificationConstants.EVENT_QUEUE)
.withArgument("x-queue-type", "quorum")
.deadLetterExchange(NotificationConstants.DEAD_EXCHANGE)
.deadLetterRoutingKey(NotificationConstants.DEAD_ROUTING_KEY)
.build();
}
/** notification.#确保当前和未来新增的消息类型都能进入统一落库流程。 */
@Bean
public Binding notificationEventBinding(@Qualifier("notificationEventQueue") Queue notificationEventQueue,
@Qualifier("notificationEventExchange") TopicExchange notificationEventExchange) {
return BindingBuilder.bind(notificationEventQueue).to(notificationEventExchange)
.with(NotificationConstants.EVENT_ROUTING_PATTERN);
}
/** 消费失败事件的Direct Exchange。 */
@Bean
public DirectExchange notificationRetryExchange() {
return new DirectExchange(NotificationConstants.RETRY_EXCHANGE, true, false);
}
/**
* 固定等待30秒的重试队列。
* 队列本身没有消费者,消息TTL到期后由DLX重新路由到notification.events.x。
*/
@Bean
public Queue notificationRetryQueue() {
return QueueBuilder.durable(NotificationConstants.RETRY_QUEUE)
.ttl(30_000)
.deadLetterExchange(NotificationConstants.EVENT_EXCHANGE)
.deadLetterRoutingKey("notification.retry")
.build();
}
/** 将应用重试路由键绑定到30秒等待队列。 */
@Bean
public Binding notificationRetryBinding(@Qualifier("notificationRetryQueue") Queue notificationRetryQueue,
@Qualifier("notificationRetryExchange") DirectExchange notificationRetryExchange) {
return BindingBuilder.bind(notificationRetryQueue).to(notificationRetryExchange)
.with(NotificationConstants.RETRY_ROUTING_KEY);
}
/** 无法自动恢复事件的死信交换机。 */
@Bean
public DirectExchange notificationDeadExchange() {
return new DirectExchange(NotificationConstants.DEAD_EXCHANGE, true, false);
}
/** 死信使用Quorum Queue,确保异常事件不会因单节点故障丢失。 */
@Bean
public Queue notificationDeadQueue() {
return QueueBuilder.durable(NotificationConstants.DEAD_QUEUE)
.withArgument("x-queue-type", "quorum")
.build();
}
/** 死信队列只存储待人工检查报文,不配置自动消费者。 */
@Bean
public Binding notificationDeadBinding(@Qualifier("notificationDeadQueue") Queue notificationDeadQueue,
@Qualifier("notificationDeadExchange") DirectExchange notificationDeadExchange) {
return BindingBuilder.bind(notificationDeadQueue).to(notificationDeadExchange)
.with(NotificationConstants.DEAD_ROUTING_KEY);
}
/** 节点在线推送使用Direct Exchange,routing key精确匹配节点ID。 */
@Bean
public DirectExchange notificationPushExchange() {
return new DirectExchange(NotificationConstants.PUSH_EXCHANGE, true, false);
}
/**
* 当前实例专属临时队列。
* exclusive + autoDelete确保实例断开后队列自动清理;队列中仅保存可降级的实时提示。
*/
@Bean(name = "notificationPushQueue")
public Queue notificationPushQueue(NotificationNodeIdentity nodeIdentity) {
return QueueBuilder.nonDurable("notification.push." + nodeIdentity.getNodeId() + ".q")
.exclusive()
.autoDelete()
.build();
}
/** 使用节点ID作为绑定键,使推送报文只到达持有目标WebSocket连接的实例。 */
@Bean
public Binding notificationPushBinding(@Qualifier("notificationPushQueue") Queue notificationPushQueue,
@Qualifier("notificationPushExchange") DirectExchange notificationPushExchange,
NotificationNodeIdentity nodeIdentity) {
return BindingBuilder.bind(notificationPushQueue).to(notificationPushExchange)
.with(nodeIdentity.getNodeId());
}
/** 统一使用Jackson序列化DTO,避免生产者和消费者使用不同报文格式。 */
@Bean
public MessageConverter notificationRabbitMessageConverter(ObjectMapper objectMapper) {
return new Jackson2JsonMessageConverter(objectMapper);
}
}
......@@ -4,33 +4,48 @@ import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
/** 出勤状态、记录方式和签到会话状态的统一常量定义。 */
public final class AttendanceConstants {
private AttendanceConstants() {
}
/** 在验证码有效期内完成IP和验证码双重校验的正常签到。 */
public static final String STATUS_NORMAL = "NORMAL";
/** 计划开始超过配置分钟数后,仅通过IP校验完成的迟到签到。 */
public static final String STATUS_LATE = "LATE";
/** 课程结束后仍无有效出勤记录,或由教师手动标记的缺勤。 */
public static final String STATUS_ABSENT = "ABSENT";
/** 请假审批通过后写入的状态;计算出勤率时按未出勤处理。 */
public static final String STATUS_LEAVE = "LEAVE";
/** IP网段和6位验证码双重校验。 */
public static final String METHOD_IP_CODE = "IP_CODE";
/** 超过验证码窗口后仅校验IP网段。 */
public static final String METHOD_IP_ONLY = "IP_ONLY";
/** 授课教师手动确认。 */
public static final String METHOD_TEACHER = "TEACHER";
/** 定时任务或查询触发的自动缺勤。 */
public static final String METHOD_SYSTEM = "SYSTEM";
/** 历史签到数据迁移后的兼容标记。 */
public static final String METHOD_LEGACY = "LEGACY";
/** 请假审批模块写入。 */
public static final String METHOD_LEAVE = "LEAVE";
/** 签到会话进行中。 */
public static final String SESSION_ACTIVE = "ACTIVE";
/** 课程已经结束,签到会话关闭。 */
public static final String SESSION_ENDED = "ENDED";
private static final Set<String> TEACHER_ADJUSTABLE_STATUSES = new HashSet<>(
Arrays.asList(STATUS_NORMAL, STATUS_LATE, STATUS_ABSENT));
/** 判断目标状态是否允许授课教师在出勤模块内手动设置。 */
public static boolean isTeacherAdjustableStatus(String status) {
return status != null && TEACHER_ADJUSTABLE_STATUSES.contains(status.toUpperCase());
}
/** 正常和迟到均视为实际到课;请假不属于实际到课。 */
public static boolean isPresent(String status) {
return STATUS_NORMAL.equals(status) || STATUS_LATE.equals(status);
}
......
......@@ -4,25 +4,36 @@ import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
/** 请假类型、申请状态和审批人角色的统一常量定义。 */
public final class LeaveConstants {
private LeaveConstants() {
}
/** 病假,必须提供至少一份证明材料。 */
public static final String TYPE_SICK = "SICK";
/** 事假。 */
public static final String TYPE_PERSONAL = "PERSONAL";
/** 其他类型请假。 */
public static final String TYPE_OTHER = "OTHER";
/** 待教师或管理员审批。 */
public static final String STATUS_PENDING = "PENDING";
/** 已批准,关联课程出勤状态同步为LEAVE。 */
public static final String STATUS_APPROVED = "APPROVED";
/** 已拒绝。 */
public static final String STATUS_REJECTED = "REJECTED";
/** 学员在审批前主动撤回。 */
public static final String STATUS_WITHDRAWN = "WITHDRAWN";
/** 教师审批。 */
public static final String ROLE_TEACHER = "TEACHER";
/** 管理员审批。 */
public static final String ROLE_ADMIN = "ADMIN";
private static final Set<String> TYPES = new HashSet<>(
Arrays.asList(TYPE_SICK, TYPE_PERSONAL, TYPE_OTHER));
/** 判断请求中的请假类型是否为系统支持值。 */
public static boolean isSupportedType(String type) {
return type != null && TYPES.contains(type);
}
......
package com.platform.business.constant;
/**
* 消息中心的RabbitMQ拓扑、事务发件箱状态和Redis key统一约定。
*
* <p>集中维护名称可避免生产者、消费者和部署脚本使用不同字符串。修改交换机或队列名称时,
* 需要同步考虑线上旧队列中的积压消息和滚动发布期间的新旧版本兼容。</p>
*/
public final class NotificationConstants {
private NotificationConstants() {
}
/** 业务通知Topic交换机,接收notification.*路由键。 */
public static final String EVENT_EXCHANGE = "notification.events.x";
/** 持久化消费者队列,每个事件只由一个实例落库。 */
public static final String EVENT_QUEUE = "notification.persist.q";
/** 消息事件队列的Topic绑定规则。 */
public static final String EVENT_ROUTING_PATTERN = "notification.#";
/** 消费失败后的重试交换机。 */
public static final String RETRY_EXCHANGE = "notification.retry.x";
/** 固定等待30秒的TTL重试队列。 */
public static final String RETRY_QUEUE = "notification.retry.30s.q";
public static final String RETRY_ROUTING_KEY = "notification.retry.30s";
/** 超过最大重试次数后使用的死信交换机。 */
public static final String DEAD_EXCHANGE = "notification.dead.x";
/** 保留异常报文、供人工排查和补偿的死信队列。 */
public static final String DEAD_QUEUE = "notification.dead.q";
public static final String DEAD_ROUTING_KEY = "notification.dead";
/** 在线推送Direct交换机,routing key为WebSocket节点ID。 */
public static final String PUSH_EXCHANGE = "notification.push.x";
/** 发件箱等待发布。 */
public static final String OUTBOX_NEW = "NEW";
/** 发件箱已被某个服务实例抢占。 */
public static final String OUTBOX_PUBLISHING = "PUBLISHING";
/** RabbitMQ已确认接收。 */
public static final String OUTBOX_PUBLISHED = "PUBLISHED";
/** 发布失败,等待指数退避后重试。 */
public static final String OUTBOX_RETRY = "RETRY";
/** 达到最大次数,不再自动重试。 */
public static final String OUTBOX_FAILED = "FAILED";
/** 用户在线节点Hash前缀,完整key为前缀加userId。 */
public static final String PRESENCE_KEY_PREFIX = "notification:presence:";
/** 一次性WebSocket票据key前缀。 */
public static final String TICKET_KEY_PREFIX = "notification:ticket:";
/** RabbitMQ报文头中的应用级重试次数。 */
public static final String RETRY_HEADER = "x-notification-retry";
}
......@@ -34,6 +34,7 @@ import java.util.Calendar;
import java.util.Date;
import java.util.List;
/** 出勤管理三端接口;人员身份统一从JWT解析,不接收前端传入的人员编号。 */
@Api(tags = "出勤管理")
@RestController
@RequestMapping("/attendance")
......@@ -109,6 +110,7 @@ public class AttendanceController extends BaseController {
return Result.data(attendanceService.querySummary(query));
}
/** 校验当前用户是否具备管理员角色。 */
private void requireAdmin(UserEntity user) {
List<SysPhoneRoleEntity> roles = sysPhoneRoleService.queryByPhone(user.getPhoneNumber());
boolean admin = roles != null && roles.stream().anyMatch(role -> "管理员".equals(role.getRoleName()));
......@@ -117,6 +119,7 @@ public class AttendanceController extends BaseController {
}
}
/** 管理端未传日期时默认查询当月1日至当前时间。 */
private void applyDefaultDateRange(AttendanceQueryDTO query) {
if (query.getStartDate() != null || query.getEndDate() != null) {
return;
......@@ -131,6 +134,7 @@ public class AttendanceController extends BaseController {
query.setEndDate(new Date());
}
/** 从Authorization头解析手机号,再查询系统用户ID作为业务人员标识。 */
private UserEntity currentUser(HttpServletRequest request) {
String token = request.getHeader("Authorization");
if (token == null || token.trim().isEmpty()) {
......@@ -154,6 +158,10 @@ public class AttendanceController extends BaseController {
return user;
}
/**
* 获取服务端认可的客户端IP。
* 仅在明确信任且网关会清洗转发头时读取X-Forwarded-For/X-Real-IP。
*/
private String resolveClientIp(HttpServletRequest request) {
String ip = null;
if (attendanceProperties.isTrustForwardedHeaders()) {
......
......@@ -34,6 +34,7 @@ import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import java.util.List;
/** 请假管理三端接口;学员和教师的数据范围均由当前JWT用户强制限定。 */
@Api(tags = "请假管理")
@RestController
@RequestMapping("/leave")
......@@ -151,12 +152,14 @@ public class LeaveController extends BaseController {
admin.getId(), LeaveConstants.ROLE_ADMIN));
}
/** 启动请假列表分页,缺省为第1页、每页10条。 */
private void startLeavePage(LeaveQueryDTO query) {
int pageNum = query.getPageNum() == null || query.getPageNum() < 1 ? 1 : query.getPageNum();
int pageSize = query.getPageSize() == null || query.getPageSize() < 1 ? 10 : query.getPageSize();
startPage(pageNum, pageSize);
}
/** 校验请假附件的大小和扩展名,限制为原型约定的图片或PDF。 */
private void validateAttachment(MultipartFile file) {
if (file == null || file.isEmpty()) {
throw new BusinessException("证明材料不能为空");
......@@ -173,6 +176,7 @@ public class LeaveController extends BaseController {
}
}
/** 校验当前用户是否具备管理员角色。 */
private void requireAdmin(UserEntity user) {
List<SysPhoneRoleEntity> roles = sysPhoneRoleService.queryByPhone(user.getPhoneNumber());
boolean admin = roles != null && roles.stream().anyMatch(role -> "管理员".equals(role.getRoleName()));
......@@ -181,6 +185,7 @@ public class LeaveController extends BaseController {
}
}
/** 从Authorization头解析手机号,并以用户表ID作为后续业务人员标识。 */
private UserEntity currentUser(HttpServletRequest request) {
String token = request.getHeader("Authorization");
if (token == null || token.trim().isEmpty()) {
......
package com.platform.business.controller;
import com.platform.business.model.dto.NotificationMessageQueryDTO;
import com.platform.business.model.dto.NotificationPublishDTO;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.NotificationMessageVO;
import com.platform.business.model.vo.NotificationSocketTicketVO;
import com.platform.business.service.AuthenticatedUserService;
import com.platform.business.service.NotificationMessageService;
import com.platform.business.service.NotificationSocketTicketService;
import com.platform.controller.BaseController;
import com.platform.model.resp.Result;
import com.platform.page.TableDataInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
/**
* 管理端、教师端和学员端共用的消息中心HTTP接口。
*
* <p>普通操作只能作用于JWT对应用户;只有管理员可以调用发布接口。WebSocket仅负责提示,
* 所有读取、已读和删除操作仍经过这里的数据归属校验。</p>
*/
@Api(tags = "三端消息中心")
@RestController
@RequestMapping("/message")
public class NotificationMessageController extends BaseController {
@Resource
private NotificationMessageService messageService;
@Resource
private NotificationSocketTicketService ticketService;
@Resource
private AuthenticatedUserService authenticatedUserService;
@ApiOperation("分页查询当前用户消息")
@PostMapping("/page")
public TableDataInfo page(@RequestBody(required = false) NotificationMessageQueryDTO query,
HttpServletRequest request) {
UserEntity user = authenticatedUserService.current(request);
NotificationMessageQueryDTO safeQuery = query == null ? new NotificationMessageQueryDTO() : query;
// 无条件覆盖客户端userId,杜绝通过请求体查询其他用户消息。
safeQuery.setUserId(user.getId());
int pageNum = safeQuery.getPageNum() == null || safeQuery.getPageNum() < 1 ? 1 : safeQuery.getPageNum();
// 最大100条用于限制单次正文数据量和数据库压力。
int pageSize = safeQuery.getPageSize() == null || safeQuery.getPageSize() < 1 ? 10
: Math.min(safeQuery.getPageSize(), 100);
startPage(pageNum, pageSize);
return getDataTable(messageService.query(safeQuery));
}
@ApiOperation("查看消息详情并标记已读")
@GetMapping("/{messageId}")
public Result<NotificationMessageVO> detail(@PathVariable String messageId, HttpServletRequest request) {
return Result.data(messageService.detailAndMarkRead(messageId,
authenticatedUserService.current(request).getId()));
}
@ApiOperation("标记单条消息已读")
@PutMapping("/{messageId}/read")
public Result<Boolean> markRead(@PathVariable String messageId, HttpServletRequest request) {
return Result.data(messageService.markRead(messageId,
authenticatedUserService.current(request).getId()));
}
@ApiOperation("全部标记已读")
@PutMapping("/read-all")
public Result<Integer> markAllRead(HttpServletRequest request) {
return Result.data(messageService.markAllRead(authenticatedUserService.current(request).getId()));
}
@ApiOperation("获取未读消息数")
@GetMapping("/unread/count")
public Result<Long> unreadCount(HttpServletRequest request) {
return Result.data(messageService.unreadCount(authenticatedUserService.current(request).getId()));
}
@ApiOperation("删除当前用户的单条消息")
@DeleteMapping("/{messageId}")
public Result<Boolean> delete(@PathVariable String messageId, HttpServletRequest request) {
return Result.data(messageService.delete(messageId,
authenticatedUserService.current(request).getId()));
}
@ApiOperation("清空当前用户已读消息")
@DeleteMapping("/read")
public Result<Integer> clearRead(HttpServletRequest request) {
return Result.data(messageService.clearRead(authenticatedUserService.current(request).getId()));
}
@ApiOperation("申请一次性消息 WebSocket 连接票据")
@PostMapping("/socket-ticket")
public Result<NotificationSocketTicketVO> socketTicket(HttpServletRequest request) {
// 只有先通过JWT认证才能得到一次性WebSocket票据。
return Result.data(ticketService.issue(authenticatedUserService.current(request).getId()));
}
@ApiOperation("管理端发布或预约发布消息")
@PostMapping("/admin/publish")
public Result<String> publish(@RequestBody NotificationPublishDTO body, HttpServletRequest request) {
UserEntity admin = authenticatedUserService.current(request);
// 发布权限单独校验,不以路由名称或前端入口作为可信权限边界。
authenticatedUserService.requireAdmin(admin);
return Result.data(messageService.publish(body, admin.getId(), admin.getNickName()));
}
}
package com.platform.business.duplex;
import com.alibaba.fastjson2.JSON;
import com.platform.business.service.NotificationPresenceService;
import com.platform.business.service.NotificationSocketTicketService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import javax.annotation.Resource;
import javax.websocket.CloseReason;
import javax.websocket.EndpointConfig;
import javax.websocket.OnClose;
import javax.websocket.OnError;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.PathParam;
import javax.websocket.server.ServerEndpoint;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
/**
* 消息中心专用 WebSocket。一个用户可以同时存在多个浏览器标签页和多个节点连接。
* 长连接只传轻量通知,已读、删除和详情仍通过有权限校验的 HTTP 接口完成。
*/
@ServerEndpoint("/notification/websocket/{userId}")
@Component
@Slf4j
public class NotificationWebSocketServer {
/**
* 本节点连接表:userId -> (connectionId -> endpoint实例)。
* 二级Map允许同一账号同时登录多个设备或打开多个标签页,所有连接都会收到实时通知。
*/
private static final ConcurrentHashMap<String, ConcurrentHashMap<String, NotificationWebSocketServer>> CONNECTIONS
= new ConcurrentHashMap<>();
/** JSR-356端点由Web容器创建实例,因此通过Spring实例方法注入到静态引用。 */
private static NotificationSocketTicketService ticketService;
private static NotificationPresenceService presenceService;
/** 当前连接对应的容器Session。 */
private Session session;
/** 由一次性票据认证得到的用户ID,而不是直接信任URL参数。 */
private String userId;
/** 当前物理连接的唯一ID,用于区分同一用户的多个标签页。 */
private String connectionId;
@Resource
public void setTicketService(NotificationSocketTicketService service) {
NotificationWebSocketServer.ticketService = service;
}
@Resource
public void setPresenceService(NotificationPresenceService service) {
NotificationWebSocketServer.presenceService = service;
}
@OnOpen
public void onOpen(Session session, @PathParam("userId") String pathUserId, EndpointConfig config) {
// 票据必须存在、未过期、未使用,并且票据用户必须与路径用户一致。
String ticket = first(session.getRequestParameterMap().get("ticket"));
String authenticatedUserId = ticketService == null ? null : ticketService.consume(ticket);
if (authenticatedUserId == null || !authenticatedUserId.equals(pathUserId)) {
close(session, CloseReason.CloseCodes.VIOLATED_POLICY, "连接票据无效或已过期");
return;
}
this.session = session;
this.userId = authenticatedUserId;
this.connectionId = UUID.randomUUID().toString().replace("-", "");
// 限制空闲时长和入站报文大小;通知连接不承载大正文或文件。
session.setMaxIdleTimeout(150_000L);
session.setMaxTextMessageBufferSize(4 * 1024);
session.getAsyncRemote().setSendTimeout(5_000L);
// 先登记本地连接,再发布Redis在线位置,避免节点收到推送时本地Session尚不可用。
CONNECTIONS.computeIfAbsent(userId, ignored -> new ConcurrentHashMap<>())
.put(connectionId, this);
if (presenceService != null) {
presenceService.register(userId, connectionId);
}
// 明确回复连接成功事件,前端可在此后拉取未读消息完成离线补偿。
Map<String, Object> connected = new HashMap<>();
connected.put("eventType", "CONNECTED");
connected.put("connectionId", connectionId);
sendText(JSON.toJSONString(connected));
log.info("消息 WebSocket 已连接: userId={}, connectionId={}, localConnections={}",
userId, connectionId, localConnectionCount());
}
@OnMessage
public void onMessage(String message) {
// 业务读写全部走HTTP接口;文本通道仅保留应用层PING/PONG用于浏览器主动探活。
if ("PING".equalsIgnoreCase(message)) {
sendText("{\"eventType\":\"PONG\"}");
}
}
@OnClose
public void onClose(CloseReason reason) {
// removeConnection具有幂等性,与onError并发执行也不会误删其他连接。
removeConnection();
log.info("消息 WebSocket 已断开: userId={}, connectionId={}, reason={}",
userId, connectionId, reason == null ? "unknown" : reason.getReasonPhrase());
}
@OnError
public void onError(Throwable error) {
log.warn("消息 WebSocket 异常: userId={}, connectionId={}, error={}",
userId, connectionId, error == null ? "unknown" : error.getMessage());
removeConnection();
}
public static int sendToLocalUser(String targetUserId, String message) {
Map<String, NotificationWebSocketServer> userConnections = CONNECTIONS.get(targetUserId);
if (userConnections == null || userConnections.isEmpty()) {
return 0;
}
// 向该用户在本节点上的每个Session异步发送,返回成功提交到异步队列的连接数。
AtomicInteger accepted = new AtomicInteger();
userConnections.values().forEach(endpoint -> {
if (endpoint.sendText(message)) {
accepted.incrementAndGet();
}
});
return accepted.get();
}
public static boolean isLocalUserOnline(String targetUserId) {
Map<String, NotificationWebSocketServer> connections = CONNECTIONS.get(targetUserId);
return connections != null && !connections.isEmpty();
}
public static int localConnectionCount() {
return CONNECTIONS.values().stream().mapToInt(Map::size).sum();
}
public static void heartbeatAll() {
// WebSocket Ping帧由浏览器协议栈自动响应,无需前端JavaScript手动处理。
CONNECTIONS.values().forEach(userConnections -> userConnections.values().forEach(endpoint -> {
if (endpoint.session == null || !endpoint.session.isOpen()) {
endpoint.removeConnection();
return;
}
try {
endpoint.session.getAsyncRemote().sendPing(ByteBuffer.wrap(new byte[]{1}));
// 只有心跳发送成功后才刷新Redis位置,避免把失效Session继续标记为在线。
if (presenceService != null) {
presenceService.refresh(endpoint.userId, endpoint.connectionId);
}
} catch (IOException e) {
endpoint.removeConnection();
close(endpoint.session, CloseReason.CloseCodes.CLOSED_ABNORMALLY, "心跳失败");
}
}));
}
private boolean sendText(String message) {
if (session == null || !session.isOpen()) {
removeConnection();
return false;
}
try {
// 使用AsyncRemote避免某个慢客户端阻塞RabbitMQ消费线程和其他用户推送。
session.getAsyncRemote().sendText(message, result -> {
if (!result.isOK()) {
log.warn("消息 WebSocket 异步发送失败: userId={}, connectionId={}", userId, connectionId);
}
});
return true;
} catch (RuntimeException e) {
log.warn("消息 WebSocket 发送失败: userId={}, connectionId={}, error={}",
userId, connectionId, e.getMessage());
removeConnection();
return false;
}
}
private void removeConnection() {
if (userId == null || connectionId == null) {
return;
}
ConcurrentHashMap<String, NotificationWebSocketServer> userConnections = CONNECTIONS.get(userId);
if (userConnections != null) {
// 带value参数的remove可避免旧端点误删同connectionId下已经替换的新实例。
userConnections.remove(connectionId, this);
if (userConnections.isEmpty()) {
CONNECTIONS.remove(userId, userConnections);
}
}
if (presenceService != null) {
presenceService.unregister(userId, connectionId);
}
}
private static String first(List<String> values) {
return values == null || values.isEmpty() ? null : values.get(0);
}
private static void close(Session session, CloseReason.CloseCode code, String reason) {
if (session == null || !session.isOpen()) {
return;
}
try {
session.close(new CloseReason(code, reason));
} catch (IOException ignored) {
// 连接本身已不可用,无需再次处理。
}
}
}
......@@ -13,35 +13,41 @@ import org.apache.ibatis.annotations.Param;
import java.util.List;
/**
* @Author: wujipeng
* @Description: TODO
* @Date: 2026/8/3 11:33
* @Version: 1.0
*/
/** 出勤记录写入、加锁查询及多维统计的数据访问接口。 */
@Mapper
public interface ClassSubjectAttendanceMapper extends BaseMapper<ClassSubjectAttendanceEntity> {
/** 兼容原有按本人查询签到记录的接口。 */
List<ClassSubjectAttendanceEntity> queryOneself(ClassDTO classDTO);
/** 幂等插入签到记录;课程与学员重复时忽略,用于处理并发签到。 */
int insertIgnore(ClassSubjectAttendanceEntity record);
/** 批量补写课程结束时仍缺少记录的学员为缺勤,重复记录忽略。 */
int insertAbsencesIgnore(@Param("records") List<ClassSubjectAttendanceEntity> records);
/** 教师手动调整状态;数据库层保护已批准的请假状态不被覆盖。 */
int upsertTeacherStatus(ClassSubjectAttendanceEntity record);
/** 审批前锁定指定学员在全部关联课程中的记录,协调签到与审批并发。 */
List<ClassSubjectAttendanceEntity> lockRecords(@Param("subjectIds") List<Integer> subjectIds,
@Param("userId") String userId);
/** 批量写入请假状态;若已存在正常或迟到签到则保留原出勤状态。 */
int upsertLeaveStatuses(@Param("records") List<ClassSubjectAttendanceEntity> records);
/** 按条件查询完整出勤记录及人员手机号。 */
List<AttendanceRecordVO> queryRecords(AttendanceQueryDTO query);
/** 查询教师课程点名册,尚无记录的学员状态显示为PENDING。 */
List<AttendanceRecordVO> queryTeacherRoster(@Param("subjectId") Integer subjectId);
/** 查询筛选范围内的总出勤统计。 */
AttendanceSummaryVO querySummary(AttendanceQueryDTO query);
/** 查询按学员维度的出勤统计。 */
List<AttendanceStudentStatisticsVO> queryStudentStatistics(AttendanceQueryDTO query);
/** 查询按课程维度的出勤统计。 */
List<AttendanceCourseStatisticsVO> queryCourseStatistics(AttendanceQueryDTO query);
}
......@@ -4,7 +4,9 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.platform.business.model.entity.ClassSubjectAttendanceSessionEntity;
import org.apache.ibatis.annotations.Mapper;
/** 课程签到会话的数据访问接口。 */
@Mapper
public interface ClassSubjectAttendanceSessionMapper extends BaseMapper<ClassSubjectAttendanceSessionEntity> {
/** 幂等创建会话,依靠课程唯一索引保证验证码只能生成一次。 */
int insertIgnore(ClassSubjectAttendanceSessionEntity session);
}
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