# 三端消息中心接入说明 ## 部署前置 1. 执行 `sql/message_center.sql`。 2. 使用 RabbitMQ 3.8 或更高版本;持久化事件队列和死信队列使用 quorum queue。 3. 配置 Redis、RabbitMQ 环境变量。消息服务至少部署两个实例时,不要复用 `NOTIFICATION_NODE_ID`。 4. 网关需将 `/notification/websocket/**` 按 WebSocket 协议转发至 `practical-train-business`。 消息正文和每个用户的已读状态以 MySQL 为准。Redis 故障只影响跨节点即时定位和新票据签发;WebSocket 推送失败时,用户重新进入消息中心仍能查询到消息。 ## 前端连接顺序 1. 使用登录 JWT 调用 `POST /message/socket-ticket`。 2. 根据响应的 `endpoint` 建立 `wss://网关地址{endpoint}?ticket={ticket}`。票据 60 秒有效且只能使用一次。 3. 收到 `NOTIFICATION` 后显示右上角弹窗;当 `refreshUnreadCount=true` 时,立即调用 `GET /message/unread/count` 刷新角标。 4. 收到 `UNREAD_COUNT_CHANGED` 时不显示弹窗,重新查询未读数;如果消息中心页面已打开,同时刷新当前列表。 5. 弹窗只使用轻量报文;点击后调用 `GET /message/{messageId}` 获取正文,该接口同时标记已读。 6. 断线后重新申请票据,并重新查询未读列表完成离线补偿。前端按 `messageId` 去重。 数量变化事件在数据库事务提交、Redis旧缓存清除之后才发送。因此客户端收到事件后查询到的是已经提交的权威数量,不能在本地通过 `+1/-1` 维护角标。短时间内连续收到多个刷新事件时,可以在100毫秒左右进行防抖,只执行一次未读数查询。 ### WebSocket事件示例 新消息事件同时负责弹窗和未读数刷新: ```json { "eventType": "NOTIFICATION", "messageId": "消息ID", "messageType": "EXAM", "title": "考试即将开始", "summary": "请提前进入考场", "refreshUnreadCount": true, "changeType": "NEW_MESSAGE" } ``` 已读、全部已读、删除或清空操作会向同一账号的全部在线标签页和设备发送状态事件: ```json { "eventType": "UNREAD_COUNT_CHANGED", "refreshUnreadCount": true, "changeType": "MARK_READ" } ``` ## 三端通用接口 - `POST /message/page`:分页列表,支持 `readStatus`、`messageType`、`keyword`。 - `GET /message/{messageId}`:详情并标记已读。 - `PUT /message/{messageId}/read`:单条已读。 - `PUT /message/read-all`:全部已读。 - `GET /message/unread/count`:未读数。 - `DELETE /message/{messageId}`:仅删除当前用户视图。 - `DELETE /message/read`:清空当前用户已读消息。 - `POST /message/admin/publish`:管理员发布或预约发布消息。 管理员发布请求可组合 `recipientUserIds`、`recipientRoleNames`、`recipientClassIds` 和 `broadcast`。预约时间由 `scheduledAt` 指定。 ## 业务模块接入 考试发布、考试即将开始、成绩发布、请假审批、课程变更等业务类只需要注入 `BusinessNotificationPublisher`。该接口仅存在于 `practical-business` 服务内部,不提供HTTP或Feign入口。 建议在业务数据库事务中调用: ```java @Resource private BusinessNotificationPublisher notificationPublisher; // 与考试发布、请假审批等业务数据处于同一个数据库事务。 notificationPublisher.publish(command, operatorId, operatorName); ``` 该调用只写 `notification_outbox`,不直接访问 RabbitMQ,因此业务提交与通知事件不会发生数据库/MQ双写不一致。后台任务抢占发件箱记录,使用 Publisher Confirm 发布;消费失败进入 30 秒 TTL 重试队列,累计失败后进入死信队列。 系统定时提醒没有人工操作人时,`senderId` 可以传 `null`,`senderName` 使用“系统通知”。原有 `POST /message/admin/publish` 管理员手动发布接口保持不变,并继续执行管理员角色校验。 ## RabbitMQ 拓扑 - `notification.events.x`:Topic Exchange,按 `notification.system`、`notification.exam` 等路由。 - `notification.persist.q`:quorum queue,落库消费者。 - `notification.retry.30s.q`:TTL 重试队列,过期后通过 DLX 返回事件交换机。 - `notification.dead.q`:超过重试次数的死信事件。 - `notification.push.x`:Direct Exchange,routing key 为节点 ID;每个服务节点仅有一个临时推送队列,不会按用户创建队列。