NOTIFICATION_README.md 9.3 KB
消息通知系统使用说明
概述
本项目集成了一套完整的消息通知系统，支持WebSocket实时推送和数据库存储，提供便捷的消息管理功能。
功能特性
- ✅ 实时推送: 基于WebSocket + STOMP协议
- ✅ 消息持久化: MySQL数据库存储
- ✅ 多种消息类型: 系统通知、任务通知、报告通知、警告通知、提醒通知
- ✅ 消息管理: 已读/未读状态管理、删除、统计
- ✅ 批量操作: 批量发送、批量标记已读、批量删除
- ✅ 优先级支持: 低、普通、高、紧急四个级别
- ✅ 自动清理: 定时清理过期消息
- ✅ 业务关联: 支持业务ID和业务类型关联
- ✅ 工具类支持: 提供静态方法便捷调用
系统架构
前端页面
↓ (WebSocket)
消息推送服务 (WebSocketService)
↓
消息服务 (NotificationService)
↓
数据库存储 (MySQL)
↓
定时清理 (NotificationCleanupTask)
快速开始
1. 数据库初始化
执行SQL脚本创建相关表：
-- 运行 /sql/notification.sql 文件
2. 启动应用
确保Spring Boot应用正常启动，WebSocket会自动配置。
3. 前端集成
参考 frontend/websocket-example.html 文件进行前端集成。
API接口
消息管理接口
获取消息列表
GET /api/notification/list?current=1&size=20&messageType=SYSTEM&status=UNREAD
获取未读消息数量
GET /api/notification/unread-count
标记消息为已读
POST /api/notification/read/{messageId}
批量标记已读
POST /api/notification/read/batch
Content-Type: application/json
[1, 2, 3, 4, 5]
标记全部已读
POST /api/notification/read/all
删除消息
DELETE /api/notification/{messageId}
获取消息统计
GET /api/notification/statistics
消息发送接口
发送系统通知
POST /api/message/system
Content-Type: application/json
{
"receiverId": 1001,
"title": "系统维护通知",
"content": "系统将于今晚22:00进行维护",
"businessId": "SYS_MAINTENANCE_001",
"businessType": "SYSTEM_MAINTENANCE"
}
发送任务通知
POST /api/message/task
Content-Type: application/json
{
"receiverId": 1001,
"title": "新任务分配",
"content": "您有一个新的影像诊断任务",
"businessId": "TASK_12345"
}
发送报告通知
POST /api/message/report
Content-Type: application/json
{
"receiverId": 1001,
"title": "诊断报告已完成",
"content": "患者张三的影像诊断报告已完成",
"businessId": "REPORT_54321"
}
批量发送系统通知
POST /api/message/system/batch
Content-Type: application/json
{
"receiverIds": [1001, 1002, 1003],
"title": "系统升级通知",
"content": "系统已升级到新版本，请查看更新内容"
}
代码集成
1. 使用Service方式
@Autowired
private NotificationService notificationService;
// 发送系统通知
Long messageId = notificationService.sendSystemNotification(
userId,
"标题",
"内容"
);
// 发送任务通知
Long messageId = notificationService.sendTaskNotification(
userId,
"任务标题",
"任务内容",
businessId
);
// 批量发送
int count = notificationService.batchSendNotification(
userIdList,
"标题",
"内容",
"SYSTEM"
);
2. 使用工具类（推荐）
import static com.zskk.pacsonline.modules.notification.util.NotificationUtil.*;
// 发送系统通知
sendSystemNotification(userId, "标题", "内容");
// 发送带业务ID的系统通知
sendSystemNotification(userId, "标题", "内容", businessId, "REPORT");
// 发送任务通知
sendTaskNotification(userId, "任务标题", "任务内容", businessId);
// 发送报告通知
sendReportNotification(userId, "报告标题", "报告内容", businessId);
// 发送警告通知
sendWarningNotification(userId, "警告标题", "警告内容");
// 批量发送
List<Long> userIds = Arrays.asList(1001L, 1002L, 1003L);
sendToMultipleUsers(userIds, "标题", "内容", "SYSTEM");
3. 在Controller中使用
@RestController
public class ReportController {
@Autowired
private NotificationService notificationService;
@PostMapping("/report/complete")
public RestResult<String> completeReport(@RequestBody CompleteReportRequest request) {
// 业务逻辑处理
reportService.completeReport(request);
// 发送通知给申请人
notificationService.sendReportNotification(
request.getApplicantId(),
"诊断报告已完成",
String.format("患者%s的影像诊断报告已完成，请及时查看", request.getPatientName()),
request.getReportId()
);
return RestResult.success("报告完成通知已发送");
}
}
WebSocket连接
连接信息
- WebSocket URL:
ws://localhost:8080/ws-notification - HTTP URL:
http://localhost:8080/ws-notification - 协议: STOMP over WebSocket
连接示例（JavaScript）
// 连接WebSocket
const socket = new SockJS('http://localhost:8080/ws-notification');
const stompClient = Stomp.over(socket);
// 设置认证头
const headers = {
'Authorization': 'Bearer ' + token
};
stompClient.connect(headers, function(frame) {
console.log('连接成功: ' + frame);
// 订阅个人消息
stompClient.subscribe('/user/queue/notifications', function(message) {
const data = JSON.parse(message.body);
console.log('收到消息: ', data);
// 处理消息显示
});
// 订阅系统消息
stompClient.subscribe('/user/queue/system', function(message) {
const data = JSON.parse(message.body);
console.log('收到系统消息: ', data);
});
// 订阅广播消息
stompClient.subscribe('/topic/broadcast', function(message) {
const data = JSON.parse(message.body);
console.log('收到广播消息: ', data);
});
});
消息格式
通知消息格式
{
"type": "NOTIFICATION",
"data": {
"id": 1234567890,
"receiverId": 1001,
"receiverName": "张医生",
"messageType": "REPORT",
"title": "诊断报告已完成",
"content": "患者李四的影像诊断报告已完成",
"priority": "HIGH",
"status": "UNREAD",
"businessId": "REPORT_54321",
"businessType": "REPORT",
"sendTime": "2023-12-01 10:30:00"
},
"timestamp": 1701426600000
}
系统消息格式
{
"type": "SYSTEM_MESSAGE",
"title": "系统维护通知",
"content": "系统将于今晚22:00进行维护",
"timestamp": 1701426600000
}
消息类型说明
| 类型 | 说明 | 优先级 | 过期时间 |
|---|---|---|---|
| SYSTEM | 系统通知 | 普通 | 7天 |
| TASK | 任务通知 | 普通 | 30天 |
| REPORT | 报告通知 | 高 | 30天 |
| MESSAGE | 普通消息 | 普通 | 30天 |
| REMINDER | 提醒通知 | 普通 | 30天 |
| WARNING | 警告通知 | 高 | 3天 |
优先级说明
| 级别 | 说明 | 显示效果 |
|---|---|---|
| LOW | 低 | 普通显示 |
| NORMAL | 普通 | 普通显示 |
| HIGH | 高 | 红色标记 |
| URGENT | 紧急 | 红色标记 + 弹窗提醒 |
状态说明
| 状态 | 说明 |
|---|---|
| UNREAD | 未读 |
| READ | 已读 |
| ARCHIVED | 已归档 |
配置说明
application.yaml配置
# 消息通知配置
notification:
# 默认过期时间（小时）
default-expire-hours: 720 # 30天
# 系统消息过期时间（小时）
system-expire-hours: 168 # 7天
# 警告消息过期时间（小时）
warning-expire-hours: 72 # 3天
# 批量发送限制
batch-limit: 1000
# WebSocket连接心跳间隔（秒）
heartbeat-interval: 30
性能优化建议
- 数据库索引: 确保相关字段有索引
- 消息分页: 避免一次性加载过多消息
- 定期清理: 自动清理过期消息
- 缓存策略: 可结合Redis缓存未读数量
- 批量操作: 使用批量API提高效率
监控和日志
关键日志
- 消息发送成功/失败
- WebSocket连接状态
- 数据库操作异常
- 定时任务执行情况
监控指标
- 消息发送量
- WebSocket连接数
- 未读消息统计
- 系统性能指标
故障排除
常见问题
WebSocket连接失败
- 检查Token是否正确
- 检查网络连接
- 查看浏览器控制台错误
消息未收到
- 检查用户是否在线
- 检查消息是否已过期
- 查看后端日志
数据库查询慢
- 检查索引是否正确
- 优化SQL查询
- 考虑分页查询
扩展开发
自定义消息类型
- 在
NotificationConstants中添加新的消息类型 - 在Service中添加对应的发送方法
- 更新数据库表类型约束
自定义推送渠道
- 实现
MessagePushService接口 - 在
NotificationService中调用自定义推送服务 - 配置相关参数
示例代码
完整的使用示例请参考：
frontend/websocket-example.html- 前端集成示例- 各个Controller中的实际使用案例
技术支持
如有问题，请联系开发团队或查看项目文档。