From 7506c88194fc01f0953902bfeb80501e6a1fc155 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=A5=BF=E8=A1=97=E9=95=BF=E5=AE=89?= Date: Sun, 12 Oct 2025 20:36:42 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?= =?UTF-8?q?=20/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 接口文档（REST API） — 聊天系统.md | 401 +++++++++++++++++++++++++++++ 数据字典.md | 17 +- 2 files changed, 412 insertions(+), 6 deletions(-) create mode 100644 接口文档（REST API） — 聊天系统.md diff --git a/接口文档（REST API） — 聊天系统.md b/接口文档（REST API） — 聊天系统.md new file mode 100644 index 0000000..8c9dfac --- /dev/null +++ b/接口文档（REST API） — 聊天系统.md @@ -0,0 +1,401 @@ +# 接口文档（REST API） — 聊天系统 + +> 统一响应格式（JSON） + +``` +{ + "code": 0, + "message": "请求成功", + "data": {} +} +``` + +- `code`：参照响应 Code 规范（0 成功，非 0 为错误）。 +- `message`：提示文本。 +- `data`：返回主体。 + +------ + +## 通用约定 + +- 所有需要登录的接口必须在 Header 中带 `Authorization: Bearer `。 +- 时间戳统一使用 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 ` +- 响应 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` \ No newline at end of file diff --git a/数据字典.md b/数据字典.md index 8fa2f74..9ad0612 100644 --- a/数据字典.md +++ b/数据字典.md @@ -9,6 +9,7 @@ | Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 | | Username | VARCHAR(50) | 是 | / | / | 唯一 | 唯一用户名 | admin | | Password | VARCHAR(50) | 是 | / | / | / | 用户密码 | 123456 | +| NickName | VARCHAR(50) | 是 | / | / | / | 用户昵称 | / | | OlineStatus | TINYINT | 是 | 0 | / | / | 用户在线状态
0（默认）：不在线
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 | / | / | 聊天类型
（0：私聊,1：群聊） | 0 | -| MsgType | TINYINT | 是 | 0 | / | / | 消息类型
(0:文本,1：图片,2：语音,3：视频,4：文件，5：语音聊天,6：视频聊天) | 0 | -| Content | TEXT | 否 | / | | | | | +| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 | +| --------- | -------- | -------- | -------- | -------------- | --------- | ------------------------------------------------------------ | ------ | +| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 | +| ChatType | TINYINT | 是 | 0 | / | / | 聊天类型
（0：私聊,1：群聊） | 0 | +| MsgType | TINYINT | 是 | 0 | / | / | 消息类型
(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