ODTS-57: JUMS 通知服务——模板化的邮件与短信通知

目标读者：想理解 ODTS 如何向客户和运营发送邮件/SMS 通知、模板机制和消息格式的 BA/PM

相关文档：ODTS-14 (结算), ODTS-52 (外部系统可视化)

为什么 BA/PM 需要理解通知服务

通知服务是交易台与客户/运营之间的”最后一句话”——所有系统处理的结果，最终要通过通知告知人类行动。通知失败 = 业务流程无声断裂。

通知失败的真实代价：

• Margin Call 通知延迟： 如果 JUMS 发送 margin call 催缴邮件延迟了 2 小时，客户可能在 16:00 银行关闭后才看到通知。当天无法打款，构成技术性违约。即使只延迟一次，5000 万名义本金的隔夜风险敞口 = 可能 100 万以上的潜在损失。 这也是为什么 margin call 必须 Email + SMS 双通道——SMS 作为备用通道，即使邮件延迟，短信也能确保触达。
• 结算通知遗漏 = 客户投诉： 一笔 1000 万的票息支付完成后，系统应该自动发通知告知客户”钱已到账”。如果通知遗漏，客户不会主动知道钱已到账——他们会认为交易台还没支付，打电话问销售。每次遗漏通知导致销售接一个”钱在哪”的电话，消耗销售 5-10 分钟。月均 5-10 次遗漏 = 每月 25-100 分钟，销售时间比运营值钱得多。
• 模板维护的操作风险： 运营在 JUMS 管理后台修改模板时可能引入语法错误（比如 {{amount}} 写成了 {amount}}），系统不会报错——只是通知渲染失败。Margin call 催缴邮件可能显示为”尊敬的客户，您的账户需要追加保证金 ${amount}“——客户不会理解这个占位符，以为交易台发错了邮件。这种”静默失败” (silent failure) 是最危险的：系统显示”已发送”，但客户收到的邮件是一堆乱占位符。
• 运营告警疲劳： 结算失败告警每次失败都发。如果某个银行当天系统不稳定，运营可能一上午收 20 封同样的告警邮件，导致”狼来了”效应——真正紧急的 margin call 通知被忽略。

概述

JUMS (J Unified Message Service) 是 ODTS 的模板化通知服务,支持邮件(Email)和短信(SMS)两种渠道。它不是通用的消息中间件(如 ActiveMQ/Kafka),而是专注于面向人的通知——发送 Margin Call 警报、结算完成通知、合同签署提醒等运营和客户触达消息。

JUMS 由 Odyssey cash-manager-service 等微服务调用,配置在 application.yml 中。

配置

jums:
  url: https://jums.internal.cicc.com/api
  channelKey: odts-cash-channel
  masterSecret: ****
  templateUrl: https://jums.internal.cicc.com/templates
  templateId: 1001

配置项	说明
url	JUMS 服务 API 基地址
channelKey	渠道标识,用于权限认证
masterSecret	密钥,用于 API 签名
templateUrl	模板管理页面地址
templateId	默认使用的通知模板 ID

发送模式

模式一：模板邮件 (EmailTemplateNotice)

使用预定义的模板发送邮件：

{
  "aud_email": [{
    "instance": "email",
    "group": {
      "to": ["client@example.com", "ops@cicc.com"]
    }
  }],
  "template_id": 1001,
  "template_para": {
    "clientName": "某某投资有限公司",
    "amount": "1,230,456.78",
    "currency": "CNY",
    "settlementDate": "2025-07-16",
    "tradeRef": "SNOWBALL202507001"
  }
}

处理流程： JUMS 查找 template_id=1001 对应的模板 → 用 template_para 填充模板占位符 → 按 aud_email 中的收件人列表发送。

模式二：邮件+SMS 组合 (EmailSmsNotice)

同时发送邮件和短信：

{
  "aud_email": [
    { "instance": "email", "data": ["ops@cicc.com"] }
  ],
  "aud_sms": [
    { "instance": "sms", "data": ["13800138000"] }
  ],
  "msg_email": [
    { "subject": "Margin Call 通知", "text": "尊敬的客户..." }
  ],
  "msg_sms": [
    { "content": "您的账户需要追加保证金1,000,000元..." }
  ]
}

谁使用组合模式： Margin Call 和结算失败等需要即时触达的高优场景。

模式三：分组发送

JUMS 支持按组分发：

{
  "aud_email": [{
    "instance": "email",
    "group": { "to": ["ops@cicc.com"] },
    "group_type": "SINGLE"
  }]
}

group_type 区分单组(SINGLE)和多组(GROUP),前者所有收件人在同一封邮件中(可见彼此),后者每人一封独立邮件。

通知场景

业务场景	通知渠道	触发事件	模板变量
资金划转完成	Email	IPMP 转账成功	金额、日期、对手方
Margin Call	Email + SMS	保证金比例低于阈值	催缴金额、期限、账户
合同签署提醒	Email	合同生成待签署	合同号、对手方、链接
结算失败告警	Email + SMS	转账FAILED	失败原因、金额、操作指引
日终对账差异	Email	报告完成	差异笔数、金额、时间
系统异常告警	SMS	轮询超时/报错	服务名、异常信息

模板系统

JUMS 使用预定义模板而非动态生成。模板在 JUMS 管理后台上维护：

模板 ID	名称	渠道	说明
1001	结算完成通知	Email	标准转账完成通知
1002	Margin Call 催缴	Email+SMS	保证金不足紧急通知
1003	合同签署请求	Email	通知签署
1004	系统告警	SMS	运营内部异常通知

模板内容包含占位符(如 {{clientName}}),由 template_para 填充。模板变更不需要改代码,在 JUMS 管理后台修改即可。

关键代码目录

odyssey/cash-manager-service/src/main/java/.../jums/
├── JUMSClient.java                        ← JUMS HTTP REST 客户端
├── JUMSConfig.java                        ← 配置类
├── EmailTemplateNotice.java               ← 模板邮件 VO
├── EmailSmsNotice.java                    ← 邮件+SMS VO
└── AUD.java                               ← 收件人 VO(Email/SMS 地址)