code/IM
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

提交

Browse Source
This commit is contained in:
nanxun
2026-02-12 21:53:26 +08:00
parent 77db20dc38
commit b96d895809
339 changed files with 46655 additions and 46657 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ER图.drawio
+1094 -1094
View File
File diff suppressed because it is too large Load Diff
docs/IM 系统消息存储与推送策略文档.md
+140 -140
View File
@@ -1,141 +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` 表
# 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` 表
- 支持离线同步
docs/IM 系统鉴权与 Token 安全规范文档.md
+115 -115
View File
@@ -1,115 +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. **设备列表管理**：可查看在线设备并强制下线
# 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. **设备列表管理**：可查看在线设备并强制下线
docs/vue3组件文档.md
+149 -149
View File
@@ -1,150 +1,150 @@
# 📚 MyButton
## 🏷️ 1. 组件概览
### 基础信息
| **属性** | **值** |
| ------------ | ---------------------------------------------------------- |
| **组件名称** | `MyButton` |
| **文件路径** | `@/components/MyButton.vue` |
| **用途** | 封装项目中的所有交互按钮，提供统一的样式、交互状态和动画。 |
| **版本** | v1.0.0 |
| **核心依赖** | `feather-icons` (需要父组件或全局初始化) |
### 引入方式
JavaScript
```
import MyButton from '@/components/MyButton.vue';
```
## 💡 2. 使用示例
### 基础用法（Primary Variant）
HTML
```
<MyButton>保存配置</MyButton>
<MyButton variant="primary">
<i data-feather="send"></i>
发送邮件
</MyButton>
```
### 状态和事件绑定
HTML
```
<MyButton variant="secondary" :disabled="isSaving">
取消
</MyButton>
<MyButton variant="danger" :loading="isDeleting" @click="handleDelete">
删除数据
</MyButton>
```
## ⚙️ 3. Props 属性说明 (API)
| **名称 (Prop Name)** | **类型 (Type)** | **可选值/说明** | **默认值 (Default)** | **描述** |
| -------------------- | --------------- | ------------------------------------------------------------ | -------------------- | -------------------------------------------------------- |
| `variant` | `String` | `primary` (主色调), `secondary` (次要/灰色), `danger` (危险/红色), `text` (纯文本链接样式) | `'primary'` | 定义按钮的外观和主题颜色。 |
| `disabled` | `Boolean` | — | `false` | 明确禁用按钮，移除点击交互和视觉提示。 |
| `loading` | `Boolean` | — | `false` | 设置为 `true` 时，按钮显示加载状态，并自动应用禁用样式。 |
## 🧩 4. 插槽说明 (Slots)
| **名称 (Slot Name)** | **用途** | **插槽 Prop** | **示例用法** |
| -------------------- | ------------------------------------------ | ------------- | --------------------------------- |
| **默认** (`default`) | 用于插入按钮的**文本内容**或其他核心元素。 | 无 | `<MyButton> 按钮文本 </MyButton>` |
## ⚡ 5. 事件说明 (Events)
| **名称 (Event Name)** | **参数 (Payload)** | **描述** |
| --------------------- | --------------------- | ------------------------------------------------------------ |
| `@click` | `(event: MouseEvent)` | 按钮被点击时触发。由于使用了 `v-bind="attrs"`，此事件是透传自内部 `<button>`。 |
# 📚 IconInput
## 🏷️ 1. 组件概览
### 基础信息
| **属性** | **值** |
| ------------ | ------------------------------------------------------------ |
| **组件名称** | `IconInput` |
| **文件路径** | `@/components/IconInput.vue` |
| **用途** | 封装带图标的输入框，支持 `v-model` 双向绑定，并提供聚焦时图标颜色变化等高级交互。 |
| **版本** | v1.0.0 |
| **核心依赖** | `feather-icons` (需要在项目中安装) |
| **特性** | 支持 `v-model`，自动集成 Feather Icons。 |
### 引入方式
JavaScript
```
import IconInput from '@/components/IconInput.vue';
```
## 💡 2. 使用示例
### 基础用法（双向绑定）
HTML
```
<template>
<div>
<IconInput
v-model="username"
lab="用户名"
icon-name="user"
placeholder="请输入用户名"
type="text"
/>
<IconInput
v-model="password"
lab="密码"
icon-name="lock"
placeholder="请输入密码"
type="password"
/>
<p>当前用户名: {{ username }}</p>
</div>
</template>
<script setup>
import { ref } from 'vue';
import CustomInput from './CustomInput.vue';
const username = ref('');
const password = ref('');
</script>
```
## ⚙️ 3. Props 属性说明 (API)
| **名称 (Prop Name)** | **类型 (Type)** | **可选值/说明** | **默认值 (Default)** | **描述** |
| -------------------- | --------------- | ------------------------------------------------------------ | -------------------- | -------------------------------------------- |
| `v-model` 绑定 | 见 `modelValue` | — | — | **使用标准 `v-model` 语法实现双向绑定。** |
| `modelValue` | `String` | — | `''` | (内部 Prop) `v-model` 绑定传入的值。 |
| `lab` | `String` | — | `'输入框'` | 输入框上方的标签（Label）文本。 |
| `placeholder` | `String` | — | `''` | 输入框的占位符文本。 |
| `type` | `String` | `text`, `password`, `email` 等原生类型 | `'text'` | 设置输入框的 `type` 属性。 |
| `iconName` | `String` | 任何有效的 [Feather Icon] 名称（例如 `'mail'`, `'user'`, `'lock'`）。 | **无** | **必填项**，用于指定显示在输入框左侧的图标。 |
## ⚡ 4. 事件说明 (Events)
| **名称 (Event Name)** | **参数 (Payload)** | **描述** |
| --------------------- | -------------------- | ------------------------------------------------------------ |
| `@update:modelValue` | `(newValue: string)` | **(核心事件)** 当输入框的值变化时，触发此事件来更新父组件通过 `v-model` 绑定的数据。 |
# 📚 MyButton
## 🏷️ 1. 组件概览
### 基础信息
| **属性** | **值** |
| ------------ | ---------------------------------------------------------- |
| **组件名称** | `MyButton` |
| **文件路径** | `@/components/MyButton.vue` |
| **用途** | 封装项目中的所有交互按钮，提供统一的样式、交互状态和动画。 |
| **版本** | v1.0.0 |
| **核心依赖** | `feather-icons` (需要父组件或全局初始化) |
### 引入方式
JavaScript
```
import MyButton from '@/components/MyButton.vue';
```
## 💡 2. 使用示例
### 基础用法（Primary Variant）
HTML
```
<MyButton>保存配置</MyButton>
<MyButton variant="primary">
<i data-feather="send"></i>
发送邮件
</MyButton>
```
### 状态和事件绑定
HTML
```
<MyButton variant="secondary" :disabled="isSaving">
取消
</MyButton>
<MyButton variant="danger" :loading="isDeleting" @click="handleDelete">
删除数据
</MyButton>
```
## ⚙️ 3. Props 属性说明 (API)
| **名称 (Prop Name)** | **类型 (Type)** | **可选值/说明** | **默认值 (Default)** | **描述** |
| -------------------- | --------------- | ------------------------------------------------------------ | -------------------- | -------------------------------------------------------- |
| `variant` | `String` | `primary` (主色调), `secondary` (次要/灰色), `danger` (危险/红色), `text` (纯文本链接样式) | `'primary'` | 定义按钮的外观和主题颜色。 |
| `disabled` | `Boolean` | — | `false` | 明确禁用按钮，移除点击交互和视觉提示。 |
| `loading` | `Boolean` | — | `false` | 设置为 `true` 时，按钮显示加载状态，并自动应用禁用样式。 |
## 🧩 4. 插槽说明 (Slots)
| **名称 (Slot Name)** | **用途** | **插槽 Prop** | **示例用法** |
| -------------------- | ------------------------------------------ | ------------- | --------------------------------- |
| **默认** (`default`) | 用于插入按钮的**文本内容**或其他核心元素。 | 无 | `<MyButton> 按钮文本 </MyButton>` |
## ⚡ 5. 事件说明 (Events)
| **名称 (Event Name)** | **参数 (Payload)** | **描述** |
| --------------------- | --------------------- | ------------------------------------------------------------ |
| `@click` | `(event: MouseEvent)` | 按钮被点击时触发。由于使用了 `v-bind="attrs"`，此事件是透传自内部 `<button>`。 |
# 📚 IconInput
## 🏷️ 1. 组件概览
### 基础信息
| **属性** | **值** |
| ------------ | ------------------------------------------------------------ |
| **组件名称** | `IconInput` |
| **文件路径** | `@/components/IconInput.vue` |
| **用途** | 封装带图标的输入框，支持 `v-model` 双向绑定，并提供聚焦时图标颜色变化等高级交互。 |
| **版本** | v1.0.0 |
| **核心依赖** | `feather-icons` (需要在项目中安装) |
| **特性** | 支持 `v-model`，自动集成 Feather Icons。 |
### 引入方式
JavaScript
```
import IconInput from '@/components/IconInput.vue';
```
## 💡 2. 使用示例
### 基础用法（双向绑定）
HTML
```
<template>
<div>
<IconInput
v-model="username"
lab="用户名"
icon-name="user"
placeholder="请输入用户名"
type="text"
/>
<IconInput
v-model="password"
lab="密码"
icon-name="lock"
placeholder="请输入密码"
type="password"
/>
<p>当前用户名: {{ username }}</p>
</div>
</template>
<script setup>
import { ref } from 'vue';
import CustomInput from './CustomInput.vue';
const username = ref('');
const password = ref('');
</script>
```
## ⚙️ 3. Props 属性说明 (API)
| **名称 (Prop Name)** | **类型 (Type)** | **可选值/说明** | **默认值 (Default)** | **描述** |
| -------------------- | --------------- | ------------------------------------------------------------ | -------------------- | -------------------------------------------- |
| `v-model` 绑定 | 见 `modelValue` | — | — | **使用标准 `v-model` 语法实现双向绑定。** |
| `modelValue` | `String` | — | `''` | (内部 Prop) `v-model` 绑定传入的值。 |
| `lab` | `String` | — | `'输入框'` | 输入框上方的标签（Label）文本。 |
| `placeholder` | `String` | — | `''` | 输入框的占位符文本。 |
| `type` | `String` | `text`, `password`, `email` 等原生类型 | `'text'` | 设置输入框的 `type` 属性。 |
| `iconName` | `String` | 任何有效的 [Feather Icon] 名称（例如 `'mail'`, `'user'`, `'lock'`）。 | **无** | **必填项**，用于指定显示在输入框左侧的图标。 |
## ⚡ 4. 事件说明 (Events)
| **名称 (Event Name)** | **参数 (Payload)** | **描述** |
| --------------------- | -------------------- | ------------------------------------------------------------ |
| `@update:modelValue` | `(newValue: string)` | **(核心事件)** 当输入框的值变化时，触发此事件来更新父组件通过 `v-model` 绑定的数据。 |
##
docs/后端代码规范文档.md
+82 -82
View File
@@ -1,82 +1,82 @@
# 项目规范文档
## 1. 命名规范
* **全局命名**
* 采用 **小驼峰命名法**（camelCase），例如：`aBbCc`。
* 特殊情况除外，例如 **.NET 编译器要求方法名使用大驼峰**（PascalCase）。
* **各层命名规范**
* **Controllers**：自定义命名 + `Controller`
* **Services**：自定义命名 + `Service`
* **Dtos**：自定义命名 + `Dto`
---
## 2. 文件/文件夹规范
| 文件夹 | 功能描述 | 注意事项 |
| -------------------- | -------------------------- | -------------------------------------------- |
| **Controllers** | 存放控制器和 Actions，用于处理请求和响应 | 禁止直接操作数据库。如需数据库操作，应先在 Services 层编写业务逻辑再调用 |
| **Services** | 存放业务逻辑代码，包括数据库交互 | 应在 Service 层处理所有业务逻辑，保证 Controller 层纯粹用于请求处理 |
| **Dtos** | 存放不同层之间的数据传输模型（DTO） | 用于数据类型转换，例如返回用户信息时需剔除密码等敏感信息。禁止直接返回数据库模型类 |
| **Models** | 存放数据库模型类（Entity） | 一般情况下请勿随意修改 |
| **appsettings.json** | 存放配置文件，如数据库连接字符串、Redis 配置等 | 禁止在业务代码中硬编码配置信息，统一放在此文件中 |
---
## 3. Service 编写与使用规范
### 3.1 编写 Service
1. 在 `Interface/Services` 文件夹下创建接口，定义业务方法框架。
2. 提交接口代码至 Gitea，合并并通过审核。
3. 在 `Services` 文件夹下新建类，实现上述接口。
### 3.2 注册 Service
1. 在 `Configs/ServiceCollectionExtensions.cs` 文件的 `AddAllService` 方法中添加：
```csharp
services.AddTransient<接口类型, 实现类>();
```
2. 根据业务逻辑选择生命周期：
* **AddTransient**：瞬时
* **AddScoped**：请求范围
* **AddSingleton**：单例
### 3.3 在 Controller 中使用 Service
1. 在 Controller 内定义属性：
```csharp
private readonly IDemo _demo;
```
2. 在构造函数中通过依赖注入接收接口实例：
```csharp
public WeatherForecastController(IDemo demo)
{
_demo = demo;
}
```
3. 在 Controller 方法中使用 `_demo` 调用业务逻辑方法。
## 4. 模型类字段使用规范
### 4.1 类中状态相关字段，例如：Status，返回值为sbyte。若类中有同名字段+后缀Enum，则优先使用后者,StatusEnum。
## 5.数据库相关
### 5.1 若数据库表结构更新，请在软件包控制台执行如下命令：
```cmd
Scaffold-DbContext "Name=ConnectionStrings:DefaultConnection" Pomelo.EntityFrameworkCore.MySql -OutputDir Models -Context ImContext -Force -NoOnConfiguring
```
# 项目规范文档
## 1. 命名规范
* **全局命名**
* 采用 **小驼峰命名法**（camelCase），例如：`aBbCc`。
* 特殊情况除外，例如 **.NET 编译器要求方法名使用大驼峰**（PascalCase）。
* **各层命名规范**
* **Controllers**：自定义命名 + `Controller`
* **Services**：自定义命名 + `Service`
* **Dtos**：自定义命名 + `Dto`
---
## 2. 文件/文件夹规范
| 文件夹 | 功能描述 | 注意事项 |
| -------------------- | -------------------------- | -------------------------------------------- |
| **Controllers** | 存放控制器和 Actions，用于处理请求和响应 | 禁止直接操作数据库。如需数据库操作，应先在 Services 层编写业务逻辑再调用 |
| **Services** | 存放业务逻辑代码，包括数据库交互 | 应在 Service 层处理所有业务逻辑，保证 Controller 层纯粹用于请求处理 |
| **Dtos** | 存放不同层之间的数据传输模型（DTO） | 用于数据类型转换，例如返回用户信息时需剔除密码等敏感信息。禁止直接返回数据库模型类 |
| **Models** | 存放数据库模型类（Entity） | 一般情况下请勿随意修改 |
| **appsettings.json** | 存放配置文件，如数据库连接字符串、Redis 配置等 | 禁止在业务代码中硬编码配置信息，统一放在此文件中 |
---
## 3. Service 编写与使用规范
### 3.1 编写 Service
1. 在 `Interface/Services` 文件夹下创建接口，定义业务方法框架。
2. 提交接口代码至 Gitea，合并并通过审核。
3. 在 `Services` 文件夹下新建类，实现上述接口。
### 3.2 注册 Service
1. 在 `Configs/ServiceCollectionExtensions.cs` 文件的 `AddAllService` 方法中添加：
```csharp
services.AddTransient<接口类型, 实现类>();
```
2. 根据业务逻辑选择生命周期：
* **AddTransient**：瞬时
* **AddScoped**：请求范围
* **AddSingleton**：单例
### 3.3 在 Controller 中使用 Service
1. 在 Controller 内定义属性：
```csharp
private readonly IDemo _demo;
```
2. 在构造函数中通过依赖注入接收接口实例：
```csharp
public WeatherForecastController(IDemo demo)
{
_demo = demo;
}
```
3. 在 Controller 方法中使用 `_demo` 调用业务逻辑方法。
## 4. 模型类字段使用规范
### 4.1 类中状态相关字段，例如：Status，返回值为sbyte。若类中有同名字段+后缀Enum，则优先使用后者,StatusEnum。
## 5.数据库相关
### 5.1 若数据库表结构更新，请在软件包控制台执行如下命令：
```cmd
Scaffold-DbContext "Name=ConnectionStrings:DefaultConnection" Pomelo.EntityFrameworkCore.MySql -OutputDir Models -Context ImContext -Force -NoOnConfiguring
```
docs/接口文档（REST API） — 聊天系统.md
+400 -400
View File
@@ -1,401 +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 查询操作日志
# 接口文档（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`
docs/数据字典.md
+222 -222
View File
@@ -1,223 +1,223 @@
# 数据字典
### 表名：Users
#### 表说明：储存用户个人信息
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
| ----------- | ------------ | -------- | -------- | ------- | --------- | ------------------------------------------------ | ----------------------- |
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
| Username | VARCHAR(50) | 是 | / | / | 唯一 | 唯一用户名 | admin |
| Avatar | VARCHAR(255) | 否 | / | / | / | 用户头像 | https://baidu.com/1.png |
| 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 |
| RemarkName | VARCHAR(20) | 是 | / | / | / | 好友备注 | 小王 |
| Avatar | VARCHAR(255) | 否 | / | / | / | 好友头像 | https://baidu.com/1.png |
| 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） | 索引 | 角色 | / |
# 数据字典
### 表名：Users
#### 表说明：储存用户个人信息
| 字段名 | 数据类型 | 是否必填 | 默认值 | 主/外键 | 约束/索引 | 字段说明 | 示例值 |
| ----------- | ------------ | -------- | -------- | ------- | --------- | ------------------------------------------------ | ----------------------- |
| Id | INT | 是 | / | 主键 | 索引 | 主键自增 | 1 |
| Username | VARCHAR(50) | 是 | / | / | 唯一 | 唯一用户名 | admin |
| Avatar | VARCHAR(255) | 否 | / | / | / | 用户头像 | https://baidu.com/1.png |
| 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 |
| RemarkName | VARCHAR(20) | 是 | / | / | / | 好友备注 | 小王 |
| Avatar | VARCHAR(255) | 否 | / | / | / | 好友头像 | https://baidu.com/1.png |
| 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） | 索引 | 权限 | / |
docs/测试环境文档.md
+54 -54
View File
@@ -1,55 +1,55 @@
# 🧪 测试环境自动化构建使用手册
本手册用于指导测试人员如何通过 Jenkins 快速部署指定分支的代码，并访问对应的测试地址。
---
### 1. 环境准备
| 平台名称 | 地址 |
| ---------------------- | ------------------------------------------------------------ |
| Jenkins IM前端构建任务 | [Jenkins](http://192.168.5.100:8100/job/IM前端/build?delay=0sec) |
| Jenkins IM后端构建任务 | [IM后端 - Jenkins](http://192.168.5.100:8100/job/IM后端/) |
| 前端分支列表 | https://im.test.nxsir.cn |
在开始构建前，请确认：
* 已拥有 **Jenkins 登录权限**。
* **前置环境wireguard**已启动。
* 已获取需要测试的 **Git 分支名称**（例如：`feature/order-page`）。
---
### 2. 构建操作步骤流程
1. **登录 Jenkins**：访问 [此处输入你的Jenkins地址] 并登录。
2. **进入任务**：在项目列表中点击进入对应的测试项目。
3. **参数化构建**：
* 点击左侧菜单栏的 **Build with Parameters**（带参数构建）。
* 在 **`BRANCH_NAME`** 输入框中，填入或选择你的 Git 分支名。
4. **开始构建**：点击下方的 **Build** 按钮。
> ⚠️ **提示**：建议直接从代码仓库复制分支名，避免手动输入导致拼写错误。
---
### 3. 查看构建状态与结果
* **观察状态**：在左下角 **Build History** 看到圆形图标变为 **蓝色/绿色**，表示构建成功。
* **访问网页**：
* 构建成功后，点击该次构建编号（如 `#10`）。
* 在详情页中点击 **[访问测试环境]** 链接（通常位于页面显著位置）。
* 或者直接访问：`https://im.test.nxsir.cn/[分支名]`
---
### 4. 常见问题排查
| 现象 | 可能原因 | 解决方法 |
| :-------------------------- | :--------------------- | :----------------------------------------------------------- |
| **构建显示红色（Failure）** | 分支名不存在或代码冲突 | 检查分支名是否已推送到远端仓库。 |
| **点击链接显示 404** | 部署尚未完全完成 | 构建完成后通常有几秒延迟，请稍后刷新。 |
| **页面依然显示旧内容** | 浏览器缓存 | 请使用 `Ctrl + F5` (Windows) 或 `Cmd + Shift + R` (Mac) 强制刷新。 |
---
# 🧪 测试环境自动化构建使用手册
本手册用于指导测试人员如何通过 Jenkins 快速部署指定分支的代码，并访问对应的测试地址。
---
### 1. 环境准备
| 平台名称 | 地址 |
| ---------------------- | ------------------------------------------------------------ |
| Jenkins IM前端构建任务 | [Jenkins](http://192.168.5.100:8100/job/IM前端/build?delay=0sec) |
| Jenkins IM后端构建任务 | [IM后端 - Jenkins](http://192.168.5.100:8100/job/IM后端/) |
| 前端分支列表 | https://im.test.nxsir.cn |
在开始构建前，请确认：
* 已拥有 **Jenkins 登录权限**。
* **前置环境wireguard**已启动。
* 已获取需要测试的 **Git 分支名称**（例如：`feature/order-page`）。
---
### 2. 构建操作步骤流程
1. **登录 Jenkins**：访问 [此处输入你的Jenkins地址] 并登录。
2. **进入任务**：在项目列表中点击进入对应的测试项目。
3. **参数化构建**：
* 点击左侧菜单栏的 **Build with Parameters**（带参数构建）。
* 在 **`BRANCH_NAME`** 输入框中，填入或选择你的 Git 分支名。
4. **开始构建**：点击下方的 **Build** 按钮。
> ⚠️ **提示**：建议直接从代码仓库复制分支名，避免手动输入导致拼写错误。
---
### 3. 查看构建状态与结果
* **观察状态**：在左下角 **Build History** 看到圆形图标变为 **蓝色/绿色**，表示构建成功。
* **访问网页**：
* 构建成功后，点击该次构建编号（如 `#10`）。
* 在详情页中点击 **[访问测试环境]** 链接（通常位于页面显著位置）。
* 或者直接访问：`https://im.test.nxsir.cn/[分支名]`
---
### 4. 常见问题排查
| 现象 | 可能原因 | 解决方法 |
| :-------------------------- | :--------------------- | :----------------------------------------------------------- |
| **构建显示红色（Failure）** | 分支名不存在或代码冲突 | 检查分支名是否已推送到远端仓库。 |
| **点击链接显示 404** | 部署尚未完全完成 | 构建完成后通常有几秒延迟，请稍后刷新。 |
| **页面依然显示旧内容** | 浏览器缓存 | 请使用 `Ctrl + F5` (Windows) 或 `Cmd + Shift + R` (Mac) 强制刷新。 |
---
**💡 运维备注**：如遇 Jenkins 无法登录或构建按钮置灰，请联系管理员。
docs/系统架构设计.md
+36 -36
View File
@@ -1,37 +1,37 @@
# 系统架构设计
## 1.1 系统概述
- 项目名称：聊天系统
- 项目类型：即时通讯（Web 端）
- 技术栈：
- 前端：Vue + WebSocket
- 后端：.NET/C#
- 数据库：MySQL + Redis
- 消息队列：Kafka
- 部署：Docker + Nginx + 云服务器
## 1.2 系统架构图
- [前端] ↔ [WebSocket Server] ↔ [业务服务器] ↔ [数据库/缓存]
## 1.3 模块划分
### 前端模块
- 登录/注册
- 好友列表
- 单聊聊天窗口
- 个人资料窗口
- 语音/视频通话
- 群聊聊天窗口
- 文件/表情/图片发送
### 后端模块
- 用户管理（注册、登录、资料）
- 好友管理（加好友、删除、黑名单）
- 消息管理（单聊、群聊、已读/未读、撤回）
- 群聊管理（创建群、成员管理、公告）
- 通知管理（好友请求、群邀请、系统消息）
- 通话管理
### 中间件/第三方
- WebSocket 实时通信
- Redis 消息缓存
# 系统架构设计
## 1.1 系统概述
- 项目名称：聊天系统
- 项目类型：即时通讯（Web 端）
- 技术栈：
- 前端：Vue + WebSocket
- 后端：.NET/C#
- 数据库：MySQL + Redis
- 消息队列：Kafka
- 部署：Docker + Nginx + 云服务器
## 1.2 系统架构图
- [前端] ↔ [WebSocket Server] ↔ [业务服务器] ↔ [数据库/缓存]
## 1.3 模块划分
### 前端模块
- 登录/注册
- 好友列表
- 单聊聊天窗口
- 个人资料窗口
- 语音/视频通话
- 群聊聊天窗口
- 文件/表情/图片发送
### 后端模块
- 用户管理（注册、登录、资料）
- 好友管理（加好友、删除、黑名单）
- 消息管理（单聊、群聊、已读/未读、撤回）
- 群聊管理（创建群、成员管理、公告）
- 通知管理（好友请求、群邀请、系统消息）
- 通话管理
### 中间件/第三方
- WebSocket 实时通信
- Redis 消息缓存
- 文件存储（图片/语音/文件）
docs/需求规格说明书（SRS）.md
+63 -63
View File
@@ -1,64 +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 人场景下稳定传递。
# 需求规格说明书（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 人场景下稳定传递。
- 消息能在弱网环境下重试并成功送达。
docs/📘 WebSocket 通讯协议设计文档.md
+284 -284
View File
@@ -1,285 +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 + 时长 |
# 📘 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加入群" | 系统消息 |
docs/📘 接口响应 Code 设计文档.md
+144 -144
View File
@@ -1,145 +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
}
# 📘 接口响应 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
}
```