初始化

rdms-framework/rdms-spring-boot-starter-websocket/README.md

@@ -0,0 +1,196 @@
+# rdms-spring-boot-starter-websocket
+
+## 1. 模块定位
+
+`rdms-spring-boot-starter-websocket` 是 WebSocket 基础设施模块，用于统一处理连接、会话管理、消息分发与消息发送，并支持多节点场景下的广播投递。
+
+模块聚合的核心能力：
+
+- WebSocket 自动装配与路径注册
+- 登录用户绑定与会话管理
+- JSON 消息协议与监听器分发
+- 消息发送与多节点广播
+
+## 2. 设计思路
+
+- 统一 JSON 消息协议（`type` + `content`），通过 `type` 分发到对应监听器，降低业务耦合。
+- 通过 `WebSocketSessionManager` 统一管理会话，支持按用户类型/用户编号/会话 ID 进行推送。
+- 通过可插拔 `sender-type` 支持单机与多节点广播（local/redis/rocketmq/rabbitmq/kafka）。
+- 与安全体系结合，在握手阶段写入 `LoginUser`，便于后续鉴权与定向发送。
+
+## 3. 功能模块
+
+### 3.1 自动装配
+
+`RdmsWebSocketAutoConfiguration` 会完成：
+
+- 注册 WebSocket 路径与处理器
+- 注册握手拦截器（默认 `LoginUserHandshakeInterceptor`）
+- 注册 `WebSocketSessionManager`
+- 放行 WebSocket 路径的安全校验
+- 注册消息发送器（按 `sender-type`）
+
+### 3.2 JSON 消息协议
+
+内置统一消息结构：
+
+```json
+{
+  "type": "notice",
+  "content": "{...}"
+}
+```
+
+处理流程：
+
+- `JsonWebSocketMessageHandler` 解析 JSON
+- 根据 `type` 选择对应 `WebSocketMessageListener`
+- 将 `content` 反序列化为监听器泛型类型并交给业务处理
+
+内置 `ping/pong`：收到 `ping` 会直接返回 `pong`。
+
+### 3.3 会话管理
+
+`WebSocketSessionManager` 支持：
+
+- 按 `sessionId` 获取会话
+- 按 `userType` 获取会话列表
+- 按 `userType + userId` 获取会话列表
+
+用于定向推送和广播推送。
+
+### 3.4 消息发送
+
+统一使用 `WebSocketMessageSender` 发送消息：
+
+- 按用户推送
+- 按用户类型广播
+- 按会话 ID 推送
+
+消息会被封装为统一的 `JsonWebSocketMessage` 后发送。
+
+### 3.5 多节点广播
+
+`sender-type` 支持以下类型：
+
+- `local`：单机直连（默认）
+- `redis` / `rocketmq` / `rabbitmq` / `kafka`：通过 MQ 广播到各实例，再由各实例推送到本机会话
+
+### 3.6 登录用户绑定
+
+握手阶段会读取当前登录用户并写入 WebSocket Session：
+
+- 需要前端通过 `?token={token}` 形式携带令牌
+- `LoginUserHandshakeInterceptor` 会将 `LoginUser` 写入 Session
+- `WebSocketFrameworkUtils` 可获取 `userId/userType/tenantId`
+
+## 4. 开发人员上手
+
+### 4.1 引入依赖
+
+```xml
+<dependency>
+    <groupId>com.njcn</groupId>
+    <artifactId>rdms-spring-boot-starter-websocket</artifactId>
+</dependency>
+```
+
+### 4.2 基础配置
+
+```yaml
+rdms:
+  websocket:
+    enable: true
+    path: /ws
+    sender-type: local
+```
+
+说明：
+
+- `path` 默认 `/ws`
+- `sender-type` 默认 `local`
+- `enable` 默认 `true`
+
+### 4.3 连接方式
+
+前端连接示例：
+
+```
+ws://{host}:{port}/ws?token={token}
+```
+
+### 4.4 编写消息监听器
+
+```java
+@Component
+public class NoticeMessageListener implements WebSocketMessageListener<NoticeDTO> {
+
+    @Override
+    public void onMessage(WebSocketSession session, NoticeDTO message) {
+        // 处理消息
+    }
+
+    @Override
+    public String getType() {
+        return "notice";
+    }
+}
+```
+
+### 4.5 服务端推送
+
+```java
+@Resource
+private WebSocketMessageSender webSocketMessageSender;
+
+public void push(Long userId, NoticeDTO notice) {
+    webSocketMessageSender.sendObject(UserTypeEnum.ADMIN.getValue(), userId, "notice", notice);
+}
+```
+
+### 4.6 多节点广播配置示例
+
+Redis：
+
+```yaml
+rdms:
+  websocket:
+    sender-type: redis
+```
+
+RocketMQ：
+
+```yaml
+rdms:
+  websocket:
+    sender-type: rocketmq
+    sender-rocketmq:
+      topic: ws-topic
+      consumer-group: ws-group
+```
+
+Kafka：
+
+```yaml
+rdms:
+  websocket:
+    sender-type: kafka
+    sender-kafka:
+      topic: ws-topic
+      consumer-group: ws-group
+```
+
+RabbitMQ：
+
+```yaml
+rdms:
+  websocket:
+    sender-type: rabbitmq
+    sender-rabbitmq:
+      exchange: ws-exchange
+      queue: ws-queue
+```
+
+注意：
+
+- 使用 MQ 模式时，请确保对应 MQ 客户端依赖与连接配置已就绪。