# 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 反代。