Initial commit: DataTool backend, frontend and Docker

docs/03-WebSocket连接管理（连接-订阅-心跳-重连）.md

@@ -0,0 +1,49 @@
+# 03 - WebSocket连接管理（连接 / 订阅 / 心跳 / 重连）
+
+## 功能目标
+- 建立浏览器到服务端的 WebSocket 连接（SockJS + STOMP）。
+- 订阅房间广播通道，实时接收消息。
+- 具备心跳保活与自动重连；UI 显示连接状态。
+
+## 前端（Vue）
+- **封装层**：`src/api/websocket.js`
+  - `connect(url, onConnect, onError)`：创建 STOMP Client，启用 `reconnectDelay` 与心跳参数。
+  - `subscribe(destination, callback)`：按 destination 保存订阅，便于统一退订。
+  - `send(destination, body)`：publish JSON 消息。
+  - `disconnect()`：取消订阅并关闭连接。
+- **连接时序（建议）**
+  1. connect 成功
+  2. subscribe `/topic/room/{roomCode}`
+  3. send `/app/room/{roomCode}/join`
+  4. 开始收发消息
+- **连接状态 UI**
+  - 显示：连接中 / 已连接 / 断开 / 重连中
+  - 重连成功后：自动重新 subscribe + 重新 join
+
+## 后端（Spring Boot）
+- **WebSocket 配置**
+  - 端点：`/ws/data-transfer`
+  - broker：`/topic`
+  - 应用前缀：`/app`
+  - SockJS：`.withSockJS()`
+- **跨域与握手**
+  - `setAllowedOriginPatterns("*")`（开发期）
+  - 生产期建议：限制 Origin + 启用 WSS
+- **心跳**
+  - 与前端 STOMP 心跳保持一致（如需更严格，改用外部 broker 或自定义心跳策略）
+
+## 协议与通道
+- 订阅（接收）
+  - `/topic/room/{roomCode}`：房间内通用消息广播
+  - `/topic/room/{roomCode}/file/{fileId}`：某文件分片通道（可选设计）
+- 发送（服务端处理）
+  - `/app/room/{roomCode}/join`
+  - `/app/room/{roomCode}/leave`
+  - `/app/room/{roomCode}/message`
+  - `/app/room/{roomCode}/file/chunk`
+
+## 边界与注意点
+- **重连后的状态恢复**：需要重新 join 才能恢复在线用户列表与系统消息一致性。
+- **订阅泄漏**：房间切换、页面卸载必须 disconnect/退订，避免重复订阅造成重复消息。
+- **代理/反代**：生产 Nginx 需支持 Upgrade，`/ws` 走 ws 反代。
+