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
138
docs/api/README.md
Normal file
138
docs/api/README.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# EchoChat API 接口文档
|
||||
|
||||
> 本目录包含 EchoChat 系统所有接口定义，按功能模块拆分为独立文档，便于维护和查阅。
|
||||
> 架构设计见 `docs/architecture/system-architecture.md`
|
||||
> 完整设计方案见 `docs/plans/2026-02-27-echochat-system-design.md`
|
||||
|
||||
---
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 模块 | 说明 |
|
||||
|------|------|------|
|
||||
| [auth.md](auth.md) | 认证模块 | 用户注册、登录、Token 管理、个人信息 |
|
||||
| [contact.md](contact.md) | 联系人模块 | 好友管理、好友分组 |
|
||||
| [im.md](im.md) | 即时通讯模块 | 会话管理、消息历史、群聊管理 |
|
||||
| [meeting.md](meeting.md) | 会议模块 | 即时会议、预约会议、加入/离开会议 |
|
||||
| [notify.md](notify.md) | 通知模块 | 通知列表、已读管理 |
|
||||
| [admin.md](admin.md) | 后台管理模块 | 用户管理、会议监控、系统配置、操作日志 |
|
||||
| [websocket.md](websocket.md) | WebSocket 协议 | 实时消息、会议信令、在线状态事件 |
|
||||
|
||||
---
|
||||
|
||||
## 通用规范
|
||||
|
||||
### 基础 URL
|
||||
|
||||
| 环境 | 地址 |
|
||||
|------|------|
|
||||
| 开发环境 | `http://localhost:8080` |
|
||||
| 生产环境 | `https://api.echochat.com`（待定） |
|
||||
|
||||
### 认证方式
|
||||
|
||||
除登录/注册等公开接口外，所有接口均需在请求头中携带 JWT Token：
|
||||
|
||||
```
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
### 统一响应格式
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": { ... },
|
||||
"timestamp": 1740700000
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
{
|
||||
"code": 1001,
|
||||
"message": "参数错误：邮箱格式不正确",
|
||||
"data": null,
|
||||
"timestamp": 1740700000
|
||||
}
|
||||
```
|
||||
|
||||
### 错误码定义
|
||||
|
||||
#### 通用错误码（1000-1099）
|
||||
|
||||
| 错误码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 0 | 成功 | 请求处理成功 |
|
||||
| 1001 | 参数错误 | 请求参数缺失或格式不正确 |
|
||||
| 1002 | 未认证 | Token 缺失、过期或无效 |
|
||||
| 1003 | 权限不足 | 当前用户角色无权执行此操作 |
|
||||
| 1004 | 资源不存在 | 请求的目标资源不存在 |
|
||||
| 1005 | 操作重复 | 如重复注册、重复添加好友等 |
|
||||
|
||||
#### 认证模块错误码（2000-2099）
|
||||
|
||||
| 错误码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 2001 | 用户名已存在 | 注册时用户名重复 |
|
||||
| 2002 | 邮箱已注册 | 注册时邮箱重复 |
|
||||
| 2003 | 账号或密码错误 | 登录失败 |
|
||||
| 2004 | 账号已被禁用 | 用户状态为禁用 |
|
||||
|
||||
#### IM 模块错误码（3000-3099）
|
||||
|
||||
| 错误码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 3001 | 会话不存在 | IM 会话 ID 无效 |
|
||||
| 3002 | 非会话成员 | 用户不在该会话中 |
|
||||
| 3003 | 已被禁言 | 用户在该群聊中被禁言 |
|
||||
|
||||
#### 会议模块错误码（4000-4099）
|
||||
|
||||
| 错误码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 4001 | 会议不存在 | 会议号无效 |
|
||||
| 4002 | 会议密码错误 | 加入会议时密码不匹配 |
|
||||
| 4003 | 会议已满 | 参会人数已达上限 |
|
||||
| 4004 | 会议已结束 | 尝试加入已结束的会议 |
|
||||
|
||||
#### 系统错误码（5000-5099）
|
||||
|
||||
| 错误码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 5001 | 系统内部错误 | 服务端未知错误 |
|
||||
| 5002 | 服务暂不可用 | 依赖服务不可用（数据库、Redis 等） |
|
||||
|
||||
### 分页规范
|
||||
|
||||
支持分页的接口统一使用以下查询参数：
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| page | int | 1 | 页码，从 1 开始 |
|
||||
| page_size | int | 20 | 每页数量，最大 100 |
|
||||
|
||||
分页响应格式：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"list": [ ... ],
|
||||
"total": 150,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文档维护规则
|
||||
|
||||
1. **新增接口时**：在对应模块文档中追加，保持格式一致
|
||||
2. **接口变更时**：同步更新文档，必要时在接口描述中标注版本信息
|
||||
3. **新增模块时**：创建新的模块文档，在本 README 导航表中添加链接
|
||||
4. **错误码新增时**：在本文档的错误码定义中追加，保持各模块错误码区间不重叠
|
||||
280
docs/api/admin.md
Normal file
280
docs/api/admin.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# 后台管理模块 API (Admin)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
> 以下所有接口（除管理员登录外）均需要 **JWT 认证 + admin/super_admin 角色**
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 认证
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| POST | /api/v1/admin/auth/login | 公开 | 管理员登录 |
|
||||
|
||||
### 用户管理
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/admin/users | admin | 获取用户列表 |
|
||||
| GET | /api/v1/admin/users/:id | admin | 获取用户详情 |
|
||||
| PUT | /api/v1/admin/users/:id/status | admin | 更新用户状态 |
|
||||
| PUT | /api/v1/admin/users/:id/role | super_admin | 分配用户角色 |
|
||||
| POST | /api/v1/admin/users | admin | 管理员创建用户 |
|
||||
| GET | /api/v1/admin/users/:id/meetings | admin | 获取用户会议记录 |
|
||||
|
||||
### 会议管理
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/admin/meetings | admin | 获取会议列表 |
|
||||
| GET | /api/v1/admin/meetings/:id | admin | 获取会议详情 |
|
||||
| PUT | /api/v1/admin/meetings/:id/close | admin | 强制结束会议 |
|
||||
| GET | /api/v1/admin/meetings/stats | admin | 获取会议统计 |
|
||||
|
||||
### 系统管理
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/admin/dashboard | admin | 获取仪表盘数据 |
|
||||
| GET | /api/v1/admin/logs | admin | 获取操作日志 |
|
||||
| GET | /api/v1/admin/system/config | super_admin | 获取系统配置 |
|
||||
| PUT | /api/v1/admin/system/config | super_admin | 更新系统配置 |
|
||||
|
||||
---
|
||||
|
||||
## 认证
|
||||
|
||||
### 1. 管理员登录
|
||||
|
||||
`POST /api/v1/admin/auth/login`
|
||||
|
||||
**权限：** 公开
|
||||
|
||||
**请求参数：** 与用户登录相同
|
||||
|
||||
**说明：** 登录后会额外验证用户是否拥有 admin 或 super_admin 角色，如果没有对应角色则返回 1003（权限不足）。
|
||||
|
||||
---
|
||||
|
||||
## 用户管理
|
||||
|
||||
### 2. 获取用户列表
|
||||
|
||||
`GET /api/v1/admin/users`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| keyword | string | 无 | 搜索关键词（匹配用户名/邮箱/昵称） |
|
||||
| status | int | 无 | 按状态筛选：1=正常，2=禁用，3=注销 |
|
||||
| role | string | 无 | 按角色筛选：user / admin / super_admin |
|
||||
| page | int | 1 | 页码 |
|
||||
| page_size | int | 20 | 每页数量 |
|
||||
|
||||
---
|
||||
|
||||
### 3. 获取用户详情
|
||||
|
||||
`GET /api/v1/admin/users/:id`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "zhangsan",
|
||||
"email": "zhangsan@example.com",
|
||||
"nickname": "张三",
|
||||
"avatar": "https://...",
|
||||
"gender": 1,
|
||||
"phone": "13800138000",
|
||||
"status": 1,
|
||||
"roles": ["user"],
|
||||
"last_login_at": "2026-02-27T10:00:00Z",
|
||||
"last_login_ip": "192.168.1.100",
|
||||
"created_at": "2026-02-20T08:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新用户状态
|
||||
|
||||
`PUT /api/v1/admin/users/:id/status`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| status | int | 是 | 目标状态：1=正常（启用），2=禁用 |
|
||||
|
||||
**说明：** 禁用用户后，该用户的所有活跃 Token 将被清除，正在进行的 WebSocket 连接将被断开。
|
||||
|
||||
---
|
||||
|
||||
### 5. 分配用户角色
|
||||
|
||||
`PUT /api/v1/admin/users/:id/role`
|
||||
|
||||
**权限：** super_admin
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| role_code | string | 是 | 角色代码：user / admin / super_admin |
|
||||
|
||||
---
|
||||
|
||||
### 6. 管理员创建用户
|
||||
|
||||
`POST /api/v1/admin/users`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**请求参数：** 同用户注册接口，额外支持：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| role_code | string | 否 | 指定角色，默认为 user |
|
||||
|
||||
---
|
||||
|
||||
### 7. 获取用户会议记录
|
||||
|
||||
`GET /api/v1/admin/users/:id/meetings`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| status | string | 无 | ongoing=进行中，upcoming=即将开始，ended=已结束 |
|
||||
| page | int | 1 | 页码 |
|
||||
| page_size | int | 20 | 每页数量 |
|
||||
|
||||
---
|
||||
|
||||
## 会议管理
|
||||
|
||||
### 8. 获取会议列表
|
||||
|
||||
`GET /api/v1/admin/meetings`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**查询参数：** 支持按 status、type、keyword（会议标题）筛选，支持分页
|
||||
|
||||
---
|
||||
|
||||
### 9. 获取会议详情
|
||||
|
||||
`GET /api/v1/admin/meetings/:id`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
---
|
||||
|
||||
### 10. 强制结束会议
|
||||
|
||||
`PUT /api/v1/admin/meetings/:id/close`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**说明：** 强制结束后，所有参会者将收到会议结束通知，所有媒体资源将被回收。操作将记录到管理日志。
|
||||
|
||||
---
|
||||
|
||||
### 11. 获取会议统计
|
||||
|
||||
`GET /api/v1/admin/meetings/stats`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"total_meetings": 1500,
|
||||
"ongoing_meetings": 5,
|
||||
"today_meetings": 23,
|
||||
"total_participants": 8500,
|
||||
"avg_duration": 1800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 系统管理
|
||||
|
||||
### 12. 获取仪表盘数据
|
||||
|
||||
`GET /api/v1/admin/dashboard`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"total_users": 1200,
|
||||
"online_users": 85,
|
||||
"today_new_users": 12,
|
||||
"ongoing_meetings": 5,
|
||||
"today_meetings": 23,
|
||||
"today_messages": 5600
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. 获取操作日志
|
||||
|
||||
`GET /api/v1/admin/logs`
|
||||
|
||||
**权限：** admin
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| module | string | 无 | 按模块筛选 |
|
||||
| action | string | 无 | 按操作类型筛选 |
|
||||
| admin_id | int | 无 | 按操作管理员筛选 |
|
||||
| page | int | 1 | 页码 |
|
||||
| page_size | int | 20 | 每页数量 |
|
||||
|
||||
---
|
||||
|
||||
### 14. 获取系统配置
|
||||
|
||||
`GET /api/v1/admin/system/config`
|
||||
|
||||
**权限：** super_admin
|
||||
|
||||
---
|
||||
|
||||
### 15. 更新系统配置
|
||||
|
||||
`PUT /api/v1/admin/system/config`
|
||||
|
||||
**权限：** super_admin
|
||||
203
docs/api/auth.md
Normal file
203
docs/api/auth.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 认证模块 API (Auth)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| POST | /api/v1/auth/register | 公开 | 用户注册 |
|
||||
| POST | /api/v1/auth/login | 公开 | 用户登录 |
|
||||
| POST | /api/v1/auth/logout | 需认证 | 退出登录 |
|
||||
| POST | /api/v1/auth/refresh-token | 公开 | 刷新 Token |
|
||||
| GET | /api/v1/auth/profile | 需认证 | 获取个人信息 |
|
||||
| PUT | /api/v1/auth/profile | 需认证 | 更新个人信息 |
|
||||
| PUT | /api/v1/auth/password | 需认证 | 修改密码 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 用户注册
|
||||
|
||||
`POST /api/v1/auth/register`
|
||||
|
||||
**权限：** 公开
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| username | string | 是 | 3-50 字符，字母数字下划线 | 用户名 |
|
||||
| email | string | 是 | 合法邮箱格式 | 邮箱地址 |
|
||||
| password | string | 是 | 6-50 字符 | 登录密码 |
|
||||
| nickname | string | 否 | 最多 50 字符 | 昵称，默认与用户名相同 |
|
||||
|
||||
**请求示例：**
|
||||
```json
|
||||
{
|
||||
"username": "zhangsan",
|
||||
"email": "zhangsan@example.com",
|
||||
"password": "123456",
|
||||
"nickname": "张三"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"expires_in": 604800,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "zhangsan",
|
||||
"email": "zhangsan@example.com",
|
||||
"nickname": "张三",
|
||||
"avatar": "",
|
||||
"roles": ["user"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**可能的错误码：** 1001, 2001, 2002
|
||||
|
||||
---
|
||||
|
||||
## 2. 用户登录
|
||||
|
||||
`POST /api/v1/auth/login`
|
||||
|
||||
**权限：** 公开
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| account | string | 是 | 用户名或邮箱（自动识别格式） |
|
||||
| password | string | 是 | 登录密码 |
|
||||
|
||||
**请求示例：**
|
||||
```json
|
||||
{
|
||||
"account": "zhangsan",
|
||||
"password": "123456"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应：** 与注册接口返回格式一致
|
||||
|
||||
**可能的错误码：** 1001, 2003, 2004
|
||||
|
||||
---
|
||||
|
||||
## 3. 退出登录
|
||||
|
||||
`POST /api/v1/auth/logout`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 服务端清除 Redis 中的 Token 记录，客户端需同步清除本地存储的 Token。
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 刷新 Token
|
||||
|
||||
`POST /api/v1/auth/refresh-token`
|
||||
|
||||
**权限：** 公开（携带 refresh_token）
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| refresh_token | string | 是 | 刷新令牌 |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"token": "eyJhbG...(新 Access Token)",
|
||||
"refresh_token": "eyJhbG...(新 Refresh Token)",
|
||||
"expires_in": 604800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**可能的错误码：** 1002
|
||||
|
||||
---
|
||||
|
||||
## 5. 获取个人信息
|
||||
|
||||
`GET /api/v1/auth/profile`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "zhangsan",
|
||||
"email": "zhangsan@example.com",
|
||||
"nickname": "张三",
|
||||
"avatar": "https://cdn.echochat.com/avatar/1.jpg",
|
||||
"gender": 1,
|
||||
"phone": "13800138000",
|
||||
"roles": ["user"],
|
||||
"created_at": "2026-02-27T10:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 更新个人信息
|
||||
|
||||
`PUT /api/v1/auth/profile`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数（均为可选，只传需要修改的字段）：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| nickname | string | 否 | 新昵称 |
|
||||
| avatar | string | 否 | 新头像 URL |
|
||||
| gender | int | 否 | 性别：0=未知，1=男，2=女 |
|
||||
| phone | string | 否 | 手机号 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 修改密码
|
||||
|
||||
`PUT /api/v1/auth/password`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| old_password | string | 是 | 原密码 |
|
||||
| new_password | string | 是 | 新密码（6-50 字符） |
|
||||
|
||||
**可能的错误码：** 1001, 2003（原密码错误）
|
||||
164
docs/api/contact.md
Normal file
164
docs/api/contact.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 联系人模块 API (Contact)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/contacts | 需认证 | 获取好友列表 |
|
||||
| POST | /api/v1/contacts/request | 需认证 | 发送好友申请 |
|
||||
| POST | /api/v1/contacts/accept | 需认证 | 接受好友申请 |
|
||||
| POST | /api/v1/contacts/reject | 需认证 | 拒绝好友申请 |
|
||||
| DELETE | /api/v1/contacts/:id | 需认证 | 删除好友 |
|
||||
| PUT | /api/v1/contacts/:id/remark | 需认证 | 修改好友备注 |
|
||||
| GET | /api/v1/contacts/groups | 需认证 | 获取好友分组列表 |
|
||||
| POST | /api/v1/contacts/groups | 需认证 | 创建好友分组 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 获取好友列表
|
||||
|
||||
`GET /api/v1/contacts`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| group_id | int | 否 | 按分组筛选 |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"friend_id": 2,
|
||||
"username": "lisi",
|
||||
"nickname": "李四",
|
||||
"remark": "我的同事",
|
||||
"avatar": "https://cdn.echochat.com/avatar/2.jpg",
|
||||
"online": true,
|
||||
"group_id": 1,
|
||||
"group_name": "同事"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 发送好友申请
|
||||
|
||||
`POST /api/v1/contacts/request`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| target_id | int | 是 | 目标用户 ID |
|
||||
| message | string | 否 | 申请附言，如"我是张三的同事" |
|
||||
|
||||
**可能的错误码：** 1004（用户不存在），1005（已是好友或已发送过申请）
|
||||
|
||||
---
|
||||
|
||||
## 3. 接受好友申请
|
||||
|
||||
`POST /api/v1/contacts/accept`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| friendship_id | int | 是 | 好友关系记录 ID |
|
||||
|
||||
**说明：** 接受后系统自动创建双向好友关系，并发送通知给对方。
|
||||
|
||||
---
|
||||
|
||||
## 4. 拒绝好友申请
|
||||
|
||||
`POST /api/v1/contacts/reject`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| friendship_id | int | 是 | 好友关系记录 ID |
|
||||
|
||||
---
|
||||
|
||||
## 5. 删除好友
|
||||
|
||||
`DELETE /api/v1/contacts/:id`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**路径参数：** `id` — 好友关系记录 ID
|
||||
|
||||
**说明：** 删除后双向关系均解除，关联的单聊会话不会删除（消息记录保留）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修改好友备注
|
||||
|
||||
`PUT /api/v1/contacts/:id/remark`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**路径参数：** `id` — 好友关系记录 ID
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| remark | string | 是 | 新备注名，最多 50 字符 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 获取好友分组列表
|
||||
|
||||
`GET /api/v1/contacts/groups`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": [
|
||||
{ "id": 1, "name": "同事", "sort_order": 0, "count": 15 },
|
||||
{ "id": 2, "name": "朋友", "sort_order": 1, "count": 8 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 创建好友分组
|
||||
|
||||
`POST /api/v1/contacts/groups`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 分组名称，最多 50 字符 |
|
||||
|
||||
**可能的错误码：** 1005（同名分组已存在）
|
||||
208
docs/api/im.md
Normal file
208
docs/api/im.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# 即时通讯模块 API (IM)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
> 消息的实时收发通过 WebSocket 完成，见 [websocket.md](websocket.md)
|
||||
> 本文档中的接口用于会话管理和消息历史查询等非实时操作。
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/conversations | 需认证 | 获取会话列表 |
|
||||
| POST | /api/v1/conversations | 需认证 | 创建群聊 |
|
||||
| GET | /api/v1/conversations/:id | 需认证 | 获取会话详情 |
|
||||
| GET | /api/v1/conversations/:id/messages | 需认证 | 获取消息历史 |
|
||||
| POST | /api/v1/conversations/:id/members | 需认证 | 邀请成员加入群聊 |
|
||||
| DELETE | /api/v1/conversations/:id/members/:uid | 需认证 | 移除群聊成员 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 获取会话列表
|
||||
|
||||
`GET /api/v1/conversations`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 返回当前用户的所有会话，按最后消息时间倒序排列。单聊会话的 `name`/`avatar` 为空，前端应使用 `target_user` 的信息展示。
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"type": 1,
|
||||
"name": "",
|
||||
"avatar": "",
|
||||
"target_user": {
|
||||
"id": 2,
|
||||
"nickname": "李四",
|
||||
"avatar": "https://cdn.echochat.com/avatar/2.jpg",
|
||||
"online": true
|
||||
},
|
||||
"last_message": {
|
||||
"id": 100,
|
||||
"type": 1,
|
||||
"content": "你好",
|
||||
"sender_id": 2,
|
||||
"created_at": "2026-02-27T10:30:00Z"
|
||||
},
|
||||
"unread_count": 3,
|
||||
"is_pinned": false
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"type": 2,
|
||||
"name": "产品讨论组",
|
||||
"avatar": "https://cdn.echochat.com/group/5.jpg",
|
||||
"target_user": null,
|
||||
"last_message": {
|
||||
"id": 205,
|
||||
"type": 1,
|
||||
"content": "明天开会",
|
||||
"sender_id": 3,
|
||||
"created_at": "2026-02-27T11:00:00Z"
|
||||
},
|
||||
"unread_count": 0,
|
||||
"is_pinned": true,
|
||||
"member_count": 8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 创建群聊
|
||||
|
||||
`POST /api/v1/conversations`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 群聊名称 |
|
||||
| member_ids | int[] | 是 | 初始成员用户 ID 列表（不含自己，至少 2 人） |
|
||||
|
||||
**说明：** 创建者自动成为群主（role=2），被邀请的成员为普通成员（role=0）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取会话详情
|
||||
|
||||
`GET /api/v1/conversations/:id`
|
||||
|
||||
**权限：** 需认证，且为该会话成员
|
||||
|
||||
**成功响应（群聊示例）：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": 5,
|
||||
"type": 2,
|
||||
"name": "产品讨论组",
|
||||
"avatar": "https://cdn.echochat.com/group/5.jpg",
|
||||
"owner_id": 1,
|
||||
"max_members": 200,
|
||||
"member_count": 8,
|
||||
"members": [
|
||||
{ "user_id": 1, "nickname": "张三", "role": 2, "online": true },
|
||||
{ "user_id": 2, "nickname": "李四", "role": 0, "online": false }
|
||||
],
|
||||
"created_at": "2026-02-20T09:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 获取消息历史
|
||||
|
||||
`GET /api/v1/conversations/:id/messages`
|
||||
|
||||
**权限：** 需认证，且为该会话成员
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| before_id | int | 无 | 获取此消息 ID 之前的消息（用于向上翻页加载历史） |
|
||||
| limit | int | 30 | 每次获取数量，最大 50 |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"messages": [
|
||||
{
|
||||
"id": 98,
|
||||
"sender_id": 1,
|
||||
"sender_name": "张三",
|
||||
"sender_avatar": "https://...",
|
||||
"type": 1,
|
||||
"content": "明天几点开会？",
|
||||
"extra": {},
|
||||
"status": 1,
|
||||
"created_at": "2026-02-27T10:28:00Z"
|
||||
},
|
||||
{
|
||||
"id": 99,
|
||||
"sender_id": 2,
|
||||
"sender_name": "李四",
|
||||
"sender_avatar": "https://...",
|
||||
"type": 2,
|
||||
"content": "",
|
||||
"extra": {
|
||||
"url": "https://cdn.echochat.com/img/xxx.jpg",
|
||||
"width": 800,
|
||||
"height": 600,
|
||||
"thumbnail": "https://cdn.echochat.com/img/xxx_thumb.jpg"
|
||||
},
|
||||
"status": 1,
|
||||
"created_at": "2026-02-27T10:29:00Z"
|
||||
}
|
||||
],
|
||||
"has_more": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 邀请成员加入群聊
|
||||
|
||||
`POST /api/v1/conversations/:id/members`
|
||||
|
||||
**权限：** 需认证，且为该群聊成员
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| user_ids | int[] | 是 | 要邀请的用户 ID 列表 |
|
||||
|
||||
**可能的错误码：** 3001（会话不存在），3002（非会话成员），4003（超出人数上限）
|
||||
|
||||
---
|
||||
|
||||
## 6. 移除群聊成员
|
||||
|
||||
`DELETE /api/v1/conversations/:id/members/:uid`
|
||||
|
||||
**权限：** 需认证，且为群主或管理员
|
||||
|
||||
**路径参数：**
|
||||
- `id` — 会话 ID
|
||||
- `uid` — 被移除的用户 ID
|
||||
|
||||
**可能的错误码：** 3001, 3002, 1003（非群主/管理员无权操作）
|
||||
180
docs/api/meeting.md
Normal file
180
docs/api/meeting.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 会议模块 API (Meeting)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
> 会议中的实时信令（Transport/Producer/Consumer）通过 WebSocket 完成，见 [websocket.md](websocket.md)
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| POST | /api/v1/meetings | 需认证 | 创建即时会议 |
|
||||
| POST | /api/v1/meetings/schedule | 需认证 | 预约会议 |
|
||||
| GET | /api/v1/meetings/:code | 需认证 | 获取会议信息 |
|
||||
| POST | /api/v1/meetings/:code/join | 需认证 | 加入会议 |
|
||||
| POST | /api/v1/meetings/:code/leave | 需认证 | 离开会议 |
|
||||
| GET | /api/v1/meetings/upcoming | 需认证 | 获取即将开始的会议 |
|
||||
| GET | /api/v1/meetings/ongoing | 需认证 | 获取进行中的会议 |
|
||||
| GET | /api/v1/meetings/history | 需认证 | 获取历史会议 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 创建即时会议
|
||||
|
||||
`POST /api/v1/meetings`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| title | string | 是 | 会议标题 |
|
||||
| password | string | 否 | 会议密码，不设则任何人可加入 |
|
||||
| max_members | int | 否 | 最大人数，默认 50 |
|
||||
| settings | object | 否 | 会议设置 |
|
||||
|
||||
**settings 可选字段：**
|
||||
|
||||
| 字段 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| mute_on_join | bool | false | 入会时自动静音 |
|
||||
| allow_recording | bool | false | 是否允许录制（预留） |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"room_code": "123-456-789",
|
||||
"title": "产品需求讨论",
|
||||
"type": 1,
|
||||
"status": 1,
|
||||
"host_id": 1,
|
||||
"max_members": 50,
|
||||
"created_at": "2026-02-27T10:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 预约会议
|
||||
|
||||
`POST /api/v1/meetings/schedule`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| title | string | 是 | 会议标题 |
|
||||
| scheduled_at | string | 是 | 预约时间（ISO 8601，如 "2026-03-01T14:00:00Z"） |
|
||||
| password | string | 否 | 会议密码 |
|
||||
| max_members | int | 否 | 最大人数 |
|
||||
| invite_user_ids | int[] | 否 | 预先邀请的用户 ID 列表 |
|
||||
| settings | object | 否 | 会议设置 |
|
||||
|
||||
**说明：** 预约会议创建后 status=0（未开始），被邀请的用户会收到通知。系统在预约时间前 15 分钟和 5 分钟各推送一次提醒。
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取会议信息
|
||||
|
||||
`GET /api/v1/meetings/:code`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**路径参数：** `code` — 会议号
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"room_code": "123-456-789",
|
||||
"title": "产品需求讨论",
|
||||
"type": 1,
|
||||
"status": 1,
|
||||
"host": {
|
||||
"id": 1,
|
||||
"nickname": "张三",
|
||||
"avatar": "https://..."
|
||||
},
|
||||
"has_password": true,
|
||||
"max_members": 50,
|
||||
"current_members": 5,
|
||||
"started_at": "2026-02-27T10:00:00Z",
|
||||
"participants": [
|
||||
{ "user_id": 1, "nickname": "张三", "role": 1, "joined_at": "2026-02-27T10:00:00Z" },
|
||||
{ "user_id": 2, "nickname": "李四", "role": 0, "joined_at": "2026-02-27T10:01:00Z" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 加入会议
|
||||
|
||||
`POST /api/v1/meetings/:code/join`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| password | string | 否 | 会议密码（如果会议设有密码） |
|
||||
|
||||
**成功响应包含加入会议所需的信令参数。**
|
||||
|
||||
**可能的错误码：** 4001, 4002, 4003, 4004
|
||||
|
||||
---
|
||||
|
||||
## 5. 离开会议
|
||||
|
||||
`POST /api/v1/meetings/:code/leave`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 离开后系统自动计算参会时长。如果主持人离开且没有联合主持人，会议将自动结束。
|
||||
|
||||
---
|
||||
|
||||
## 6. 获取即将开始的会议
|
||||
|
||||
`GET /api/v1/meetings/upcoming`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 返回当前用户被邀请的、尚未开始的预约会议列表，按预约时间升序排列。
|
||||
|
||||
---
|
||||
|
||||
## 7. 获取进行中的会议
|
||||
|
||||
`GET /api/v1/meetings/ongoing`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 返回当前用户正在参与的或被邀请的进行中会议。
|
||||
|
||||
---
|
||||
|
||||
## 8. 获取历史会议
|
||||
|
||||
`GET /api/v1/meetings/history`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**查询参数：** 支持分页（page, page_size）
|
||||
|
||||
**说明：** 返回当前用户参与过的已结束会议，按结束时间倒序排列。
|
||||
93
docs/api/notify.md
Normal file
93
docs/api/notify.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 通知模块 API (Notify)
|
||||
|
||||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](README.md)
|
||||
> 新通知的实时推送通过 WebSocket 完成，见 [websocket.md](websocket.md)
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
| 方法 | 路径 | 权限 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | /api/v1/notifications | 需认证 | 获取通知列表 |
|
||||
| PUT | /api/v1/notifications/:id/read | 需认证 | 标记通知已读 |
|
||||
| PUT | /api/v1/notifications/read-all | 需认证 | 全部标记已读 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 获取通知列表
|
||||
|
||||
`GET /api/v1/notifications`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**查询参数：**
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| is_read | bool | 无 | 筛选已读/未读，不传则返回全部 |
|
||||
| type | string | 无 | 筛选通知类型（meeting_invite / friend_request / friend_accepted / meeting_reminder / system） |
|
||||
| page | int | 1 | 页码 |
|
||||
| page_size | int | 20 | 每页数量 |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "ok",
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"type": "meeting_invite",
|
||||
"title": "会议邀请",
|
||||
"content": "张三邀请你参加会议「产品需求讨论」",
|
||||
"extra": {
|
||||
"room_code": "123-456-789",
|
||||
"room_title": "产品需求讨论",
|
||||
"from_user_id": 1,
|
||||
"from_username": "zhangsan"
|
||||
},
|
||||
"is_read": false,
|
||||
"created_at": "2026-02-27T10:00:00Z"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"type": "friend_request",
|
||||
"title": "好友申请",
|
||||
"content": "李四请求添加你为好友",
|
||||
"extra": {
|
||||
"from_user_id": 2,
|
||||
"from_username": "lisi",
|
||||
"message": "我是你的同事"
|
||||
},
|
||||
"is_read": false,
|
||||
"created_at": "2026-02-27T09:30:00Z"
|
||||
}
|
||||
],
|
||||
"total": 15,
|
||||
"page": 1,
|
||||
"page_size": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 标记通知已读
|
||||
|
||||
`PUT /api/v1/notifications/:id/read`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**路径参数：** `id` — 通知 ID
|
||||
|
||||
---
|
||||
|
||||
## 3. 全部标记已读
|
||||
|
||||
`PUT /api/v1/notifications/read-all`
|
||||
|
||||
**权限：** 需认证
|
||||
|
||||
**说明：** 将当前用户的所有未读通知标记为已读。
|
||||
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