Merge pull request '更新 📘 接口响应 Code 设计文档.md' (#7) from test into main
Reviewed-on: code/Chat#7
This commit is contained in:
+1094
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,141 @@
|
||||
# IM 系统消息存储与推送策略文档
|
||||
|
||||
## 1. 概述
|
||||
|
||||
本策略文档定义了 **消息在系统中的存储、读取和推送流程**，目标是：
|
||||
|
||||
- 保证 **消息实时性**
|
||||
- 支持 **离线消息存储与同步**
|
||||
- 支持 **多端登录同步**
|
||||
- 支持 **单聊、群聊及系统消息**
|
||||
|
||||
------
|
||||
|
||||
## 2. 消息存储策略
|
||||
|
||||
### 2.1 消息表设计
|
||||
|
||||
表结构参考前期设计：
|
||||
|
||||
| 表名 | 作用 |
|
||||
| ------------ | ------------------------------------------------------------ |
|
||||
| Messages | 存储所有聊天消息（单聊/群聊） |
|
||||
| Conversation | 缓存用户最近会话信息（last_message_id, target_id, unread_count） |
|
||||
| Files | 附件 / 图片 / 语音存储URL |
|
||||
|
||||
------
|
||||
|
||||
### 2.2 消息存储规则
|
||||
|
||||
1. **单聊消息**
|
||||
- 写入 `Messages` 表
|
||||
- 更新发送者和接收者 `Conversation` 表
|
||||
- 更新 `UnreadCount`
|
||||
2. **群聊消息**
|
||||
- 写入 `Messages` 表
|
||||
- 更新群成员对应的 `Conversation` 表（except 发送者）
|
||||
- 更新每个成员的 `UnreadCount`
|
||||
3. **文件消息**
|
||||
- 文件存储到对象存储（OSS/S3/MinIO）
|
||||
- `Messages.Content` 存文件 URL + metadata
|
||||
4. **消息撤回**
|
||||
- 消息允许撤回时，修改 `message.status = 1
|
||||
- 更新 `Conversation.LastMessageId`（如撤回的是最后一条消息）
|
||||
|
||||
------
|
||||
|
||||
## 3. 消息推送策略
|
||||
|
||||
### 3.1 推送原则
|
||||
|
||||
- **实时性**：在线用户立即通过 WebSocket 推送
|
||||
- **可靠性**：离线用户存储消息，登录时同步
|
||||
- **顺序保证**：消息按 `timestamp` 或 `messageId` 顺序发送
|
||||
- **幂等性**：客户端可根据 `messageId` 去重
|
||||
|
||||
------
|
||||
|
||||
### 3.2 单聊推送流程
|
||||
|
||||
1. 发送者通过 WebSocket 或 HTTP API 发送消息
|
||||
2. 服务端写入 `Messages` 表
|
||||
3. 查询接收者是否在线
|
||||
- **在线**：通过 WebSocket 推送
|
||||
- **离线**：存储到 Redis 或 `Conversation.UnreadCount`
|
||||
4. 接收者收到消息后发送 `MESSAGE_ACK`
|
||||
5. //暂不要求：更新消息状态（已送达 / 已读）
|
||||
|
||||
------
|
||||
|
||||
### 3.3 群聊推送流程
|
||||
|
||||
1. 发送者发送群消息
|
||||
2. 服务端写入 `Message`s 表
|
||||
3. 查询群成员列表（`GroupMember` 表）
|
||||
4. 遍历成员：
|
||||
- **在线成员**：WebSocket 推送
|
||||
- **离线成员**：增加 `UnreadCount`，保存在 Redis/数据库
|
||||
5. //暂不要求：接收者回 ACK 后更新 `message_receipt`（已读）
|
||||
|
||||
------
|
||||
|
||||
### 3.4 离线消息处理
|
||||
|
||||
- 离线消息存储位置：
|
||||
1. 数据库 `Messages` 表（长期保存）
|
||||
2. Redis 缓存（短期加速推送）
|
||||
- 客户端上线时：
|
||||
1. 请求 `/syncMessages` 接口
|
||||
2. 返回未读消息 + 未读计数
|
||||
- 消息同步完成后清除缓存或更新状态
|
||||
|
||||
------
|
||||
|
||||
### 3.5 多端同步策略
|
||||
|
||||
- 每个设备维护独立的 `deviceId`
|
||||
- WebSocket 推送时：
|
||||
- 排除发送设备
|
||||
- 推送给同账号其他设备
|
||||
- //暂不要求：消息回执：
|
||||
- 每端发送 ACK
|
||||
- 服务端更新 `Voncers` 和 `message_receipt`
|
||||
|
||||
------
|
||||
|
||||
## 4. 消息可靠性保障
|
||||
|
||||
| 场景 | 解决方案 |
|
||||
| ------------------ | ---------------------------------- |
|
||||
| 消息丢失 | 发送端生成 `requestId`，服务端去重 |
|
||||
| 消息顺序错乱 | 按 `messageId` 或 `timestamp` 排序 |
|
||||
| WebSocket 异常断开 | 客户端重连后同步离线消息 |
|
||||
| 群聊大消息量 | 异步推送 + 批量 ACK |
|
||||
|
||||
------
|
||||
|
||||
## 5. //暂不要求：高性能优化策略
|
||||
|
||||
1. **消息表索引**：`(chat_type, to_id, created_at)`
|
||||
2. **会话表缓存**：`conversation` 表避免全表查询
|
||||
3. **Redis 缓存**：用户在线状态、未读消息数
|
||||
4. **分表/分库**：按月或按用户分表
|
||||
5. **异步推送队列**：消息通过 MQ（Kafka/RabbitMQ）推送，保证高并发
|
||||
|
||||
------
|
||||
|
||||
## 6. 消息撤回与删除策略
|
||||
|
||||
1. **撤回条件**：超时限制（ 2 分钟内可撤回）
|
||||
2. **撤回操作**：
|
||||
- 更新 `message.status = 1`
|
||||
- 更新 `Conversation.LastMessageId`
|
||||
- 推送撤回事件到在线用户
|
||||
|
||||
------
|
||||
|
||||
## 7. 系统消息与通知策略
|
||||
|
||||
- 系统消息（好友申请、群邀请、公告）走 **同样的消息推送流程**
|
||||
- 保留在 `Notification` 表
|
||||
- 支持离线同步
|
||||
@@ -0,0 +1,115 @@
|
||||
# IM 系统鉴权与 Token 安全规范文档
|
||||
|
||||
## 1. 概述
|
||||
|
||||
本规范用于确保系统用户身份验证、消息安全和多端同步安全。
|
||||
鉴权体系采用 **Token（JWT 或自定义） + HTTPS/WebSocket** 方式。
|
||||
|
||||
------
|
||||
|
||||
## 2. 鉴权方式选择
|
||||
|
||||
| 方法 |
|
||||
| -------------------------------------- |
|
||||
| JWT（JSON Web Token）+ Redis黑名单机制 |
|
||||
|
||||
------
|
||||
|
||||
## 3. Token 生成规则
|
||||
|
||||
### 3.1 Token 内容结构（JWT 示例）
|
||||
|
||||
```
|
||||
{
|
||||
"userId": 1001, // 用户ID
|
||||
"iat": 1700000000, // 签发时间（Unix时间戳）
|
||||
"exp": 1700003600, // 过期时间
|
||||
"deviceId": "uuid-xxxx", // 设备ID，用于多端区分
|
||||
"role": "user" // 角色
|
||||
}
|
||||
```
|
||||
|
||||
- **签名算法**：HMAC-SHA256 或 RSA
|
||||
- **签名秘钥**：服务端统一管理，不暴露给客户端
|
||||
|
||||
------
|
||||
|
||||
### 3.2 Token 生成流程
|
||||
|
||||
1. 用户登录（用户名/密码）
|
||||
2. 验证用户名与密码正确
|
||||
3. 生成 Token，写入 Redis（可选）
|
||||
4. 返回 Token 给客户端
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
## 4. Token 使用
|
||||
|
||||
### 4.1 HTTP 接口鉴权
|
||||
|
||||
- 客户端请求带上 Header：
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
- 后端解析 Token：
|
||||
1. 校验签名
|
||||
2. 校验 exp 是否过期
|
||||
3. 校验 Redis 黑名单（可选）
|
||||
- 不通过返回 401 / code 1006
|
||||
|
||||
------
|
||||
|
||||
### 4.2 WebSocket 鉴权
|
||||
|
||||
- 建立连接时通过 Query 或 Header 传 Token：
|
||||
|
||||
```
|
||||
ws://example.com/ws?token=xxxx&deviceId=uuid-001
|
||||
```
|
||||
|
||||
- 握手阶段：
|
||||
1. 服务器验证 Token
|
||||
2. 成功返回 AUTH_SUCCESS
|
||||
3. 失败返回 AUTH_FAIL 并关闭连接
|
||||
|
||||
------
|
||||
|
||||
## 5. Token 过期策略
|
||||
|
||||
| 类型 | 建议值 | 说明 |
|
||||
| ------------------ | ---------------------- | ---------------------------------------- |
|
||||
| 短期 Token | 30 分钟 ~ 1 小时 | 防止长时间泄露 |
|
||||
| 长期 Refresh Token | 7 ~ 30 天 | 用于获取新 Token，安全性高 |
|
||||
| WebSocket 长连接 | Token 与短期有效期一致 | 客户端定期刷新 Token（心跳或重连时验证） |
|
||||
|
||||
### 5.1 Token 刷新流程
|
||||
|
||||
1. 客户端 Token 快过期时，调用刷新接口
|
||||
2. 服务端验证 Refresh Token
|
||||
3. 返回新 Token，更新 Redis / 黑名单
|
||||
|
||||
------
|
||||
|
||||
## 6. 多端登录处理
|
||||
|
||||
- **每个设备对应一个 deviceId**
|
||||
- Token 中绑定 deviceId
|
||||
- 多端策略：
|
||||
1. **允许多端同时登录**：每端单独维护 Token
|
||||
2. **限制单端登录**：新登录覆盖旧设备 Token
|
||||
3. **设备列表管理**：可查看在线设备并强制下线
|
||||
|
||||
@@ -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`
|
||||
+220
@@ -0,0 +1,220 @@
|
||||
# 数据字典
|
||||
|
||||
### 表名：Users
|
||||
|
||||
#### 表说明：储存用户个人信息
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ----------- | ----------- | -------- | -------- | ------- | --------- | ------------------------------------------------ | --------- |
|
||||
| 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 |
|
||||
| Status | TINYINT | 是 | 1 | / | / | 账户状态<br />(0：未激活,1：正常,2：封禁) | 1 |
|
||||
| IsDeleted | TINYINT | 是 | 0 | / | / | 软删除标识<br />0：账号正常<br />1：账号已删除 | 0 |
|
||||
|
||||
### 表名：Friends
|
||||
|
||||
#### 表说明：好友关系映射
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| -------- | -------- | -------- | -------- | ---------------- | --------- | ------------------------------------------------------------ | --------- |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| UserId | INT | 是 | / | 外键（Users.Id） | 索引 | 用户ID | 1 |
|
||||
| FriendId | INT | 是 | / | 外键（Users.Id） | 索引 | 用户2ID | 2 |
|
||||
| Status | TINYINT | 是 | 0 | / | / | 当前好友关系状态<br />（0：待通过,1：已添加,2：已拒绝,3：已拉黑） | 0 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 好友关系创建时间 | 2025/9/29 |
|
||||
|
||||
### 表名：Groups
|
||||
|
||||
#### 表说明：群聊
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ---------------- | ------------- | -------- | -------- | ---------------- | --------- | ------------------------------------------------------------ | ------------------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| Name | VARCHAT（20） | 是 | / | / | / | 群聊名称 | 测试群聊1 |
|
||||
| GroupMaster | INT | 是 | / | 外键（Users.Id） | 索引 | 群主 | 1 |
|
||||
| Auhority | TINYINT | 是 | 0 | / | / | 群权限<br />（0：需管理员同意,1：任意人可加群,2：不允许任何人加入） | 0 |
|
||||
| AllMembersBanned | TINYINT | 是 | 0 | / | / | 全员禁言（0允许发言，2全员禁言） | 0 |
|
||||
| Status | TINYINT | 是 | 1 | / | / | 群聊状态<br />(1：正常,2：封禁) | 1 |
|
||||
| Announcement | TEXT | 否 | null | / | / | 群公告 | 这是一条测试群公告 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 群聊创建时间 | 2025/9/29 |
|
||||
|
||||
### 表名：GroupMember
|
||||
|
||||
#### 表说明：群成员
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------- | -------- | -------- | -------- | --------------- | --------- | -------------------------------------- | -------- |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| UserId | INT | 是 | / | 外键(Users.Id) | 索引 | 用户编号 | 1 |
|
||||
| GroupId | INT | 是 | / | 外键(Groups.Id) | 索引 | 群聊编号 | 1 |
|
||||
| Role | TINYINT | 是 | 0 | / | / | 成员角色（0:普通成员,1:管理员,2:群主） | 1 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 加入群聊时间 | 1970/1/1 |
|
||||
|
||||
### 表名：GroupInvite
|
||||
|
||||
#### 表说明：群聊邀请
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ----------- | -------- | -------- | -------- | --------------- | --------- | ------------------------------------------------ | -------- |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| GroupId | INT | 是 | / | 外键(Groups.Id) | 索引 | 群聊编号 | 1 |
|
||||
| InvitedUser | INT | 是 | / | 外键(Users.Id) | 索引 | 被邀请用户 | 1 |
|
||||
| InviteUser | INT | 是 | / | 外键(Users.Id) | 索引 | 邀请用户 | 1 |
|
||||
| State | TINYINT | 是 | 0 | / | / | 当前状态(0:待被邀请人同意<br />1:被邀请人已同意) | 1 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | 1970/1/1 |
|
||||
|
||||
### 表名：GroupRequest
|
||||
|
||||
#### 表说明：群聊入群申请
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ----------- | -------- | -------- | --------------- | --------------- | --------- | --------------------------------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| GroupId | INT | 是 | / | 外键(Groups.Id) | 索引 | 群聊编号 | 1 |
|
||||
| UserId | INT | 是 | / | 外键(Users.Id) | 索引 | 申请人 | 1 |
|
||||
| State | TINYINT | 是 | 0 | / | / | 申请状态（0:待管理员同意,1:已拒绝,2：已同意） | 1 |
|
||||
| Description | TEXT | 是 | xxx申请加入群聊 | / | / | 入群附言 | / |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | / |
|
||||
|
||||
### 表名：Messages
|
||||
|
||||
#### 表说明：用户消息
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| --------- | -------- | -------- | -------- | -------------- | --------- | ------------------------------------------------------------ | ------ |
|
||||
| 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
|
||||
|
||||
#### 表说明：文件
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| --------- | ------------ | -------- | -------- | ------------------- | --------- | -------------------- | ----------------------- |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| Name | VARCHAR(50) | 是 | / | / | / | 文件名 | 测试文件.txt |
|
||||
| URL | VARCHAR(100) | 是 | / | / | / | 文件储存URL | https://baidu.com/1.txt |
|
||||
| Size | INT | 是 | / | / | / | 文件大小（单位：KB） | 1024 |
|
||||
| Type | VARCHAT(10) | 是 | / | / | / | 文件类型 | txt |
|
||||
| MessageId | INT | 是 | / | 外键（Messages.Id） | 索引 | 关联消息ID | 1 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | 2025/9/29 |
|
||||
|
||||
### 表名：Notifications
|
||||
|
||||
#### 表说明：系统通知消息
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------- | ------------ | -------- | -------- | -------------- | --------- | ------------------------ | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| UserId | INT | 否 | / | 外键(Users.Id) | 索引 | 接收人（为空为全体通知） | 1 |
|
||||
| NType | TINYINT | 是 | 0 | / | / | 通知类型(0：文本) | 0 |
|
||||
| Title | NVARCHAR(20) | 是 | / | / | / | 通知标题 | 1 |
|
||||
| Content | TEXT | 是 | / | / | / | 通知内容 | 1 |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | / |
|
||||
|
||||
### 表名：Conversations
|
||||
|
||||
#### 表说明：用户会话
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------------- | -------- | -------- | ------ | ----------------- | --------- | ------------------------------------ | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| UserId | INT | 是 | / | 外键(Users.Id) | 索引 | 用户 | 1 |
|
||||
| TargetId | INT | 是 | / | / | / | 对方ID（群聊为群聊ID，单聊为单聊ID） | 1 |
|
||||
| MsgType | INT | 是 | / | / | / | 消息类型（同Messages.MsgType） | / |
|
||||
| lastMessageId | INT | 是 | / | 外键(Messages.Id) | 索引 | 最后一条消息ID | 1 |
|
||||
| unreadCount | INT | 是 | / | / | / | 未读消息数 | / |
|
||||
|
||||
### 表名：FriendRequest
|
||||
|
||||
#### 表说明：好友申请
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------------ | -------- | -------- | ------------------- | ---------------- | --------- | ------------------------------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| RequestUser | INT | 是 | / | 外键(Users.Id) | 索引 | 申请人 | / |
|
||||
| ResponseUser | INT | 是 | / | 外键（Users.Id） | 索引 | 被申请人 | / |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 申请时间 | / |
|
||||
| Description | TEXT | 否 | xxx申请添加你为好友 | / | / | 申请附言 | / |
|
||||
| State | TINYINT | 是 | 0 | / | / | 申请状态（0：待通过,1:拒绝,2:同意,3：拉黑） | / |
|
||||
|
||||
### 表名：Devices
|
||||
|
||||
#### 表说明：用户设备
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| --------- | -------- | -------- | -------- | -------------- | --------- | ---------------------------------------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| UserId | INT | 是 | / | 外键(Users.Id) | 索引 | 设备所属用户 | / |
|
||||
| DType | TINYINT | 是 | / | / | / | 设备类型（<br />0:Android,1:Ios,2:PC,3：Pad,4:未知） | 0 |
|
||||
| LastLogin | DATETIME | 是 | 1970/1/1 | / | / | 最后一次登录 | / |
|
||||
|
||||
### 表名：Login_Log
|
||||
|
||||
#### 表说明：登录日志
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------- | -------- | -------- | -------- | -------------- | --------- | ---------------------------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| DType | TINYINT | 是 | / | / | / | 设备类型（通Devices/DType） | / |
|
||||
| Logined | DATETIME | 是 | 1970/1/1 | / | / | 登录时间 | / |
|
||||
| UserId | INT | 是 | / | 外键(Users.Id) | / | 登录用户 | / |
|
||||
| State | TINYINT | 是 | 0 | / | / | 登录状态(0:登陆成功,1:未验证,2:已被拒绝) | / |
|
||||
|
||||
### 表名：Admins
|
||||
|
||||
#### 表说明：系统管理员
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| -------- | ----------- | -------- | -------- | ---------------- | --------- | ----------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| Username | VARCHAR(50) | 是 | / | / | / | 用户名 | / |
|
||||
| Password | VARCHAR(50) | 是 | / | / | / | 密码 | / |
|
||||
| RoleId | INT | 是 | / | 外键（Roles.Id） | 索引 | 角色 | / |
|
||||
| State | TINYINT | 是 | 0 | / | / | 状态（0:正常，2：封禁） | / |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | / |
|
||||
| Updated | DATETIME | 是 | 1970/1/1 | / | / | 更新时间 | / |
|
||||
|
||||
### 表名：Roles
|
||||
|
||||
#### 表说明：角色
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ----------- | ----------- | -------- | -------- | ------- | --------- | -------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| Name | VARCHAR(20) | 是 | / | / | / | 角色名称 | / |
|
||||
| Description | TEXT | 是 | 空字符串 | / | / | 角色描述 | / |
|
||||
| Created | DATETIME | 是 | 1970/1/1 | / | / | 创建时间 | / |
|
||||
|
||||
### 表名：Permissions
|
||||
|
||||
#### 表说明：权限
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------- | ----------- | -------- | ------ | ------- | --------- | ----------------------------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| PType | INT | 是 | 0 | / | / | 权限类型(0:增,1:删,2:改,3:查) | / |
|
||||
| Name | VARCHAR(50) | 是 | / | / | / | 权限名称 | / |
|
||||
| Code | INT | 是 | / | / | / | 权限编码 | / |
|
||||
| Created | DATETIME | 是 | / | / | / | 创建时间 | / |
|
||||
|
||||
### 表名：PermissionARole
|
||||
|
||||
#### 表说明：权限角色关联
|
||||
|
||||
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
|
||||
| ------------ | -------- | -------- | ------ | ---------------------- | --------- | -------- | ------ |
|
||||
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
|
||||
| RoleId | INT | 是 | / | 外键（Roles.Id） | 索引 | 角色 | / |
|
||||
| PermissionId | INT | 是 | / | 外键（Permissions.Id） | 索引 | 权限 | / |
|
||||
@@ -0,0 +1,37 @@
|
||||
# 系统架构设计
|
||||
|
||||
## 1.1 系统概述
|
||||
- 项目名称：聊天系统
|
||||
- 项目类型：即时通讯（Web 端）
|
||||
- 技术栈：
|
||||
- 前端：Vue + WebSocket
|
||||
- 后端：.NET/C#
|
||||
- 数据库：MySQL + Redis
|
||||
- 消息队列：Kafka
|
||||
- 部署：Docker + Nginx + 云服务器
|
||||
|
||||
## 1.2 系统架构图
|
||||
- [前端] ↔ [WebSocket Server] ↔ [业务服务器] ↔ [数据库/缓存]
|
||||
|
||||
## 1.3 模块划分
|
||||
### 前端模块
|
||||
- 登录/注册
|
||||
- 好友列表
|
||||
- 单聊聊天窗口
|
||||
- 个人资料窗口
|
||||
- 语音/视频通话
|
||||
- 群聊聊天窗口
|
||||
- 文件/表情/图片发送
|
||||
|
||||
### 后端模块
|
||||
- 用户管理（注册、登录、资料）
|
||||
- 好友管理（加好友、删除、黑名单）
|
||||
- 消息管理（单聊、群聊、已读/未读、撤回）
|
||||
- 群聊管理（创建群、成员管理、公告）
|
||||
- 通知管理（好友请求、群邀请、系统消息）
|
||||
- 通话管理
|
||||
|
||||
### 中间件/第三方
|
||||
- WebSocket 实时通信
|
||||
- Redis 消息缓存
|
||||
- 文件存储（图片/语音/文件）
|
||||
@@ -0,0 +1,64 @@
|
||||
# 需求规格说明书（SRS）
|
||||
|
||||
## 1. 项目背景
|
||||
- #### 项目目标：
|
||||
|
||||
本项目旨在实现一个类似 QQ 的即时通讯系统，提供用户注册、好友聊天、群聊、文件传输等核心功能。
|
||||
|
||||
- 使用场景：学习练手 + 内部小团队沟通工具。
|
||||
|
||||
- #### 项目范围：
|
||||
|
||||
学习项目
|
||||
|
||||
- #### 业务价值：
|
||||
|
||||
学习项目
|
||||
|
||||
## 2. 用户需求
|
||||
- 普通用户：注册、登录、聊天、加好友
|
||||
- 管理员：封禁违规账号、管理群聊
|
||||
- 使用场景：1v1 聊天、群聊、发送文件、发送表情/图片等
|
||||
|
||||
## 3. 功能需求
|
||||
- ##### 3.1 账号系统
|
||||
- F-1 用户注册：支持手机号/邮箱注册，需验证唯一性。
|
||||
- F-2 用户登录：支持账号+密码、Token 鉴权。
|
||||
- F-3 用户资料：可修改头像、昵称、个性签名。
|
||||
|
||||
##### 3.2 好友系统
|
||||
- F-4 添加好友：通过账号/手机号搜索并申请。
|
||||
- F-5 好友请求：系统通知对方，同意/拒绝。
|
||||
- F-6 删除好友、拉黑。
|
||||
|
||||
##### 3.3 消息系统
|
||||
- F-7 单聊：支持文本、表情、图片、文件。
|
||||
- F-8 群聊：支持多人实时消息。
|
||||
- F-9 消息状态：已发送、已送达、已读（暂时只在数据库层面标记已读，不显示在客户端）。
|
||||
- F-10 消息管理：撤回、删除、搜索历史记录。
|
||||
|
||||
##### 3.4 群聊功能
|
||||
- F-11 创建群聊：指定群名称，邀请成员。
|
||||
- F-12 群管理：踢人、设管理员、发布公告。
|
||||
- F-13 群人数上限：本期 500 人。
|
||||
|
||||
##### 3.5 系统通知
|
||||
- F-14 好友申请通知。
|
||||
- F-15 群邀请通知。
|
||||
- F-16 新消息推送（WebSocket）。
|
||||
|
||||
## 4. 非功能需求
|
||||
- 实时性：消息延迟 ≤ 1 秒
|
||||
- 并发性：单群支持 ≥ 500 人在线聊天
|
||||
- 安全性：消息加密传输（WebSocket + TLS）
|
||||
- 可扩展性：后端支持水平扩展（分布式 IM 服务器） ***<u>此条暂不要求</u>***
|
||||
|
||||
## 5. 约束与假设
|
||||
- 本期仅支持 Web 端（PC + H5），移动端后续开发
|
||||
- 音视频通话仅提供基础功能，不做美颜、录屏
|
||||
|
||||
## 6.验收标准
|
||||
|
||||
- 两个用户能互加好友并聊天。
|
||||
- 群聊消息在 500 人场景下稳定传递。
|
||||
- 消息能在弱网环境下重试并成功送达。
|
||||
@@ -0,0 +1,285 @@
|
||||
# 📘 WebSocket 通讯协议设计文档
|
||||
|
||||
## 1. 概述
|
||||
|
||||
本协议用于实现 **即时聊天（IM）系统的实时消息传输**。
|
||||
客户端通过 WebSocket 连接后与服务器保持长连接，实现消息推送、状态同步、群聊与单聊。
|
||||
|
||||
**支持功能**：
|
||||
|
||||
- 用户登录鉴权
|
||||
- 单聊消息发送/接收
|
||||
- 群聊消息发送/接收
|
||||
- 消息撤回、已读回执
|
||||
- 心跳保活与断线重连
|
||||
- 系统通知（好友请求、群邀请）
|
||||
|
||||
------
|
||||
|
||||
## 2. 消息传输格式
|
||||
|
||||
### 2.1 基础消息结构（JSON）
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE_TYPE",
|
||||
"requestId": "string", // 客户端生成的请求ID，便于幂等
|
||||
"from": 1001, // 发送者ID
|
||||
"to": 1002, // 接收者ID（单聊）或群ID（群聊）
|
||||
"chatType": "single", // "single" | "group"
|
||||
"contentType": "text", // "text" | "image" | "file" | "voice" | "system"
|
||||
"content": "消息内容或文件URL",
|
||||
"timestamp": 1700000000 // Unix时间戳
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
### 2.2 常用 type 枚举
|
||||
|
||||
| type | 说明 |
|
||||
| -------------- | ------------------------- |
|
||||
| AUTH | 握手鉴权 |
|
||||
| HEARTBEAT | 心跳保活 |
|
||||
| MESSAGE | 普通聊天消息（单聊/群聊） |
|
||||
| MESSAGE_ACK | 消息已读/送达回执 |
|
||||
| MESSAGE_RECALL | 消息撤回 |
|
||||
| FRIEND_REQUEST | 好友申请通知 |
|
||||
| GROUP_INVITE | 群邀请通知 |
|
||||
| SYSTEM_NOTICE | 系统公告/通知 |
|
||||
| ERROR | 错误消息 |
|
||||
|
||||
------
|
||||
|
||||
## 3. 握手与鉴权
|
||||
|
||||
### 3.1 客户端连接
|
||||
|
||||
```
|
||||
ws://example.com/ws?token=xxxx
|
||||
```
|
||||
|
||||
- 客户端通过 Token 鉴权
|
||||
- 服务器验证 Token 后，返回 AUTH_SUCCESS 或 AUTH_FAIL
|
||||
|
||||
### 3.2 服务端响应示例
|
||||
|
||||
**成功：**
|
||||
|
||||
```
|
||||
{
|
||||
"type": "AUTH",
|
||||
"status": "success",
|
||||
"userId": 1001,
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
**失败：**
|
||||
|
||||
```
|
||||
{
|
||||
"type": "AUTH",
|
||||
"status": "fail",
|
||||
"code": 1006,
|
||||
"message": "Token无效或过期"
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
## 4. 心跳机制
|
||||
|
||||
### 4.1 客户端发送
|
||||
|
||||
```
|
||||
{
|
||||
"type": "HEARTBEAT",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 服务器响应
|
||||
|
||||
```
|
||||
{
|
||||
"type": "HEARTBEAT",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
- **客户端**：每隔 30 秒发送一次心跳
|
||||
- **服务器**：若 2 倍心跳时间未收到消息，则断开连接
|
||||
|
||||
------
|
||||
|
||||
## 5. 消息传输
|
||||
|
||||
### 5.1 单聊消息
|
||||
|
||||
客户端发送：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE",
|
||||
"requestId": "uuid-001",
|
||||
"from": 1001,
|
||||
"to": 1002,
|
||||
"chatType": "single",
|
||||
"contentType": "text",
|
||||
"content": "你好",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
服务器推送给接收者：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE",
|
||||
"messageId": 50001,
|
||||
"from": 1001,
|
||||
"to": 1002,
|
||||
"chatType": "single",
|
||||
"contentType": "text",
|
||||
"content": "你好",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
### 5.2 群聊消息
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE",
|
||||
"requestId": "uuid-002",
|
||||
"from": 1001,
|
||||
"to": 3001, // 群ID
|
||||
"chatType": "group",
|
||||
"contentType": "image",
|
||||
"content": "http://img.example.com/xxx.jpg",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
服务器会 **推送到群成员列表（除了自己）**。
|
||||
|
||||
------
|
||||
|
||||
### 5.3 消息回执（MESSAGE_ACK）
|
||||
|
||||
客户端收到消息后发送：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE_ACK",
|
||||
"messageId": 50001,
|
||||
"from": 1002,
|
||||
"to": 1001,
|
||||
"chatType": "single",
|
||||
"status": "read",
|
||||
"timestamp": 1700000000
|
||||
}
|
||||
```
|
||||
|
||||
服务器更新消息状态，并可推送给发送方。
|
||||
|
||||
------
|
||||
|
||||
### 5.4 消息撤回（MESSAGE_RECALL）
|
||||
|
||||
客户端请求撤回消息：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE_RECALL",
|
||||
"messageId": 50001,
|
||||
"from": 1001,
|
||||
"to": 1002,
|
||||
"chatType": "single",
|
||||
"timestamp": 1700000010
|
||||
}
|
||||
```
|
||||
|
||||
服务器验证是否允许撤回（时间限制、权限等），允许则推送给接收方：
|
||||
|
||||
```
|
||||
{
|
||||
"type": "MESSAGE_RECALL",
|
||||
"messageId": 50001,
|
||||
"from": 1001,
|
||||
"chatType": "single",
|
||||
"status": "success",
|
||||
"timestamp": 1700000010
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
## 6. 好友 / 群邀请通知
|
||||
|
||||
### 6.1 好友申请（FRIEND_REQUEST）
|
||||
|
||||
```
|
||||
{
|
||||
"type": "FRIEND_REQUEST",
|
||||
"requestId": "uuid-003",
|
||||
"from": 1001,
|
||||
"to": 1002,
|
||||
"content": "加个好友吧",
|
||||
"timestamp": 1700000020
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 群邀请（GROUP_INVITE）
|
||||
|
||||
```
|
||||
{
|
||||
"type": "GROUP_INVITE",
|
||||
"inviteId": "uuid-004",
|
||||
"groupId": 3001,
|
||||
"inviter": 1001,
|
||||
"invitee": 1003,
|
||||
"content": "邀请你加入群聊",
|
||||
"timestamp": 1700000030
|
||||
}
|
||||
```
|
||||
|
||||
------
|
||||
|
||||
## 7. 错误处理（ERROR）
|
||||
|
||||
```
|
||||
{
|
||||
"type": "ERROR",
|
||||
"code": 2300,
|
||||
"message": "消息发送失败",
|
||||
"requestId": "uuid-001",
|
||||
"timestamp": 1700000040
|
||||
}
|
||||
```
|
||||
|
||||
- **code** 对应响应 Code 规范
|
||||
- **requestId** 可帮助客户端确认失败的具体请求
|
||||
|
||||
------
|
||||
|
||||
## 8. 断线重连
|
||||
|
||||
- 客户端断线后，尝试每隔 5 秒重连一次
|
||||
- 重连成功后，重新发送 AUTH 消息进行鉴权
|
||||
- 重连后可请求 **未读消息同步**（message 表或 Redis 缓存）
|
||||
|
||||
------
|
||||
|
||||
## 9. 附录：contentType 示例
|
||||
|
||||
| contentType | content 示例 | 描述 |
|
||||
| ----------- | ---------------------------------- | ----------------- |
|
||||
| text | "你好" | 文本消息 |
|
||||
| image | "http://img.example.com/xxx.jpg" | 图片 URL |
|
||||
| file | "http://file.example.com/xxx.pdf" | 文件 URL + 文件名 |
|
||||
| voice | "http://audio.example.com/xxx.mp3" | 语音 URL + 时长 |
|
||||
| system | "用户xxx加入群" | 系统消息 |
|
||||
@@ -0,0 +1,145 @@
|
||||
# 📘 接口响应 Code 设计文档
|
||||
|
||||
## 1. 响应数据结构
|
||||
|
||||
统一使用 JSON 格式：
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "请求成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
- **code**：数字型，业务状态码
|
||||
- **message**：字符串，错误或提示信息
|
||||
- **data**：对象/数组，返回的数据内容（可选）
|
||||
|
||||
------
|
||||
|
||||
## 2. Code 设计原则
|
||||
|
||||
1. **统一性**：所有接口返回结构一致。
|
||||
2. **分级设计**：分为系统级错误（1xxx）、业务错误（2xxx+）。
|
||||
3. **可扩展性**：预留范围，避免混乱。
|
||||
|
||||
------
|
||||
|
||||
## 3. Code 约定规范
|
||||
|
||||
### 3.1 成功类
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ------- | ------------ |
|
||||
| 0 | 成功 | 通用成功响应 |
|
||||
|
||||
------
|
||||
|
||||
### 3.2 系统级错误（1000 ~ 1999）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ---------- | ------------------ |
|
||||
| 1000 | 系统错误 | 未知异常 |
|
||||
| 1001 | 服务不可用 | 服务器维护中或宕机 |
|
||||
| 1002 | 请求超时 | 后端超时 |
|
||||
| 1003 | 参数错误 | 缺少或参数不合法 |
|
||||
| 1004 | 数据库错误 | 数据库读写失败 |
|
||||
| 1005 | 权限不足 | 无权限访问 |
|
||||
| 1006 | 认证失败 | Token 无效/过期 |
|
||||
|
||||
------
|
||||
|
||||
### 3.3 用户相关错误（2000 ~ 2099）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ---------- | ---------------- |
|
||||
| 2000 | 用户不存在 | 查询不到用户 |
|
||||
| 2001 | 用户已存在 | 注册时用户已存在 |
|
||||
| 2002 | 密码错误 | 登录密码错误 |
|
||||
| 2003 | 用户被禁用 | 被管理员封禁 |
|
||||
| 2004 | 登录过期 | 需重新登录 |
|
||||
|
||||
------
|
||||
|
||||
### 3.4 好友相关错误（2100 ~ 2199）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | -------------- | ---------- |
|
||||
| 2100 | 好友申请已存在 | 重复申请 |
|
||||
| 2101 | 好友关系不存在 | 不是好友 |
|
||||
| 2102 | 已经是好友 | 重复添加 |
|
||||
| 2103 | 好友请求被拒绝 | 被对方拒绝 |
|
||||
| 2104 | 无法申请加好友 | 被对方拉黑 |
|
||||
|
||||
------
|
||||
|
||||
### 3.5 群聊相关错误（2200 ~ 2299）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ------------ | ------------- |
|
||||
| 2200 | 群不存在 | 查询不到群 |
|
||||
| 2201 | 已在群中 | 不能重复加入 |
|
||||
| 2202 | 群成员已满 | 超出限制 |
|
||||
| 2203 | 无加群权限 | 需要邀请/验证 |
|
||||
| 2204 | 群邀请已过期 | 邀请链接过期 |
|
||||
|
||||
------
|
||||
|
||||
### 3.6 消息相关错误（2300 ~ 2399）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ---------------- | ------------------- |
|
||||
| 2300 | 消息发送失败 | 发送时异常 |
|
||||
| 2301 | 消息不存在 | 查询不到 |
|
||||
| 2302 | 消息撤回失败 | 超过时间限制 |
|
||||
| 2303 | 不支持的消息类型 | message_type 不合法 |
|
||||
|
||||
------
|
||||
|
||||
### 3.7 文件相关错误（2400 ~ 2499）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | -------------- | ------------ |
|
||||
| 2400 | 文件上传失败 | 存储服务错误 |
|
||||
| 2401 | 文件不存在 | 下载时未找到 |
|
||||
| 2402 | 文件大小超限 | 超过配置限制 |
|
||||
| 2403 | 文件类型不支持 | 格式不允许 |
|
||||
|
||||
------
|
||||
|
||||
### 3.8 管理后台相关错误（3000 ~ 3099）
|
||||
|
||||
| code | message | 说明 |
|
||||
| ---- | ------------ | ---------------- |
|
||||
| 3000 | 管理员不存在 | 账号错误 |
|
||||
| 3001 | 密码错误 | 后台登录失败 |
|
||||
| 3002 | 角色不存在 | 角色未找到 |
|
||||
| 3003 | 权限不足 | 无操作权限 |
|
||||
| 3004 | 操作记录失败 | 后台日志写入失败 |
|
||||
|
||||
------
|
||||
|
||||
## 4. 响应示例
|
||||
|
||||
### 成功示例
|
||||
|
||||
```
|
||||
{
|
||||
"code": 0,
|
||||
"message": "好友申请成功",
|
||||
"data": {
|
||||
"requestId": 12345
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 失败示例
|
||||
|
||||
```
|
||||
{
|
||||
"code": 2100,
|
||||
"message": "好友申请已存在",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user