204 lines
5.8 KiB
Markdown
204 lines
5.8 KiB
Markdown
# 会议模块 API (Meeting)
|
||
|
||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](../README.md)
|
||
> 会议中的实时信令（Transport/Producer/Consumer）通过 WebSocket 完成，见 [websocket.md](../websocket.md)
|
||
|
||
---
|
||
|
||
## ⚠️ 文档状态说明（2026-04-21 更新）
|
||
|
||
**本文档为系统总设计阶段的占位版本，下方所列接口清单尚未落地实现。**
|
||
|
||
Phase 2e-2 已进入设计阶段，专用设计文档 [`docs/plans/2026-04-21-phase2e-2-design.md`](../../plans/2026-04-21-phase2e-2-design.md) §6.2 锁定了 **MVP 最终 12 个接口**的路径与行为。与本文旧版接口清单的关键差异：
|
||
|
||
| 维度 | 本文档旧版（总设计） | Phase 2e-2 MVP（即将实施） |
|
||
|---|---|---|
|
||
| 路径前缀 | `/api/v1/meetings/*` | `/api/v1/meeting/rooms/*`（更符合 REST 语义） |
|
||
| 范围 | 含预约会议 + 即将开始/历史会议 | MVP 仅即时会议；预约推迟到 Phase 2e-3 |
|
||
| 密码存储 | 明文 `password` | bcrypt `password_hash` |
|
||
| 主持人控制 | 仅 join/leave | 新增 `kick` / `transfer-host` / 结束会议 / 邀请 |
|
||
| 会议内聊天 | 无 | 新增 `POST /:code/chats` + `GET /:code/chats` |
|
||
| 邀请链接 | 无 | 新增 `POST /invite-tokens/:token/redeem` |
|
||
|
||
**实施指引**：
|
||
- **Phase 2e-2 开发时**：请以 Phase 2e-2 专用设计文档 §6.2 为唯一实现口径；Task 5（会议 REST 接口）完成后**全量重写**本文档
|
||
- **其他模块集成时**：请勿照搬本文旧接口路径；若需调用 meeting 模块 API 请先阅读 Phase 2e-2 设计文档
|
||
|
||
以下旧版占位内容保留供历史对照，直到 Phase 2e-2 实施完成后整体替换。
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| 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-27 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 预约会议
|
||
|
||
`POST /api/v1/meetings/schedule`
|
||
|
||
**权限：** 需认证
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| title | string | 是 | 会议标题 |
|
||
| scheduled_at | string | 是 | 预约时间，格式：`yyyy-MM-dd HH:mm:ss`，如 `"2026-03-01 14:00:00"` |
|
||
| 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-27 10:00:00",
|
||
"participants": [
|
||
{ "user_id": 1, "nickname": "张三", "role": 1, "joined_at": "2026-02-27 10:00:00" },
|
||
{ "user_id": 2, "nickname": "李四", "role": 0, "joined_at": "2026-02-27 10:01:00" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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）
|
||
|
||
**说明：** 返回当前用户参与过的已结束会议，按结束时间倒序排列。
|