Mars

外观

通知与消息 ​

概述 ​

系统管理提供四类消息触达能力，覆盖「外部触达」与「内部提醒」两种场景：

  • 短信：面向用户的手机短信，常用于验证码、业务通知、营销触达，依赖第三方短信渠道（阿里云 / 腾讯云 / 华为云）。
  • 邮箱（邮件）：基于 SMTP 的邮件发送，常用于系统通知、审批结果、批量邮件。
  • 站内信：平台内的点对点消息，落库到具体用户，按收件人隔离，用户在「铃铛」面板查看。
  • 通知公告：面向全员或公众的「公开规范型」信息，与站内信的「内部执行型」信息区分（详见通知公告章节）。

短信 ​

短信模块由「渠道 → 模板 → 发送 → 日志 → 回调回执」组成。渠道和模板是发送的前提，日志用于审计与排障，回调接口用于接收渠道商的下发状态回执。

image-20260930114536732

渠道 ​

渠道配置对应一家短信服务商，记录 code（阿里云 / 腾讯云等，以框架层 SmsChannelEnum 为单一真源）、签名 signature、apiKey / apiSecret、callbackUrl 等。status 控制启停。渠道编码与框架层枚举保持一致，避免两处值漂移。

模板 ​

模板抽象一条可复用的短信内容，记录 type（验证码 / 通知 / 营销）、content、params（占位符参数，缺省时按内容自动解析）、以及关联的 channelId / channelCode、apiTemplateId（服务商侧的模板编号）。发送时只需传 templateCode 与 templateParams，由服务层完成参数渲染并调用对应渠道客户端。

发送与日志 ​

发送入口为模板的「发送短信」接口，核心流程如下：

日志表 system_sms_log 同时记录「发送状态」与「接收状态」两套状态，并保存服务商返回的请求 ID、流水号、回执码与说明，便于对账与问题定位。

渠道商回调 ​

不同渠道商通过各自的回调路由回执：

  • /sms/callback/aliyun、/sms/callback/tencent 已对接，按流水号反查日志并写回接收状态、接收时间、回执码。
  • /sms/callback/huawei、/sms/callback/qiniu 预留接口，待补充解析逻辑。

回调接口对解析失败做了容错：即便回执无法解析也返回成功响应，避免渠道商因重试失败持续推送。

后端位置 ​

backend/app/api/v1/module_system/sms/，权限码前缀 system:sms-channel / system:sms-template / system:sms-log，并包含 system:sms-template:send-sms 发送权限。

前端页面 ​

frontend/apps/web-ele/src/views/system/sms/ 下包含三个模块：

  • channel/：渠道的增删改查、启停与导出。
  • template/：模板维护，提供「发送短信」弹窗（modules/send-form.vue）。
  • log/：短信日志分页与详情。

邮箱（邮件） ​

邮件模块与短信结构一致：先配置「账号」，再维护「模板」，发送后写入「日志」。

image-20260930114637133

账号 ​

账号即一个 SMTP 发信配置，记录 mail / username / password、host / port，以及 sslEnable / starttlsEnable 加密开关。支持「测试发送」接口，向指定收件人发送一封测试邮件以验证配置可用性。账号变更后会清理对应的 Redis 缓存命名空间，保证下一次发送命中最新配置。

模板 ​

模板记录 name / code / title / content、accountId（绑定的发信账号）、nickname（发件人名称）与 params。content 中的占位符参数由后端自动提取，前端无需手动填写参数列表。发送接口支持「收件人 / 抄送 / 密送」三组地址。

日志 ​

system_mail_log 记录每次发送的目标地址、账号、模板快照、发送状态与异常信息，便于审计失败原因。

后端位置 ​

backend/app/api/v1/module_system/mail/，权限码前缀 system:mail-account / system:mail-template / system:mail-log，发送权限为 system:mail-template:send-mail。

前端页面 ​

frontend/apps/web-ele/src/views/system/mail/ 下包含 account/、template/、log/ 三个模块，模板模块提供「发送邮件」弹窗（modules/send-form.vue）。

站内信 ​

站内信是平台内的点对点消息。它分两层：可复用的「模板」与已渲染、个性化的「消息实例」。

image-20260930114734420

模板 ​

模板（system_notify_template）记录 name / code / nickname / content / type / status，content 使用 {name} 或 {} 占位符，params 由内容自动提取。status 为 0 启用 / 1 禁用，禁用后不可发送。模板写入后会进入 Redis 缓存，发送时优先命中缓存以提升性能。

消息与我的站内信 ​

模板发送后，服务层校验模板可用性与参数完整性，渲染内容，并为每位收件人生成一条消息记录（system_notify_message）。消息冗余保存模板的发送人、内容、类型、参数，因此即使模板后续变更，历史消息依然完整可读。

消息按收件人隔离（__permission_strategy__ = OWN，仅本人可见），核心端点包括：

  • 「我的站内信」分页：当前用户视角的消息列表。
  • 「标记已读 / 全部已读」：点击查看详情时标记为已读，并记录 readTime。
  • 「未读列表 / 未读数量」：供顶部铃铛实时展示角标。

后端位置 ​

  • 模板：backend/app/api/v1/module_system/notify_template/，权限码前缀 system:notify-template，发送权限 system:notify-template:send-notify。
  • 消息：backend/app/api/v1/module_system/notify_message/（page 管理端点 system:notify-message:query 不做数据权限过滤，my-page 等用户端点仅校验登录）。

前端页面 ​

frontend/apps/web-ele/src/views/system/notify/ 下包含：

  • template/：模板维护与「发送站内信」弹窗（modules/send-form.vue）。
  • message/：管理后台视角的全量消息记录。
  • my/：当前用户「我的站内信」，支持已读、全部已读与未读筛选。

通知公告 ​

通知公告用于向全员或公众发布重要事项，与站内信定位不同：

  • 通知（内部执行型）：面向内部组织管理，如会议安排、制度调整、人员变动、任务布置，强调「明确执行责任」。
  • 公告（公开规范型）：面向全体员工、合作伙伴或社会公众，如政策、业务动态，强调「告知与规范」。

image-20260930114822455

维护与推送 ​

公告记录 title / content / type（1 通知 / 2 公告）、status（0 正常 / 1 关闭）、remark。内容会经过 HTML 净化（sanitize_html）后再落库，避免存储型 XSS。push 接口用于主动推送，status/batch 用于批量启停。公告变更后清理 Redis 缓存。

面板（铃铛） ​

image-20260930115147633

顶部铃铛的「通知面板」是一个聚合接口 /notice/panel，一次返回三类数据：

  • notices：已启用通知公告列表。
  • messages：站内信消息摘要（标题 / 内容 / 时间 / 类型）。
  • pendings：待办事项列表。

面板与「已启用公告」接口均带 Redis 缓存（面板 30s、公告 120s），在高并发下降低数据库压力。

后端位置 ​

backend/app/api/v1/module_system/notice/，权限码前缀 system:notice，含 create / update / delete / query / export / push / patch。

前端页面 ​

  • frontend/apps/web-ele/src/views/system/notice/：公告的增删改查、推送、导出。
  • 顶部铃铛组件 frontend/packages/effects/layouts/src/widgets/notification/，通过 header 的 notification 挂件开关（preferences.widget.notification）控制是否展示。
  • 个人中心的 notification-setting.vue 提供消息相关的偏好设置。

统一约定 ​

数据权限 ​

  • 站内信消息按收件人隔离（OWN 策略，仅本人可见），「我的站内信」类端点仅校验登录态。
  • 短信、邮件、通知公告的管理与模板数据默认 NONE 策略（按菜单/角色权限控制），不做行级数据隔离。

模板参数 ​

短信、邮件、站内信三类模板的 params 都由后端根据内容中的占位符（{} / {name}）自动提取，创建或更新时无需前端传入；发送时按参数名填充即可。站内信渲染同时兼容命名占位符 {name} 与位置占位符 {}。

缓存 ​

邮件账号、通知公告、站内信模板均使用 Redis 缓存，对应命名空间为 mail_account、mail_template、notice、notify_template。数据变更时清除缓存，保证下一次读取命中最新配置。