docs: 完善项目文档体系
- 数据库 SQL 所有字段添加 COMMENT 注释，枚举字段详细标注各值含义 - 新增 docs/architecture/ 系统架构文档（分层架构、数据流、演进路径） - API 文档按模块拆分为 8 个独立文档（auth/contact/im/meeting/notify/admin/websocket） - 补充 README.md 项目说明（技术栈、架构、快速开始、功能规划、文档导航） Made-with: Cursor
This commit is contained in:
bujinyuan
397
docs/api/websocket.md
Normal file
397
docs/api/websocket.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# WebSocket 事件协议
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
> 本文档定义 EchoChat 系统中所有 WebSocket 实时通信事件。
|
||||
|
||||
---
|
||||
|
||||
## 连接说明
|
||||
|
||||
### 连接地址
|
||||
|
||||
| 环境 | 地址 |
|
||||
|------|------|
|
||||
| 开发环境 | `ws://localhost:8080/ws?token=<access_token>` |
|
||||
| 生产环境 | `wss://api.echochat.com/ws?token=<access_token>` |
|
||||
|
||||
### 连接认证
|
||||
|
||||
通过 URL 查询参数 `token` 携带 JWT Access Token，服务端验证通过后建立连接。
|
||||
|
||||
### 心跳机制
|
||||
|
||||
- 客户端每 **30 秒** 发送一次 ping 帧
|
||||
- 服务端响应 pong 帧
|
||||
- 如果 **90 秒** 内未收到客户端心跳，服务端主动断开连接
|
||||
|
||||
### 断线重连
|
||||
|
||||
- 客户端检测到连接断开后自动重连
|
||||
- 重连间隔采用指数退避：1s → 2s → 4s → 8s → 16s → 最大 30s
|
||||
- 重连成功后拉取离线消息
|
||||
|
||||
---
|
||||
|
||||
## 消息格式
|
||||
|
||||
### 客户端发送格式
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "im.message.send",
|
||||
"seq": 1001,
|
||||
"data": { ... },
|
||||
"timestamp": 1740700000
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| event | string | 事件名称，格式：`{模块}.{对象}.{动作}` |
|
||||
| seq | int | 消息序列号，客户端自增，用于匹配请求和响应 |
|
||||
| data | object | 事件数据 |
|
||||
| timestamp | int | 发送时间戳（秒） |
|
||||
|
||||
### 服务端响应格式（ACK）
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "im.message.send.ack",
|
||||
"seq": 1001,
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": { "msg_id": 10086 }
|
||||
}
|
||||
```
|
||||
|
||||
### 服务端推送格式
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "im.message.new",
|
||||
"data": { ... },
|
||||
"timestamp": 1740700000
|
||||
}
|
||||
```
|
||||
|
||||
推送类消息没有 seq 字段（不需要客户端确认）。
|
||||
|
||||
---
|
||||
|
||||
## 即时通讯事件
|
||||
|
||||
### im.message.send
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 发送消息到会话
|
||||
|
||||
**data 参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| conversation_id | int | 是 | 目标会话 ID |
|
||||
| type | int | 是 | 消息类型：1=文本，2=图片，3=文件，4=语音 |
|
||||
| content | string | 否 | 文本内容 |
|
||||
| extra | object | 否 | 附加数据（图片/文件信息） |
|
||||
|
||||
**ACK 响应 data：** `{ "msg_id": 10086 }`
|
||||
|
||||
---
|
||||
|
||||
### im.message.new
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 收到新消息推送
|
||||
|
||||
**data 内容：**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 10086,
|
||||
"conversation_id": 1,
|
||||
"sender_id": 2,
|
||||
"sender_name": "李四",
|
||||
"sender_avatar": "https://...",
|
||||
"type": 1,
|
||||
"content": "你好",
|
||||
"extra": {},
|
||||
"created_at": "2026-02-27T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### im.message.revoke
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 撤回消息（发送后 2 分钟内）
|
||||
|
||||
**data 参数：** `{ "message_id": 10086 }`
|
||||
|
||||
---
|
||||
|
||||
### im.message.read
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 消息已读回执
|
||||
|
||||
**data 参数：** `{ "conversation_id": 1, "message_id": 10086 }`
|
||||
|
||||
---
|
||||
|
||||
### im.typing.start
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 通知对方"正在输入"
|
||||
|
||||
**data 参数：** `{ "conversation_id": 1 }`
|
||||
|
||||
---
|
||||
|
||||
### im.typing.stop
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 停止输入
|
||||
|
||||
**data 参数：** `{ "conversation_id": 1 }`
|
||||
|
||||
---
|
||||
|
||||
## 会议信令事件
|
||||
|
||||
### meeting.room.join
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 加入会议房间
|
||||
|
||||
**data 参数：** `{ "room_code": "123-456-789" }`
|
||||
|
||||
**ACK 响应 data：** 房间信息、参与者列表、RTP Capabilities
|
||||
|
||||
---
|
||||
|
||||
### meeting.room.leave
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 离开会议房间
|
||||
|
||||
**data 参数：** `{ "room_code": "123-456-789" }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.room.info
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 房间信息同步（成员变更、设置变更时推送）
|
||||
|
||||
---
|
||||
|
||||
### meeting.member.join
|
||||
|
||||
**方向：** 服务端 → 客户端（广播）
|
||||
|
||||
**说明：** 有新成员加入会议
|
||||
|
||||
**data 内容：**
|
||||
```json
|
||||
{
|
||||
"room_code": "123-456-789",
|
||||
"user_id": 3,
|
||||
"nickname": "王五",
|
||||
"avatar": "https://...",
|
||||
"role": 0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### meeting.member.leave
|
||||
|
||||
**方向：** 服务端 → 客户端（广播）
|
||||
|
||||
**说明：** 有成员离开会议
|
||||
|
||||
**data 内容：** `{ "room_code": "...", "user_id": 3 }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.member.mute
|
||||
|
||||
**方向：** 双向
|
||||
|
||||
**说明：** 静音/解除静音
|
||||
|
||||
**data 内容：** `{ "room_code": "...", "user_id": 1, "muted": true }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.member.video
|
||||
|
||||
**方向：** 双向
|
||||
|
||||
**说明：** 开关摄像头
|
||||
|
||||
**data 内容：** `{ "room_code": "...", "user_id": 1, "video_enabled": false }`
|
||||
|
||||
---
|
||||
|
||||
## mediasoup 信令事件
|
||||
|
||||
### meeting.transport.create
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 请求创建 WebRTC Transport（发送端或接收端）
|
||||
|
||||
**data 参数：** `{ "room_code": "...", "direction": "send" }` 或 `"recv"`
|
||||
|
||||
**ACK 响应 data：** Transport 参数（id, iceParameters, iceCandidates, dtlsParameters）
|
||||
|
||||
---
|
||||
|
||||
### meeting.transport.connect
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 完成 Transport DTLS 握手
|
||||
|
||||
**data 参数：** `{ "transport_id": "...", "dtls_parameters": { ... } }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.produce.start
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 开始推流（音频或视频）
|
||||
|
||||
**data 参数：**
|
||||
```json
|
||||
{
|
||||
"transport_id": "...",
|
||||
"kind": "video",
|
||||
"rtp_parameters": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**ACK 响应 data：** `{ "producer_id": "..." }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.produce.stop
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 停止推流
|
||||
|
||||
**data 参数：** `{ "producer_id": "..." }`
|
||||
|
||||
---
|
||||
|
||||
### meeting.consume.start
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 通知客户端可以开始接收某个参与者的流
|
||||
|
||||
**data 内容：**
|
||||
```json
|
||||
{
|
||||
"consumer_id": "...",
|
||||
"producer_id": "...",
|
||||
"kind": "video",
|
||||
"rtp_parameters": { ... },
|
||||
"user_id": 3,
|
||||
"nickname": "王五"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### meeting.consume.resume
|
||||
|
||||
**方向：** 客户端 → 服务端
|
||||
|
||||
**说明：** 恢复被暂停的 Consumer
|
||||
|
||||
**data 参数：** `{ "consumer_id": "..." }`
|
||||
|
||||
---
|
||||
|
||||
## 用户状态事件
|
||||
|
||||
### user.status.online
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 好友上线通知
|
||||
|
||||
**data 内容：** `{ "user_id": 2, "nickname": "李四" }`
|
||||
|
||||
---
|
||||
|
||||
### user.status.offline
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 好友离线通知
|
||||
|
||||
**data 内容：** `{ "user_id": 2 }`
|
||||
|
||||
---
|
||||
|
||||
## 通知事件
|
||||
|
||||
### notify.new
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 新通知推送（通用）
|
||||
|
||||
**data 内容：** 与 Notify API 获取通知列表中的单条通知格式一致
|
||||
|
||||
---
|
||||
|
||||
### notify.meeting.invite
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 会议邀请推送
|
||||
|
||||
**data 内容：**
|
||||
```json
|
||||
{
|
||||
"room_code": "123-456-789",
|
||||
"title": "产品需求讨论",
|
||||
"from_user_id": 1,
|
||||
"from_nickname": "张三"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### notify.friend.request
|
||||
|
||||
**方向：** 服务端 → 客户端
|
||||
|
||||
**说明：** 好友申请推送
|
||||
|
||||
**data 内容：**
|
||||
```json
|
||||
{
|
||||
"friendship_id": 5,
|
||||
"from_user_id": 2,
|
||||
"from_nickname": "李四",
|
||||
"from_avatar": "https://...",
|
||||
"message": "我是你的同事"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user