620 lines
15 KiB
Markdown
620 lines
15 KiB
Markdown
# OpenIM 会议接口文档（用户端 - 前端对接版）
|
||
|
||
本文档专门用于前端开发人员对接 OpenIM 会议相关 API 接口（用户端）。
|
||
|
||
## 目录
|
||
|
||
- [基础说明](#基础说明)
|
||
- [会议状态说明](#会议状态说明)
|
||
- [用户端接口](#用户端接口)
|
||
- [业务规则](#业务规则)
|
||
- [错误码说明](#错误码说明)
|
||
- [注意事项](#注意事项)
|
||
|
||
---
|
||
|
||
## 基础说明
|
||
|
||
### 请求格式
|
||
|
||
- **请求方法**: 所有接口均使用 `POST` 方法
|
||
- **Content-Type**: `application/json`
|
||
- **请求头**: 需要在请求头中携带 `token` 进行身份验证
|
||
|
||
```http
|
||
POST /meeting/get_meeting
|
||
Content-Type: application/json
|
||
token: your_token_here
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
所有接口统一返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0表示成功
|
||
"errMsg": "", // 错误消息
|
||
"errDlt": "", // 错误详情
|
||
"data": {} // 响应数据，具体结构见各接口说明
|
||
}
|
||
```
|
||
|
||
### 基础URL
|
||
|
||
根据部署环境配置，例如：
|
||
- 开发环境: `http://localhost:10002`
|
||
- 生产环境: `https://your-domain.com`
|
||
|
||
---
|
||
|
||
## 会议状态说明
|
||
|
||
| 状态值 | 状态名称 | 说明 | 用户端可见 |
|
||
|--------|---------|------|-----------|
|
||
| 1 | 已预约 | 会议已创建，等待开始 | ✅ 可见 |
|
||
| 2 | 进行中 | 会议正在进行 | ✅ 可见 |
|
||
| 3 | 已结束 | 会议已结束 | ❌ 不可见 |
|
||
| 4 | 已取消 | 会议已取消 | ❌ 不可见 |
|
||
|
||
**重要提示**：
|
||
- 用户端接口只能查看状态为 **1（已预约）** 和 **2（进行中）** 的会议
|
||
- 状态为 **3（已结束）** 和 **4（已取消）** 的会议对用户端不可见
|
||
|
||
---
|
||
|
||
## 用户端接口
|
||
|
||
### 1. 获取会议信息
|
||
|
||
**接口地址**: `POST /meeting/get_meeting`
|
||
|
||
**接口描述**: 获取单个会议信息，只能查看已预约和进行中的会议
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"meetingID": "string" // 会议ID（必填）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"meetingInfo": {
|
||
"meetingID": "string", // 会议ID
|
||
"subject": "string", // 会议主题
|
||
"coverURL": "string", // 封面URL
|
||
"scheduledTime": 1234567890000, // 预约时间戳（毫秒）
|
||
"status": 1, // 会议状态：1-已预约，2-进行中
|
||
"description": "string", // 会议描述
|
||
"duration": 60, // 会议时长（分钟）
|
||
"enableMic": true, // 是否开启连麦
|
||
"enableComment": true, // 是否开启评论
|
||
"anchorUsers": [ // 主播用户信息列表
|
||
{
|
||
"userID": "user1",
|
||
"nickname": "主播1",
|
||
"faceURL": "https://example.com/avatar1.jpg"
|
||
},
|
||
{
|
||
"userID": "user2",
|
||
"nickname": "主播2",
|
||
"faceURL": "https://example.com/avatar2.jpg"
|
||
}
|
||
],
|
||
"groupID": "string", // 关联的群聊ID
|
||
"checkInCount": 50 // 签到人数统计
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 用户端接口只显示状态为 **1（已预约）** 和 **2（进行中）** 的会议
|
||
2. 如果会议状态为 **3（已结束）** 或 **4（已取消）**，将返回错误
|
||
3. 用户端接口不返回管理字段：
|
||
- `creatorUserID`（创建者ID）
|
||
- `ex`（扩展字段）
|
||
- `createTime`（创建时间）
|
||
- `updateTime`（更新时间）
|
||
- `estimatedCount`（预估人数）
|
||
- `anchorUserIDs`（主播ID列表，只返回 `anchorUsers`）
|
||
4. 返回的主播信息包含用户ID、昵称、头像等完整用户信息
|
||
5. 返回签到人数统计（`checkInCount`），用于显示会议签到情况
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误或会议不可用（会议已结束或已取消）
|
||
- `1004`: 会议不存在
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
### 2. 获取会议列表
|
||
|
||
**接口地址**: `POST /meeting/get_meetings_public`
|
||
|
||
**接口描述**: 获取会议列表，只能查看已预约和进行中的会议
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"status": 1, // 会议状态（选填）：1-已预约，2-进行中（只能查询这两个状态）
|
||
"keyword": "string", // 搜索关键词（选填，搜索主题和描述）
|
||
"startTime": 1234567890000, // 开始时间戳（毫秒，选填）
|
||
"endTime": 1234567890000, // 结束时间戳（毫秒，选填）
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码，从1开始（选填，默认1）
|
||
"showNumber": 20 // 每页数量（选填，默认20）
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `status`: 如果指定，只能传入 `1` 或 `2`，传入其他值将返回错误
|
||
- 如果不指定 `status`，查询结果会自动过滤，只返回状态1和2的会议
|
||
- 用户端接口不支持按创建者查询（没有 `creatorUserID` 参数）
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数（只包含状态1和2的会议）
|
||
"meetings": [
|
||
{
|
||
"meetingID": "string",
|
||
"subject": "string",
|
||
"coverURL": "string",
|
||
"scheduledTime": 1234567890000,
|
||
"status": 1,
|
||
"description": "string",
|
||
"duration": 60,
|
||
"enableMic": true,
|
||
"enableComment": true,
|
||
"anchorUsers": [
|
||
{
|
||
"userID": "user1",
|
||
"nickname": "主播1",
|
||
"faceURL": "https://example.com/avatar1.jpg"
|
||
}
|
||
],
|
||
"groupID": "string", // 关联的群聊ID
|
||
"checkInCount": 50 // 签到人数统计
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 用户端接口只显示状态为 **1（已预约）** 和 **2（进行中）** 的会议
|
||
2. 如果指定 `status` 参数，只能传入 `1` 或 `2`，传入其他值将返回错误
|
||
3. 如果不指定 `status`，查询结果会自动过滤，只返回状态1和2的会议
|
||
4. 用户端接口不支持按创建者查询
|
||
5. 用户端接口不返回管理字段（创建者ID、扩展字段、创建时间、更新时间、预估人数等）
|
||
6. 返回的主播信息包含用户ID、昵称、头像等完整用户信息
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误（如状态值不是1或2）
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
## 签到接口
|
||
|
||
### 1. 会议签到
|
||
|
||
**接口地址**: `POST /meeting/check_in`
|
||
|
||
**接口描述**: 用户对会议进行签到，一个用户在一个会议中只能签到一次
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"meetingID": "string" // 会议ID（必填）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"checkInID": "string", // 签到ID
|
||
"checkInTime": 1234567890000 // 签到时间戳（毫秒）
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 一个用户在一个会议中只能签到一次
|
||
2. 只能对状态为 **1（已预约）** 和 **2（进行中）** 的会议签到
|
||
3. 签到成功后会自动更新会议的签到统计（`checkInCount`）
|
||
4. 如果用户已经签到过，会返回错误
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误或会议不可用（会议已结束或已取消）
|
||
- `1001`: 用户已签到
|
||
- `1004`: 会议不存在
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
### 2. 检查用户是否已签到
|
||
|
||
**接口地址**: `POST /meeting/check_user_check_in`
|
||
|
||
**接口描述**: 检查当前用户是否已对指定会议签到
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"meetingID": "string" // 会议ID（必填）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"isCheckedIn": true, // 是否已签到
|
||
"checkInInfo": { // 签到信息（如果已签到）
|
||
"checkInID": "string",
|
||
"meetingID": "string",
|
||
"userID": "string",
|
||
"checkInTime": 1234567890000,
|
||
"userInfo": {
|
||
"userID": "string",
|
||
"nickname": "string",
|
||
"faceURL": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 如果用户已签到，返回 `isCheckedIn: true` 和签到详细信息
|
||
2. 如果用户未签到，返回 `isCheckedIn: false`，`checkInInfo` 为 `null`
|
||
3. 已签到时，会返回用户的基本信息（用户ID、昵称、头像等）
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
### 3. 获取会议签到列表
|
||
|
||
**接口地址**: `POST /meeting/get_check_ins`
|
||
|
||
**接口描述**: 获取指定会议的所有签到记录列表
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"meetingID": "string", // 会议ID（必填）
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码，从1开始（选填，默认1）
|
||
"showNumber": 20 // 每页数量（选填，默认20）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数
|
||
"checkIns": [
|
||
{
|
||
"checkInID": "string", // 签到ID
|
||
"meetingID": "string", // 会议ID
|
||
"userID": "string", // 用户ID
|
||
"checkInTime": 1234567890000, // 签到时间戳（毫秒）
|
||
"userInfo": { // 用户信息
|
||
"userID": "string",
|
||
"nickname": "string",
|
||
"faceURL": "string"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 支持分页查询
|
||
2. 签到列表按签到时间倒序排列（最新签到的在前）
|
||
3. 每个签到记录包含用户的完整信息（用户ID、昵称、头像等）
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
### 4. 获取会议签到统计
|
||
|
||
**接口地址**: `POST /meeting/get_check_in_stats`
|
||
|
||
**接口描述**: 获取指定会议的签到人数统计
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"meetingID": "string" // 会议ID（必填）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"meetingID": "string", // 会议ID
|
||
"checkInCount": 50 // 签到人数
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
1. 返回会议的签到总人数
|
||
2. 这个统计也会在会议信息中的 `checkInCount` 字段中返回
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
### 1. 会议与群聊的关联
|
||
|
||
- 创建会议时会自动创建一个群聊
|
||
- 群聊名称为：`"会议群-{会议主题}"`
|
||
- 会议封面会作为群聊头像
|
||
- 群聊的 `ex` 字段中会包含会议标识：
|
||
```json
|
||
{
|
||
"isMeetingGroup": true,
|
||
"meetingID": "会议ID"
|
||
}
|
||
```
|
||
|
||
### 2. 主播与群角色的关系
|
||
|
||
- **有主播列表时**：
|
||
- 第一个主播 → 群主
|
||
- 其他主播 → 管理员
|
||
- 创建者（如果不在主播列表中）→ 普通成员
|
||
- **没有主播列表时**：
|
||
- 创建者 → 群主
|
||
|
||
### 3. 评论开关与群禁言
|
||
|
||
- **开启评论** (`enableComment: true`)：
|
||
- 自动取消群禁言
|
||
- 群成员可以发送消息
|
||
- **关闭评论** (`enableComment: false`)：
|
||
- 自动禁言群
|
||
- 群成员无法发送消息
|
||
|
||
### 4. 权限控制
|
||
|
||
- **查看会议**：用户端只能查看已预约和进行中的会议
|
||
|
||
### 5. 时间验证
|
||
|
||
- 创建会议时，预约时间不能早于当前时间
|
||
- 更新会议时，如果更新预约时间，也不能早于当前时间
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
### 通用错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 500 | 服务器内部错误 |
|
||
| 1001 | 参数错误 |
|
||
| 1002 | 权限不足 |
|
||
| 1004 | 记录不存在 |
|
||
|
||
### 会议相关错误场景
|
||
|
||
| 错误码 | 场景 |
|
||
|--------|------|
|
||
| 1001 | 查询状态不是1或2 |
|
||
| 1004 | 会议不存在 |
|
||
| 1004 | 查询已结束或已取消的会议 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
### 1. 认证
|
||
|
||
- 所有接口都需要在请求头中携带 `token` 进行身份验证
|
||
- Token通过 `/auth/get_user_token` 接口获取
|
||
|
||
### 2. 请求格式
|
||
|
||
- 所有接口使用 `POST` 方法
|
||
- Content-Type: `application/json`
|
||
- 请求体为JSON格式
|
||
|
||
### 3. 响应格式
|
||
|
||
- 所有接口统一返回格式：`{errCode, errMsg, errDlt, data}`
|
||
- `errCode` 为 0 表示成功，非0表示失败
|
||
- 失败时查看 `errMsg` 和 `errDlt` 获取错误详情
|
||
|
||
### 4. 时间戳
|
||
|
||
- 所有时间戳均为毫秒级Unix时间戳
|
||
- 例如：`1234567890000` 表示 2009-02-13 23:31:30
|
||
|
||
### 5. 分页参数
|
||
|
||
- 分页参数统一格式：
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码，从1开始
|
||
"showNumber": 20 // 每页数量
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 用户端接口特点
|
||
|
||
- 只能查看状态为 **1（已预约）** 和 **2（进行中）** 的会议
|
||
- 不返回管理字段：
|
||
- `creatorUserID`（创建者ID）
|
||
- `ex`（扩展字段）
|
||
- `createTime`（创建时间）
|
||
- `updateTime`（更新时间）
|
||
- `estimatedCount`（预估人数）
|
||
- `anchorUserIDs`（主播ID列表，只返回 `anchorUsers`）
|
||
- 不支持按创建者查询（没有 `creatorUserID` 参数）
|
||
|
||
### 7. 主播信息
|
||
|
||
- 用户端接口只返回 `anchorUsers`（主播详细信息）
|
||
- 主播信息包含：`userID`、`nickname`、`faceURL` 等
|
||
|
||
### 8. 群聊关联
|
||
|
||
- 每个会议都会关联一个群聊
|
||
- 通过 `groupID` 字段可以获取关联的群聊ID
|
||
- 可以使用群聊相关接口（`/group/*`）操作关联的群聊
|
||
|
||
### 9. 会议状态流转
|
||
|
||
```
|
||
1（已预约） → 2（进行中） → 3（已结束）
|
||
↓
|
||
4（已取消）
|
||
```
|
||
|
||
- 用户端只能查看状态 **1（已预约）** 和 **2（进行中）** 的会议
|
||
- 状态 **3（已结束）** 和 **4（已取消）** 的会议对用户端不可见
|
||
|
||
---
|
||
|
||
## 接口汇总表
|
||
|
||
| 接口路径 | 方法 | 描述 | 权限要求 |
|
||
|---------|------|------|---------|
|
||
| `/meeting/get_meeting` | POST | 获取会议信息 | 登录用户 |
|
||
| `/meeting/get_meetings_public` | POST | 获取会议列表 | 登录用户 |
|
||
|
||
---
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/get_meeting \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"meetingID": "meeting123"
|
||
}'
|
||
```
|
||
|
||
### 获取会议列表
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/get_meetings_public \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"status": 1,
|
||
"keyword": "产品",
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 会议签到
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/check_in \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"meetingID": "meeting123"
|
||
}'
|
||
```
|
||
|
||
### 检查用户是否已签到
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/check_user_check_in \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"meetingID": "meeting123"
|
||
}'
|
||
```
|
||
|
||
### 获取会议签到列表
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/get_check_ins \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"meetingID": "meeting123",
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 获取会议签到统计
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/meeting/get_check_in_stats \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"meetingID": "meeting123"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新时间**: 2025-01-23
|
||
|