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
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（非群主/管理员无权操作）
|
||||
Reference in New Issue
Block a user