# 站内信功能开发总结

## 开发完成时间
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`