wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: API 文档按端+模块二级目录重组

Browse Source 
- 前台用户端 API 迁移到 frontend/ 目录（auth/contact/im/meeting/notify）
- 后台管理端 admin.md 拆分为 admin/ 目录下 4 个文档（auth/user/meeting/system）
- WebSocket 协议保留在根目录（跨端通用）
- 更新 README 导航为两级结构，补充目录结构说明
- 更新所有文档间的交叉引用路径

Made-with: Cursor
This commit is contained in:
bujinyuan
2026-02-28 09:52:52 +08:00
parent 44fa5a3830
commit 7dcd89c7fc
12 changed files with 390 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/api/frontend/auth.md Normal file
View 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-27 10:00:00"
}
}
```
---
## 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/frontend/contact.md Normal file
View 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/frontend/im.md Normal file
View 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-27 10:30:00"
},
"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-27 11:00:00"
},
"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-20 09:00:00"
}
}
```
---
## 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-27 10:28:00"
},
{
"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-27 10:29:00"
}
],
"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/frontend/meeting.md Normal file
View 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-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）
**说明：** 返回当前用户参与过的已结束会议，按结束时间倒序排列。

93
docs/api/frontend/notify.md Normal file
View 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-27 10:00:00"
},
{
"id": 2,
"type": "friend_request",
"title": "好友申请",
"content": "李四请求添加你为好友",
"extra": {
"from_user_id": 2,
"from_username": "lisi",
"message": "我是你的同事"
},
"is_read": false,
"created_at": "2026-02-27 09:30:00"
}
],
"total": 15,
"page": 1,
"page_size": 20
}
}
```
---
## 2. 标记通知已读
`PUT /api/v1/notifications/:id/read`
**权限：** 需认证
**路径参数：** `id` — 通知 ID
---
## 3. 全部标记已读
`PUT /api/v1/notifications/read-all`
**权限：** 需认证
**说明：** 将当前用户的所有未读通知标记为已读。