# 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