消息通知开发文档.md 18 KB
消息通知开发文档
1. 文档概述
1.1 文档目的
本文档旨在详细说明CRMEB系统中消息通知模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导消息通知模块的开发、扩展和维护工作。
1.3 术语定义
| 术语 | 解释 |
|---|---|
| 系统消息 | 存储在数据库中的站内信，通过系统内部推送 |
| 模板消息 | 包括公众号模板消息和小程序订阅消息 |
| 短信通知 | 通过第三方短信服务商发送给用户手机的消息 |
| 企业微信消息 | 发送给管理员和客服的企业微信消息 |
| 事件驱动 | 通过触发事件来处理各种通知场景 |
| 通知渠道 | 消息发送的方式，如站内信、短信、模板消息等 |
| 通知场景 | 触发通知的业务场景，如订单支付、发货等 |
2. 核心功能模块
2.1 系统消息管理
- 消息列表：展示系统消息，支持搜索、分页
- 消息添加：添加新的系统消息
- 消息编辑：修改系统消息内容
- 消息删除：删除系统消息
- 消息发送：发送系统消息给指定用户或用户组
- 消息阅读：记录用户消息阅读状态
- 消息统计：统计消息发送和阅读情况
2.2 短信通知管理
- 短信模板管理：添加、编辑、删除短信模板
- 短信发送记录：查看短信发送记录和状态
- 短信配置：配置短信服务商、API密钥等
- 短信签名管理：管理短信签名
- 短信场景配置：配置不同场景下的短信模板
2.3 模板消息管理
- 公众号模板消息管理：添加、编辑、删除公众号模板消息
- 小程序订阅消息管理：添加、编辑、删除小程序订阅消息
- 模板消息发送记录：查看模板消息发送记录和状态
- 模板消息配置：配置不同场景下的模板消息
2.4 企业微信消息管理
- 企业微信配置：配置企业微信API密钥、AgentId等
- 企业微信消息模板：添加、编辑、删除企业微信消息模板
- 企业微信消息发送记录：查看企业微信消息发送记录和状态
2.5 通知场景配置
- 通知场景列表：展示系统支持的各种通知场景
- 场景通知配置：配置每个场景下需要发送的通知渠道
- 通知模板配置：为每个场景配置对应的通知模板
- 通知状态管理：开启/关闭特定场景的通知
3. 代码结构与设计
3.1 架构设计
系统采用事件驱动的架构设计，通过监听器统一处理各种通知事件：
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 业务事件触发 │────▶│ 事件监听器 │────▶│ 通知服务处理 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 系统消息发送 │◀────│ 多渠道通知 │────▶│ 短信通知发送 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────┐
│ 模板消息发送 │
├─────────────────────────┤
│ - 公众号模板消息 │
│ - 小程序订阅消息 │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 企业微信消息发送 │
└─────────────────────────┘
3.2 核心文件结构
3.2.1 服务层（Services）
消息通知服务：
NoticeService.php- 通知服务基类，用于设置和管理通知事件SystemNotificationServices.php- 系统通知配置管理类，包含各种通知场景的定义MessageSystemServices.php- 站内信服务类，处理用户站内消息的发送、查询和管理SmsService.php- 短信服务类，支持多种短信服务商TemplateMessageServices.php- 模板消息管理类，管理公众号模板消息和小程序订阅消息
3.2.2 监听器（Listener）
通知事件监听器：
NoticeListener.php- 核心事件监听器，处理各种通知事件，映射了30+种通知场景到对应的处理方法CustomNoticeListener.php- 自定义通知监听器，用于处理特殊通知场景
3.2.3 模型层（Model）
消息相关模型：
MessageSystem.php- 系统消息模型SmsRecord.php- 短信发送记录模型SystemNotification.php- 系统通知配置模型TemplateMessage.php- 模板消息模型
3.2.4 控制器层（Controller）
消息通知控制器：
SystemNotification.php- 系统通知配置控制器MessageSystem.php- 系统消息控制器Sms.php- 短信管理控制器TemplateMessage.php- 模板消息控制器
3.2.5 路由配置
消息通知路由：
- 包含消息通知相关的API路由，如系统消息管理、短信配置、模板消息管理等
4. 数据库设计
4.1 系统消息表（message_system）
| 字段名 | 数据类型 | 描述 |
|---|---|---|
| id | int(10) unsigned | 消息ID |
| uid | int(10) | 接收用户ID |
| title | varchar(100) | 消息标题 |
| content | text | 消息内容 |
| type | varchar(20) | 消息类型 |
| status | tinyint(1) | 阅读状态（0-未读，1-已读） |
| add_time | int(10) | 添加时间 |
| read_time | int(10) | 阅读时间 |
4.2 短信发送记录表（sms_record）
| 字段名 | 数据类型 | 描述 |
|---|---|---|
| id | int(10) unsigned | 记录ID |
| phone | varchar(20) | 接收手机号 |
| template_id | varchar(50) | 短信模板ID |
| template_param | text | 模板参数（JSON格式） |
| content | text | 短信内容 |
| status | tinyint(1) | 发送状态（0-失败，1-成功） |
| error_msg | varchar(255) | 错误信息 |
| add_time | int(10) | 发送时间 |
4.3 系统通知配置表（system_notification）
| 字段名 | 数据类型 | 描述 |
|---|---|---|
| id | int(10) unsigned | 配置ID |
| mark | varchar(50) | 通知标识 |
| title | varchar(100) | 通知标题 |
| scene | varchar(50) | 通知场景 |
| type | varchar(20) | 通知类型（system-系统消息，sms-短信，wechat-微信模板消息） |
| template | text | 通知模板 |
| is_open | tinyint(1) | 是否开启（0-关闭，1-开启） |
| sort | int(10) | 排序 |
| add_time | int(10) | 添加时间 |
4.4 模板消息表（template_message）
| 字段名 | 数据类型 | 描述 |
|---|---|---|
| id | int(10) unsigned | 模板ID |
| type | varchar(20) | 模板类型（wechat-公众号，routine-小程序） |
| name | varchar(50) | 模板名称 |
| template_id | varchar(100) | 微信模板ID |
| short_key | varchar(50) | 模板短键 |
| content | text | 模板内容 |
| example | text | 模板示例 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
5. API接口说明
5.1 系统消息管理
5.1.1 获取系统消息列表
- 请求URL：
/adminapi/v1/message/system/list - 请求方法：GET
- 权限要求：message/system/list
- 请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：阅读状态
- 返回结果：系统消息列表数据
5.1.2 发送系统消息
- 请求URL：
/adminapi/v1/message/system/send - 请求方法：POST
- 权限要求：message/system/send
- 请求参数：
- uids：用户ID数组
- title：消息标题
- content：消息内容
- type：消息类型
- 返回结果：操作结果
5.2 短信管理
5.2.1 获取短信模板列表
- 请求URL：
/adminapi/v1/message/sms/template/list - 请求方法：GET
- 权限要求：message/sms/template/list
- 返回结果：短信模板列表数据
5.2.2 发送短信
- 请求URL：
/adminapi/v1/message/sms/send - 请求方法：POST
- 权限要求：message/sms/send
- 请求参数：
- phone：接收手机号
- template_id：短信模板ID
- params：模板参数（JSON格式）
- 返回结果：操作结果
5.3 模板消息管理
5.3.1 获取模板消息列表
- 请求URL：
/adminapi/v1/message/template/list - 请求方法：GET
- 权限要求：message/template/list
- 请求参数：
- type：模板类型（wechat-公众号，routine-小程序）
- 返回结果：模板消息列表数据
5.3.2 发送模板消息
- 请求URL：
/adminapi/v1/message/template/send - 请求方法：POST
- 权限要求：message/template/send
- 请求参数：
- openid：用户openid
- template_id：模板ID
- data：模板数据（JSON格式）
- page：跳转页面
- 返回结果：操作结果
5.4 通知场景配置
5.4.1 获取通知场景列表
- 请求URL：
/adminapi/v1/message/notification/list - 请求方法：GET
- 权限要求：message/notification/list
- 返回结果：通知场景列表数据
5.4.2 配置通知场景
- 请求URL：
/adminapi/v1/message/notification/config - 请求方法：POST
- 权限要求：message/notification/config
- 请求参数：
- scene：通知场景
- config：通知配置（JSON格式，包含各通知渠道的开启状态和模板）
- 返回结果：操作结果
5.5 用户端接口
5.5.1 获取用户消息列表
- 请求URL：
/api/v1/user/message/list - 请求方法：GET
- 权限要求：登录用户
- 请求参数：
- page：页码
- limit：每页数量
- type：消息类型
- 返回结果：用户消息列表数据
5.5.2 标记消息为已读
- 请求URL：
/api/v1/user/message/read/{id} - 请求方法：PUT
- 权限要求：登录用户
- 返回结果：操作结果
5. 开发规范与流程
5.1 代码规范
命名规范：
- 类名采用大驼峰命名法，如
NoticeService - 方法名采用小驼峰命名法，如
sendSystemMessage - 变量名采用小驼峰命名法，如
messageContent - 常量名采用全大写，下划线分隔，如
NOTICE_SCENE_ORDER_PAY
- 类名采用大驼峰命名法，如
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有通知发送必须记录日志，便于追溯
事件驱动：
- 所有通知场景必须通过事件触发
- 事件名称必须清晰明了，反映触发场景
- 事件监听器必须统一处理，便于管理
5.2 开发流程
- 需求分析：明确消息通知的功能需求和业务场景
- 设计阶段：设计事件结构、API接口和业务流程
- 编码实现：
- 定义事件类（如果需要）
- 在NoticeListener中添加事件处理方法
- 实现通知发送逻辑
- 添加API接口
- 单元测试：编写单元测试，确保功能正确性
- 集成测试：进行模块集成测试，测试通知与其他模块的交互
- 性能测试：对高频通知场景进行性能测试
- 代码审查：提交代码审查，确保代码质量
- 部署上线：部署到生产环境
6. 常见问题与解决方案
6.1 通知发送失败
问题：通知发送失败，如短信发送失败、模板消息发送失败 解决方案：
- 检查配置是否正确，如API密钥、模板ID等
- 检查第三方服务是否正常，如短信服务商、微信接口等
- 查看发送日志，定位具体错误原因
- 实现重试机制，对发送失败的通知进行重试
6.2 通知延迟
问题：通知发送延迟，如订单支付后很久才收到通知 解决方案：
- 检查队列配置，确保队列服务正常运行
- 优化通知发送逻辑，减少处理时间
- 增加队列消费者数量，提高处理能力
- 实现异步发送，避免阻塞主流程
6.3 通知重复发送
问题：同一通知重复发送给用户 解决方案：
- 实现幂等性处理，确保同一事件不会触发多次通知
- 检查事件触发逻辑，避免重复触发
- 在通知发送前检查是否已经发送过
- 实现去重机制，过滤重复通知
6.4 通知模板管理混乱
问题：通知模板过多，管理混乱 解决方案：
- 对模板进行分类管理，如按通知渠道、按业务场景
- 建立模板命名规范，清晰反映模板用途
- 定期清理无用模板
- 实现模板版本管理，便于回滚
7. 扩展与定制
7.1 添加新的通知场景
- 定义场景常量：在相关常量类中添加新的通知场景常量
- 添加事件处理：在NoticeListener中添加对应的事件处理方法
- 配置模板：在system_notification表中添加对应的通知模板配置
- 添加触发点：在业务逻辑中添加事件触发代码
- 前端配置：在后台管理界面中添加对应的配置项
7.2 添加新的通知渠道
- 实现服务类：创建新的通知服务类，继承NoticeService
- 添加配置项：在系统配置中添加新的通知渠道配置
- 更新事件监听器：在NoticeListener中添加新渠道的通知发送逻辑
- 前端配置：在后台管理界面中添加对应的配置项
7.3 自定义通知模板
- 添加模板字段：在system_notification表中添加模板字段
- 更新模板管理：修改模板管理功能，支持自定义模板
- 实现模板渲染：在通知服务中添加模板渲染逻辑
- 前端配置：在后台管理界面中添加模板编辑功能
8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|---|---|---|---|
| 1.0 | 2026-01-19 | 初始版本，包含系统消息管理、短信通知管理、模板消息管理、企业微信消息管理、通知场景配置等核心功能 | AI Assistant |
9. 附录
9.1 核心类关系图
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ NoticeService │────▶│ NoticeListener │────▶│ 各种通知服务 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ SystemMessage │◀────│ MessageSystem │ │ SmsService │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────┐
│ TemplateMessageServices │
├─────────────────────────┤
│ - 公众号模板消息 │
│ - 小程序订阅消息 │
└─────────────────────────┘
9.2 通知流程示意图
通知流程：
1. 业务系统触发事件（如订单支付成功）
2. 事件监听器捕获事件
3. 根据事件类型查找对应的通知配置
4. 遍历配置的通知渠道
5. 调用对应服务发送通知
a. 发送系统消息
b. 发送短信通知
c. 发送模板消息
d. 发送企业微信消息
6. 记录通知发送日志
7. 返回发送结果
9.3 支持的通知场景
| 场景名称 | 描述 |
|---|---|
| order_pay | 订单支付成功 |
| order_delivery | 订单发货 |
| order_received | 订单收货 |
| order_refund | 订单退款 |
| order_price_edit | 订单改价 |
| recharge_success | 充值成功 |
| extract_success | 提现成功 |
| extract_fail | 提现失败 |
| brokerage_arrive | 佣金到账 |
| bargain_success | 砍价成功 |
| pink_success | 拼团成功 |
| pink_fail | 拼团失败 |
| user_register | 用户注册 |
| user_login | 用户登录 |
| spread_bind | 推广关系绑定 |
9.4 支持的通知渠道
| 渠道名称 | 描述 |
|---|---|
| system | 系统消息（站内信） |
| sms | 短信通知 |
| 公众号模板消息 | |
| routine | 小程序订阅消息 |
| enterprise_wechat | 企业微信消息 |
提示：该文档由AI生成，仅供参考。