zhibo/模块文档/04-WebSocket通信模块.md

# WebSocket通信模块接口文档

## 模块概述
WebSocket通信模块提供实时弹幕和在线人数的推送功能。

---

## WebSocket连接

### 1. 实时弹幕WebSocket

**连接地址**: `ws://host:port/ws/live/chat/{roomId}`

**连接参数**:
```
roomId: 房间ID (路径参数)
```

**发送消息格式**:
```json
{
  "type": "chat",
  "content": "弹幕内容",
  "nickname": "用户昵称",
  "userId": 用户ID
}
```

**接收消息格式**:

弹幕消息:
```json
{
  "type": "chat",
  "nickname": "用户昵称",
  "content": "弹幕内容"
}
```

连接确认:
```json
{
  "type": "connected",
  "content": "连接成功"
}
```

心跳响应:
```json
{
  "type": "pong"
}
```

**心跳消息**:
```json
{
  "type": "ping"
}
```

**说明**:
- 心跳间隔: 30秒
- 自动重连: 最多5次
- 重连延迟: 5秒 × 重连次数

---

### 2. 在线人数WebSocket

**连接地址**: `ws://host:port/ws/live/{roomId}?clientId={clientId}`

**连接参数**:
```
roomId: 房间ID (路径参数)
clientId: 客户端ID (查询参数，用户ID或guest_时间戳)
```

**接收消息格式**:

在线人数更新:
```json
{
  "type": "online_count",
  "count": 1234,
  "roomId": "房间ID",
  "timestamp": 1704000000000
}
```

连接确认:
```json
{
  "type": "connected",
  "message": "连接成功",
  "clientId": "用户ID或guest_时间戳"
}
```

心跳响应:
```json
{
  "type": "pong"
}
```

**心跳消息**:
```json
{
  "type": "ping"
}
```

**说明**:
- 心跳间隔: 30秒
- 自动重连: 最多5次
- 重连延迟: 5秒 × 重连次数
- 用户进入/离开时自动推送在线人数更新