# 📘 WebSocket 通讯协议设计文档

## 1. 概述

本协议用于实现 **即时聊天（IM）系统的实时消息传输**。
 客户端通过 WebSocket 连接后与服务器保持长连接，实现消息推送、状态同步、群聊与单聊。

**支持功能**：

- 用户登录鉴权
- 单聊消息发送/接收
- 群聊消息发送/接收
- 消息撤回、已读回执
- 心跳保活与断线重连
- 系统通知（好友请求、群邀请）

------

## 2. 消息传输格式

### 2.1 基础消息结构（JSON）

```
{
  "type": "MESSAGE_TYPE",
  "requestId": "string",        // 客户端生成的请求ID，便于幂等
  "from": 1001,                 // 发送者ID
  "to": 1002,                   // 接收者ID（单聊）或群ID（群聊）
  "chatType": "single",         // "single" | "group"
  "contentType": "text",        // "text" | "image" | "file" | "voice" | "system"
  "content": "消息内容或文件URL", 
  "timestamp": 1700000000       // Unix时间戳
}
```

------

### 2.2 常用 type 枚举

| type           | 说明                      |
| -------------- | ------------------------- |
| AUTH           | 握手鉴权                  |
| HEARTBEAT      | 心跳保活                  |
| MESSAGE        | 普通聊天消息（单聊/群聊） |
| MESSAGE_ACK    | 消息已读/送达回执         |
| MESSAGE_RECALL | 消息撤回                  |
| FRIEND_REQUEST | 好友申请通知              |
| GROUP_INVITE   | 群邀请通知                |
| SYSTEM_NOTICE  | 系统公告/通知             |
| ERROR          | 错误消息                  |

------

## 3. 握手与鉴权

### 3.1 客户端连接

```
ws://example.com/ws?token=xxxx
```

- 客户端通过 Token 鉴权
- 服务器验证 Token 后，返回 AUTH_SUCCESS 或 AUTH_FAIL

### 3.2 服务端响应示例

**成功：**

```
{
  "type": "AUTH",
  "status": "success",
  "userId": 1001,
  "timestamp": 1700000000
}
```

**失败：**

```
{
  "type": "AUTH",
  "status": "fail",
  "code": 1006,
  "message": "Token无效或过期"
}
```

------

## 4. 心跳机制

### 4.1 客户端发送

```
{
  "type": "HEARTBEAT",
  "timestamp": 1700000000
}
```

### 4.2 服务器响应

```
{
  "type": "HEARTBEAT",
  "timestamp": 1700000000
}
```

- **客户端**：每隔 30 秒发送一次心跳
- **服务器**：若 2 倍心跳时间未收到消息，则断开连接

------

## 5. 消息传输

### 5.1 单聊消息

客户端发送：

```
{
  "type": "MESSAGE",
  "requestId": "uuid-001",
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "contentType": "text",
  "content": "你好",
  "timestamp": 1700000000
}
```

服务器推送给接收者：

```
{
  "type": "MESSAGE",
  "messageId": 50001,
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "contentType": "text",
  "content": "你好",
  "timestamp": 1700000000
}
```

------

### 5.2 群聊消息

```
{
  "type": "MESSAGE",
  "requestId": "uuid-002",
  "from": 1001,
  "to": 3001,               // 群ID
  "chatType": "group",
  "contentType": "image",
  "content": "http://img.example.com/xxx.jpg",
  "timestamp": 1700000000
}
```

服务器会 **推送到群成员列表（除了自己）**。

------

### 5.3 消息回执（MESSAGE_ACK）

客户端收到消息后发送：

```
{
  "type": "MESSAGE_ACK",
  "messageId": 50001,
  "from": 1002,
  "to": 1001,
  "chatType": "single",
  "status": "read",
  "timestamp": 1700000000
}
```

服务器更新消息状态，并可推送给发送方。

------

### 5.4 消息撤回（MESSAGE_RECALL）

客户端请求撤回消息：

```
{
  "type": "MESSAGE_RECALL",
  "messageId": 50001,
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "timestamp": 1700000010
}
```

服务器验证是否允许撤回（时间限制、权限等），允许则推送给接收方：

```
{
  "type": "MESSAGE_RECALL",
  "messageId": 50001,
  "from": 1001,
  "chatType": "single",
  "status": "success",
  "timestamp": 1700000010
}
```

------

## 6. 好友 / 群邀请通知

### 6.1 好友申请（FRIEND_REQUEST）

```
{
  "type": "FRIEND_REQUEST",
  "requestId": "uuid-003",
  "from": 1001,
  "to": 1002,
  "content": "加个好友吧",
  "timestamp": 1700000020
}
```

### 6.2 群邀请（GROUP_INVITE）

```
{
  "type": "GROUP_INVITE",
  "inviteId": "uuid-004",
  "groupId": 3001,
  "inviter": 1001,
  "invitee": 1003,
  "content": "邀请你加入群聊",
  "timestamp": 1700000030
}
```

------

## 7. 错误处理（ERROR）

```
{
  "type": "ERROR",
  "code": 2300,
  "message": "消息发送失败",
  "requestId": "uuid-001",
  "timestamp": 1700000040
}
```

- **code** 对应响应 Code 规范
- **requestId** 可帮助客户端确认失败的具体请求

------

## 8. 断线重连

- 客户端断线后，尝试每隔 5 秒重连一次
- 重连成功后，重新发送 AUTH 消息进行鉴权
- 重连后可请求 **未读消息同步**（message 表或 Redis 缓存）

------

## 9. 附录：contentType 示例

| contentType | content 示例                       | 描述              |
| ----------- | ---------------------------------- | ----------------- |
| text        | "你好"                             | 文本消息          |
| image       | "http://img.example.com/xxx.jpg"   | 图片 URL          |
| file        | "http://file.example.com/xxx.pdf"  | 文件 URL + 文件名 |
| voice       | "http://audio.example.com/xxx.mp3" | 语音 URL + 时长   |
| system      | "用户xxx加入群"                    | 系统消息          |