294 lines
7.8 KiB
Markdown
294 lines
7.8 KiB
Markdown
# 站内信功能开发总结
|
||
|
||
## 开发完成时间
|
||
2025-12-07
|
||
|
||
## 功能概述
|
||
新增独立的站内信消息系统，支持指定用户消息和全员广播，集成到预约系统的组局成功/失败自动通知。
|
||
|
||
---
|
||
|
||
## 一、数据库表
|
||
|
||
### 1. SQMessage（站内信消息表）
|
||
**位置**：`数据库\SqlServer\创建站内信表.sql`
|
||
|
||
**字段说明**：
|
||
- `id`：消息ID（主键，自增）
|
||
- `user_id`：接收用户ID（全员广播时为NULL）
|
||
- `target_type`：目标类型（0=指定用户，1=全员广播）
|
||
- `title`：消息标题
|
||
- `content`：消息正文
|
||
- `message_type`：消息类型（0=系统通知，1=私信）
|
||
- `is_read`：是否已读（仅对指定用户消息有效）
|
||
- `sender_id`：发送者ID（后台管理员ID）
|
||
- `related_type`：关联业务类型（1=组局）
|
||
- `related_id`：关联业务ID
|
||
- `created_at`：创建时间
|
||
- `updated_at`：更新时间
|
||
|
||
### 2. SQMessageRead（已读记录表）
|
||
**用途**：专门记录全员广播消息的已读状态
|
||
|
||
**字段说明**：
|
||
- `id`：记录ID（主键，自增）
|
||
- `message_id`：消息ID
|
||
- `user_id`：用户ID
|
||
- `read_at`：阅读时间
|
||
|
||
**索引**：
|
||
- 唯一索引：`IX_SQMessageRead_msg_user (message_id, user_id)` 防止重复
|
||
- 普通索引：`IX_SQMessageRead_user_id` 查询优化
|
||
|
||
---
|
||
|
||
## 二、代码文件清单
|
||
|
||
### Model层（实体）
|
||
- `CoreCms.Net.Model\Entities\SQ\SQMessage.cs`
|
||
- `CoreCms.Net.Model\Entities\SQ\SQMessageRead.cs`
|
||
|
||
### Repository层（数据访问）
|
||
- `CoreCms.Net.IRepository\SQ\ISQMessageRepository.cs`
|
||
- `CoreCms.Net.IRepository\SQ\ISQMessageReadRepository.cs`
|
||
- `CoreCms.Net.Repository\SQ\SQMessageRepository.cs`
|
||
- `CoreCms.Net.Repository\SQ\SQMessageReadRepository.cs`
|
||
|
||
### Services层（业务逻辑）
|
||
- `CoreCms.Net.IServices\SQ\ISQMessageServices.cs`
|
||
- `CoreCms.Net.Services\SQ\SQMessageServices.cs`
|
||
|
||
### Controller层
|
||
- **前端API**：`CoreCms.Net.Web.WebApi\Controllers\SQController.cs`（新增3个接口）
|
||
- **后台管理**：`CoreCms.Net.Web.Admin\Controllers\SQ\SQMessageController.cs`
|
||
|
||
### 后台页面
|
||
- `CoreCms.Net.Web.Admin\wwwroot\views\sq\sqmessage\index.html`（消息列表页）
|
||
- `CoreCms.Net.Web.Admin\wwwroot\views\sq\sqmessage\details.html`（消息详情页）
|
||
- `CoreCms.Net.Web.Admin\wwwroot\views\sq\sqmessage\broadcast.html`（发送全员广播页）
|
||
|
||
### 业务集成
|
||
- `CoreCms.Net.Services\SQ\SQReservationsServices.cs`（修改，添加站内信通知）
|
||
|
||
---
|
||
|
||
## 三、前端API接口
|
||
|
||
### 1. 获取消息列表
|
||
**接口**：`GET /api/SQ/GetMessageList`
|
||
**参数**：
|
||
- `pageIndex`：页码（默认1）
|
||
- `pageSize`：每页数量（默认20）
|
||
- `messageType`：消息类型（0=全部，1=私信）
|
||
|
||
**返回**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"title": "组局成功通知",
|
||
"content": "恭喜您！组局"周末欢乐局"已成功！",
|
||
"createTime": "2025-12-07 10:30",
|
||
"messageType": 0,
|
||
"isRead": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 获取未读消息数量
|
||
**接口**：`GET /api/SQ/GetUnreadCount`
|
||
**返回**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "获取成功",
|
||
"data": {
|
||
"count": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 标记所有消息为已读
|
||
**接口**：`POST /api/SQ/MarkAllAsRead`
|
||
**返回**：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "标记成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、后台管理功能
|
||
|
||
### 1. 消息列表管理（已开发页面）
|
||
**访问路径**：后台菜单 → SQ管理 → 站内信管理
|
||
|
||
**功能特性**：
|
||
- 查看所有消息记录
|
||
- 筛选条件：消息ID、标题、目标类型（指定用户/全员广播）、消息类型（系统通知/私信）
|
||
- 支持查看详情、删除、批量删除
|
||
- 数据分页显示（可选10-200条/页）
|
||
|
||
### 2. 发送全员广播（已开发页面）
|
||
**操作方式**：
|
||
1. 在消息列表页点击"发送全员广播"按钮
|
||
2. 填写消息标题和内容
|
||
3. 点击"立即发送"，消息将发送给所有用户
|
||
|
||
**接口**：`POST /api/SQMessage/SendBroadcast`
|
||
|
||
**请求示例**：
|
||
```json
|
||
{
|
||
"title": "系统维护通知",
|
||
"content": "系统将于今晚22:00-23:00进行维护，请提前做好准备。",
|
||
"senderId": 1
|
||
}
|
||
```
|
||
|
||
### 3. 其他管理接口
|
||
**后台可调用的接口**：
|
||
- `POST /api/SQMessage/SendToUser`：发送给指定用户（可通过API调用）
|
||
- `POST /api/SQMessage/SendToUsers`：发送给多个用户（可通过API调用）
|
||
- `POST /api/SQMessage/GetUserList`：查询用户列表（用于扩展发送对象选择）
|
||
|
||
---
|
||
|
||
## 五、自动通知场景
|
||
|
||
### 1. 组局成功通知
|
||
**触发时机**：预约系统调用 `NotifyReservationSuccessAsync`
|
||
**通知内容**：
|
||
```
|
||
标题：组局成功通知
|
||
内容：恭喜您！组局"{组局名称}"已成功！
|
||
|
||
房间：{房间名称}
|
||
时间：{开始时间}
|
||
请准时到达，祝您游戏愉快！
|
||
```
|
||
|
||
### 2. 组局失败通知
|
||
**触发时机**：预约系统调用 `NotifyReservationFailedAsync`
|
||
**通知内容**：
|
||
```
|
||
标题：组局失败通知
|
||
内容：您参与的组局"{组局名称}"因人数未满已自动解散。
|
||
|
||
房间：{房间名称}
|
||
时间：{开始时间}
|
||
原因：{失败原因}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、查询逻辑说明
|
||
|
||
### 用户消息列表查询
|
||
合并查询：
|
||
- 指定给当前用户的消息（`target_type=0` 且 `user_id=当前用户`）
|
||
- 全员广播消息（`target_type=1`）
|
||
|
||
### 已读状态判断
|
||
- **私信**：直接读取 `SQMessage.is_read` 字段
|
||
- **全员广播**：查询 `SQMessageRead` 表是否存在记录
|
||
|
||
### 标记全部已读
|
||
1. 更新私信：`UPDATE SQMessage SET is_read=1`
|
||
2. 插入广播已读记录：`INSERT INTO SQMessageRead`
|
||
|
||
---
|
||
|
||
## 七、扩展功能建议
|
||
|
||
### 短期扩展
|
||
1. 消息详情页（点击消息查看完整内容）
|
||
2. 删除消息功能
|
||
3. 消息搜索功能
|
||
4. 批量操作（批量标记已读/删除）
|
||
|
||
### 长期扩展
|
||
1. 消息分类标签
|
||
2. 消息推送到手机端
|
||
3. 消息提醒声音/震动设置
|
||
4. 定时发送消息
|
||
5. 消息模板管理
|
||
|
||
---
|
||
|
||
## 八、使用说明
|
||
|
||
### 前端对接
|
||
1. 在"我的"页面添加"我的消息"入口
|
||
2. 调用 `GetUnreadCount` 接口显示红点
|
||
3. 进入列表页调用 `GetMessageList` 获取消息
|
||
4. 自动调用 `MarkAllAsRead` 标记已读
|
||
|
||
### 后台使用
|
||
1. 访问后台消息管理模块
|
||
2. 可以手动发送通知给指定用户或全体用户
|
||
3. 查看历史消息记录
|
||
|
||
---
|
||
|
||
## 九、注意事项
|
||
|
||
1. **数据库**：请先执行 `数据库\SqlServer\创建站内信表.sql` 创建表
|
||
2. **依赖注入**：系统已自动注入服务，无需手动配置
|
||
3. **性能优化**：已添加索引，支持大数据量查询
|
||
4. **消息类型**：
|
||
- `message_type=0`：系统通知（自动发送）
|
||
- `message_type=1`：私信（手动发送）
|
||
5. **目标类型**：
|
||
- `target_type=0`：指定用户
|
||
- `target_type=1`：全员广播
|
||
|
||
---
|
||
|
||
## 十、测试建议
|
||
|
||
### 功能测试
|
||
1. 发送指定用户消息
|
||
2. 发送全员广播消息
|
||
3. 查看消息列表（分页、筛选）
|
||
4. 标记已读功能
|
||
5. 未读数量显示
|
||
6. 组局成功/失败自动通知
|
||
|
||
### 压力测试
|
||
1. 大量用户同时查询消息
|
||
2. 全员广播（1000+用户）
|
||
3. 并发标记已读
|
||
|
||
---
|
||
|
||
## 完成状态
|
||
|
||
### 代码开发
|
||
✅ **100% 完成** - 所有代码文件已创建并实现
|
||
|
||
### 需要完成的部署工作
|
||
⏳ **待执行**：
|
||
1. **数据库部署**：执行 `数据库\SqlServer\创建站内信表.sql` 创建表
|
||
2. **依赖注入验证**：确认服务已正确注入（通常自动扫描已包含）
|
||
3. **接口测试**：使用 Postman 测试所有接口
|
||
4. **前端对接**：
|
||
- 注意接口路径是 `/api/SQ/GetMessageList`（不是 `/api/user/GetMessageList`）
|
||
- 实现消息列表页面
|
||
- 实现未读数量红点显示
|
||
|
||
### 重要修正
|
||
📝 **接口路径说明**：
|
||
- 需求文档建议：`/api/user/GetMessageList`
|
||
- 实际实现路径：`/api/SQ/GetMessageList`
|
||
- 原因：统一放在 SQ 预约模块下管理
|
||
- 前端对接时请使用实际路径
|
||
|
||
详细检查清单请查看：`站内信功能完成情况检查.md`
|