outsource/mahjong_group

Fork 0

zpc 63aedaf041 调整文件结构

2026-01-01 14:39:23 +08:00

7.8 KiB

Raw Blame History

站内信功能开发总结

开发完成时间

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=私信）

{
  "code": 0,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "title": "组局成功通知",
      "content": "恭喜您！组局"周末欢乐局"已成功！",
      "createTime": "2025-12-07 10:30",
      "messageType": 0,
      "isRead": false
    }
  ]
}

2. 获取未读消息数量

接口：GET /api/SQ/GetUnreadCount
返回：

{
  "code": 0,
  "msg": "获取成功",
  "data": {
    "count": 5
  }
}

3. 标记所有消息为已读

接口：POST /api/SQ/MarkAllAsRead
返回：

{
  "code": 0,
  "msg": "标记成功"
}

四、后台管理功能

1. 消息列表管理（已开发页面）

访问路径：后台菜单 → SQ管理 → 站内信管理

功能特性：

查看所有消息记录
筛选条件：消息ID、标题、目标类型（指定用户/全员广播）、消息类型（系统通知/私信）
支持查看详情、删除、批量删除
数据分页显示（可选10-200条/页）

2. 发送全员广播（已开发页面）

操作方式：

在消息列表页点击"发送全员广播"按钮
填写消息标题和内容
点击"立即发送"，消息将发送给所有用户

接口：POST /api/SQMessage/SendBroadcast

请求示例：

{
  "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 表是否存在记录

标记全部已读

更新私信：UPDATE SQMessage SET is_read=1
插入广播已读记录：INSERT INTO SQMessageRead

七、扩展功能建议

短期扩展

消息详情页（点击消息查看完整内容）
删除消息功能
消息搜索功能
批量操作（批量标记已读/删除）

长期扩展

消息分类标签
消息推送到手机端
消息提醒声音/震动设置
定时发送消息
消息模板管理

八、使用说明

前端对接

在"我的"页面添加"我的消息"入口
调用 GetUnreadCount 接口显示红点
进入列表页调用 GetMessageList 获取消息
自动调用 MarkAllAsRead 标记已读

后台使用

访问后台消息管理模块
可以手动发送通知给指定用户或全体用户
查看历史消息记录

九、注意事项

数据库：请先执行 数据库\SqlServer\创建站内信表.sql 创建表
依赖注入：系统已自动注入服务，无需手动配置
性能优化：已添加索引，支持大数据量查询
消息类型：
- message_type=0：系统通知（自动发送）
- message_type=1：私信（手动发送）
目标类型：
- target_type=0：指定用户
- target_type=1：全员广播

十、测试建议

功能测试

发送指定用户消息
发送全员广播消息
查看消息列表（分页、筛选）
标记已读功能
未读数量显示
组局成功/失败自动通知

压力测试

大量用户同时查询消息
全员广播（1000+用户）
并发标记已读

完成状态

代码开发

✅ 100% 完成 - 所有代码文件已创建并实现

需要完成的部署工作

⏳ 待执行：

数据库部署：执行 数据库\SqlServer\创建站内信表.sql 创建表
依赖注入验证：确认服务已正确注入（通常自动扫描已包含）
接口测试：使用 Postman 测试所有接口
前端对接：
- 注意接口路径是 /api/SQ/GetMessageList（不是 /api/user/GetMessageList）
- 实现消息列表页面
- 实现未读数量红点显示

重要修正

📝 接口路径说明：

需求文档建议：/api/user/GetMessageList
实际实现路径：/api/SQ/GetMessageList
原因：统一放在 SQ 预约模块下管理
前端对接时请使用实际路径

详细检查清单请查看：站内信功能完成情况检查.md

7.8 KiB Raw Blame History Unescape Escape