Merge pull request '上传文件至 /' (#6) from nanxun-patch-1 into main
Reviewed-on: code/Chat#6
This commit is contained in:
commit
33063ed31c
401
接口文档（REST API） — 聊天系统.md
Normal file
401
接口文档（REST API） — 聊天系统.md
Normal file
@ -0,0 +1,401 @@
|
||||
# 接口文档（REST API） — 聊天系统
|
||||
|
||||
> 统一响应格式（JSON）
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "请求成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `code`：参照响应 Code 规范（0 成功，非 0 为错误）。
|
||||
- `message`：提示文本。
|
||||
- `data`：返回主体。
|
||||
|
||||
------
|
||||
|
||||
## 通用约定
|
||||
|
||||
- 所有需要登录的接口必须在 Header 中带 `Authorization: Bearer <token>`。
|
||||
- 时间戳统一使用 Unix 秒。
|
||||
- 分页统一采用 `page`（第几页，从1开始）与 `limit`（每页大小）或基于时间/消息ID的 `afterMessageId` / `beforeTimestamp`。
|
||||
- 幂等性：对于可能重试的写操作，请求体中带 `requestId`。
|
||||
- Content-Type: `application/json`（文件上传除外）。
|
||||
- 返回错误码请参考前面的响应 Code 文档。
|
||||
|
||||
------
|
||||
|
||||
## 目录
|
||||
|
||||
1. 鉴权（Auth）
|
||||
2. 用户（User）
|
||||
3. 好友（Friend）
|
||||
4. 会话（Conversation）
|
||||
5. 消息（Message）
|
||||
6. 文件/上传（File）
|
||||
7. 群组（Group）
|
||||
8. 通知（Notification）
|
||||
9. 管理后台（Admin）
|
||||
10. 常见错误与限流
|
||||
|
||||
------
|
||||
|
||||
## 1. 鉴权（Auth）
|
||||
|
||||
### 1.1 注册
|
||||
|
||||
- URL: `POST /api/v1/auth/register`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"username": "alice",
|
||||
"password": "password123",
|
||||
"phone": "13800000000",
|
||||
"email":"admin@admin.com",
|
||||
"nickname":"测试用户",
|
||||
"avatar": "https://cdn.example.com/avatar/1001.png",
|
||||
}
|
||||
```
|
||||
|
||||
- 成功响应：
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "注册成功",
|
||||
"data": { "userId": 1001 }
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 登录（返回 Token）
|
||||
|
||||
- URL: `POST /api/v1/auth/login`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"username": "alice",
|
||||
"password": "password123",
|
||||
"deviceId": "uuid-device-001"
|
||||
}
|
||||
```
|
||||
|
||||
- 成功响应：
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"token": "eyJ....",
|
||||
"expires_in": 3600,
|
||||
"refreshToken": "rft-xxxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 刷新 Token
|
||||
|
||||
- URL: `POST /api/v1/auth/refresh`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{ "refreshToken": "rft-xxxx", "deviceId": "uuid-device-001" }
|
||||
```
|
||||
|
||||
- 响应同登录（返回新 token）。
|
||||
|
||||
------
|
||||
|
||||
## 2. 用户（User）
|
||||
|
||||
### 2.1 获取当前用户信息
|
||||
|
||||
- URL: `GET /api/v1/user/me`
|
||||
- Header: `Authorization: Bearer <token>`
|
||||
- 响应 data 示例：
|
||||
|
||||
```
|
||||
{
|
||||
"id": 1001,
|
||||
"username": "alice",
|
||||
"nickname": "Alice",
|
||||
"avatar": "https://cdn.example.com/avatar/1001.png",
|
||||
"status": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 修改用户资料
|
||||
|
||||
- URL: `PUT /api/v1/user/profile`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"nickname": "小艾",
|
||||
"olinestatus": "0",
|
||||
"avatar": "https://..."
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 根据 id 查询用户（用于搜索/加好友）
|
||||
|
||||
- URL: `GET /api/v1/user/{userId}`
|
||||
- 响应含基本公开信息（不含敏感字段）。
|
||||
|
||||
------
|
||||
|
||||
## 3. 好友（Friend）
|
||||
|
||||
### 3.1 发送好友申请
|
||||
|
||||
- URL: `POST /api/v1/friend/request`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"toUserId": 1002,
|
||||
"Description": "我们在项目中认识，申请加好友",
|
||||
"requestId": "uuid-req-001" // 幂等字段
|
||||
}
|
||||
```
|
||||
|
||||
- 成功返回 `requestId` 或新记录 id。
|
||||
|
||||
### 3.2 列出好友申请（收/发）
|
||||
|
||||
- URL: `GET /api/v1/friend/requests?type=received|sent&page=1&limit=20`
|
||||
|
||||
### 3.3 处理好友申请（同意/拒绝）
|
||||
|
||||
- URL: `POST /api/v1/friend/request/{requestId}/handle`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{ "action": "accept" } // accept | reject
|
||||
```
|
||||
|
||||
### 3.4 获取好友列表
|
||||
|
||||
- URL: `GET /api/v1/friend/list?page=1&limit=50`
|
||||
- 返回：好友数组（id, nickname, avatar, remark）
|
||||
|
||||
### 3.5 删除好友 / 拉黑
|
||||
|
||||
- URL: `DELETE /api/v1/friend/{friendId}`
|
||||
- URL: `POST /api/v1/friend/{friendId}/block`
|
||||
|
||||
------
|
||||
|
||||
## 4. 会话（Conversation）
|
||||
|
||||
### 4.1 获取会话列表（聊天列表）
|
||||
|
||||
- URL: `GET /api/v1/conversations?page=1&limit=50`
|
||||
- 返回每条会话示例：
|
||||
|
||||
```
|
||||
{
|
||||
"targetId": 1002,
|
||||
"chatType": "single",
|
||||
"lastMessage": { "messageId": 50001, "contentType":"text", "content":"你好", "timestamp": 1700000000 },
|
||||
"unreadCount": 3,
|
||||
"updatedAt": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 删除会话（清空会话/历史）
|
||||
|
||||
- URL: `DELETE /api/v1/conversation/{chatType}/{targetId}`
|
||||
- 注：chatType 为 `single` 或 `group`。删除会影响客户端显示/未读计数，历史消息视策略保留或软删除。
|
||||
|
||||
------
|
||||
|
||||
## 5. 消息（Message）
|
||||
|
||||
> 说明：即时消息优先通过 WebSocket 发送/接收；REST 接口用于历史消息读取、离线发送（备用）、ACK、撤回等。
|
||||
|
||||
### 5.1 发送消息（HTTP 版备用）
|
||||
|
||||
- URL: `POST /api/v1/message/send`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"requestId": "uuid-msg-001",
|
||||
"from": 1001,
|
||||
"to": 1002,
|
||||
"chatType": "single",
|
||||
"contentType": "text",
|
||||
"content": "你好",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
- 响应：
|
||||
|
||||
```
|
||||
{ "code": 0, "data": { "messageId": 50001, "status": "sent" } }
|
||||
```
|
||||
|
||||
- 注意：若用户在线，后端可同时通过 WebSocket 推送到接收端。
|
||||
|
||||
### 5.2 拉取历史消息（分页或基于消息ID）
|
||||
|
||||
- URL: `GET /api/v1/messages/history?chatType=single&targetId=1002&beforeMessageId=50000&limit=50`
|
||||
- 返回消息数组（按时间倒序或正序，双方约定）。
|
||||
|
||||
### 5.3 同步未读/离线消息（登录/重连时）
|
||||
|
||||
- URL: `GET /api/v1/messages/sync?since=1700000000` 或 `afterMessageId=xxxxx`
|
||||
- 返回：所有未读/未同步消息（或给定时间段内消息）。
|
||||
|
||||
### 5.4 消息已读/送达回执（HTTP）
|
||||
|
||||
- URL: `POST /api/v1/message/ack`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"messageId": 50001,
|
||||
"status": "read", // delivered | read
|
||||
"chatType": "single",
|
||||
"from": 1002, // ack 发送者（接收方）
|
||||
"to": 1001
|
||||
}
|
||||
```
|
||||
|
||||
### 5.5 撤回消息
|
||||
|
||||
- URL: `POST /api/v1/message/{messageId}/recall`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{ "requestId": "uuid-recall-001" }
|
||||
```
|
||||
|
||||
- 响应成功后，服务器会向相关在线端推送 `MESSAGE_RECALL` 事件，更新 message.status。
|
||||
|
||||
### 5.6 删除单条消息（客户端侧删除/服务端删除）
|
||||
|
||||
- URL: `DELETE /api/v1/message/{messageId}`
|
||||
- 注意区分“仅自己删除”与“全局删除（撤回）”。
|
||||
|
||||
------
|
||||
|
||||
## 6. 文件/上传（File）
|
||||
|
||||
### 6.1 上传文件（图片/语音/文档）
|
||||
|
||||
- URL: `POST /api/v1/file/upload`
|
||||
- Content-Type: `multipart/form-data`
|
||||
- 字段：`file`，可选 `type`、`attachedMessageRequestId`
|
||||
- 成功响应：
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"fileId": 9001,
|
||||
"fileUrl": "https://oss.example.com/xxx.jpg",
|
||||
"fileName": "xxx.jpg",
|
||||
"fileSize": 12345
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 建议：文件先上传到对象存储（OSS/S3/MinIO），返回 URL，消息发送时引用该 URL（message.content）。
|
||||
|
||||
### 6.2 下载文件
|
||||
|
||||
- 直接访问 `fileUrl` 或通过后端代理下载（带鉴权）。
|
||||
|
||||
------
|
||||
|
||||
## 7. 群组（Group）
|
||||
|
||||
### 7.1 创建群
|
||||
|
||||
- URL: `POST /api/v1/group/create`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{
|
||||
"name": "项目群",
|
||||
"ownerId": 1001,
|
||||
"memberIds": [1002,1003],
|
||||
"maxMembers": 500,
|
||||
"needApproval": true // 加群是否需要审批
|
||||
}
|
||||
```
|
||||
|
||||
- 响应返回 `groupId`。
|
||||
|
||||
### 7.2 获取群信息
|
||||
|
||||
- URL: `GET /api/v1/group/{groupId}`
|
||||
|
||||
### 7.3 邀请入群
|
||||
|
||||
- URL: `POST /api/v1/group/{groupId}/invite`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{ "inviter":1001, "invitees":[1004,1005], "message":"来加入我们吧" }
|
||||
```
|
||||
|
||||
- 若群需要审批，发送 `group_join_request`；否则直接加入并更新 group_member。
|
||||
|
||||
### 7.4 加群申请（用户申请）
|
||||
|
||||
- URL: `POST /api/v1/group/{groupId}/join-request`
|
||||
- 管理员/群主处理：`POST /api/v1/group/join-request/{requestId}/handle`
|
||||
|
||||
### 7.5 群成员管理（踢人/设管理员/退出群）
|
||||
|
||||
- 踢人：`POST /api/v1/group/{groupId}/kick`
|
||||
- 退出：`POST /api/v1/group/{groupId}/leave`
|
||||
- 设管理员：`POST /api/v1/group/{groupId}/role`
|
||||
|
||||
------
|
||||
|
||||
## 8. 通知（Notification）
|
||||
|
||||
### 8.1 获取通知列表
|
||||
|
||||
- URL: `GET /api/v1/notifications?page=1&limit=50`
|
||||
- 类型包含：好友请求、群邀请、系统公告等。
|
||||
|
||||
### 8.2 标记通知为已读
|
||||
|
||||
- URL: `POST /api/v1/notification/{notificationId}/read`
|
||||
|
||||
------
|
||||
|
||||
## 9. 管理后台（Admin）
|
||||
|
||||
> 仅管理员或具备权限的账号访问（需在 token 中包含角色或额外权限校验）
|
||||
|
||||
### 9.1 管理员登录（同 auth）
|
||||
|
||||
- URL: `POST /api/v1/admin/login`
|
||||
|
||||
### 9.2 查询用户列表
|
||||
|
||||
- URL: `GET /api/v1/admin/users?page=1&limit=50&keyword=alice`
|
||||
|
||||
### 9.3 禁用/启用用户
|
||||
|
||||
- URL: `POST /api/v1/admin/user/{userId}/ban`
|
||||
- 请求：
|
||||
|
||||
```
|
||||
{ "action": "ban", "reason": "违规传播" } // action: ban | unban
|
||||
```
|
||||
|
||||
### 9.4 查询操作日志
|
||||
|
||||
- URL: `GET /api/v1/admin/logs?page=1&limit=50`
|
||||
17
数据字典.md
17
数据字典.md
@ -9,6 +9,7 @@
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| Username | VARCHAR(50) | 是 | / | / | 唯一 | 唯一用户名 | admin |
|
||||
| Password | VARCHAR(50) | 是 | / | / | / | 用户密码 | 123456 |
|
||||
| NickName | VARCHAR(50) | 是 | / | / | / | 用户昵称 | / |
|
||||
| OlineStatus | TINYINT | 是 | 0 | / | / | 用户在线状态<br />0（默认）：不在线<br />1：在线 | 0 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 账户创建时间 | 2025/9/29 |
|
||||
| Updated | DATETIME | 否 | / | / | / | 账户修改时间 | 2024/9/29 |
|
||||
@ -84,12 +85,16 @@
|
||||
|
||||
#### 表说明：用户消息
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| -------- | -------- | -------- | ------ | ------- | --------- | ------------------------------------------------------------ | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| ChatType | TINYINT | 是 | 0 | / | / | 聊天类型<br />（0：私聊,1：群聊） | 0 |
|
||||
| MsgType | TINYINT | 是 | 0 | / | / | 消息类型<br />(0:文本,1：图片,2：语音,3：视频,4：文件，5：语音聊天,6：视频聊天) | 0 |
|
||||
| Content | TEXT | 否 | / | | | | |
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| --------- | -------- | -------- | -------- | -------------- | --------- | ------------------------------------------------------------ | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| ChatType | TINYINT | 是 | 0 | / | / | 聊天类型<br />（0：私聊,1：群聊） | 0 |
|
||||
| MsgType | TINYINT | 是 | 0 | / | / | 消息类型<br />(0:文本,1：图片,2：语音,3：视频,4：文件，5：语音聊天,6：视频聊天) | 0 |
|
||||
| Content | TEXT | 是 | / | / | / | 消息内容 | / |
|
||||
| Sender | INT | 是 | / | 外键(Users.Id) | 索引 | 发送者 | / |
|
||||
| Recipient | INT | 是 | / | / | / | 接收者（私聊为用户ID，群聊为群聊ID） | / |
|
||||
| State | TINYINT | 是 | 0 | / | / | 消息状态(0:已发送,1:已撤回) | / |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 发送时间 | 、 |
|
||||
|
||||
### 表名：Files
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user