用 InterSystems IRIS 将业务通知推送到企业微信

在医院、企业和运维场景中，很多重要信息都需要及时送达相关人员：接口运行异常、系统资源告警、审批提醒、任务完成通知……这些消息通常由不同业务系统产生，但接收人员希望在一个熟悉的地方查看。

企业微信是一个自然的选择。对于已经使用 InterSystems IRIS Interoperability 的团队，如果能够直接在 Production 中配置企业微信出站组件，就可以把现有业务流程中的消息发送到员工或工作群，而不必为每个业务系统单独开发一套推送服务。

iris-wechat-gateway 就是为这个目的设计的。它提供基于 IRIS Interoperability 的企业微信出站适配器，让业务流程通过 Business Operation 发送企业微信消息。项目源码可在 GitHub 仓库查看。

项目能做什么？

当前版本支持两种企业微信消息通道：

两种通道都支持 text 和 markdown 消息。例如：

• 发送接口故障或服务器磁盘空间告警；
• 通知员工某项任务已完成；
• 向相关部门推送业务处理结果；
• 在运维群中集中展示监控通知。

消息由 IRIS 业务流程构造，再通过对应的 Business Operation 和 Outbound Adapter 发送：

业务系统 / Business Process
          │
          ▼
WeChat.Message.Outbound
          │
          ▼
企业微信 Business Operation
          │
          ▼
企业微信 Outbound Adapter
          │
          ▼
企业微信应用消息或群消息推送

为什么要放在 IRIS Production 中？

IRIS Interoperability 已经提供了业务服务、业务流程、业务操作以及消息监控等机制。将企业微信推送作为出站组件接入 Production，可以让通知成为现有集成流程的一部分。

例如，当一个业务流程发现外部接口连续调用失败时，它可以构造一条通知，发送给企业微信消息推送 BO；而当一项业务任务完成时，也可以通过应用消息 BO 将结果发给指定员工。

在同一个 Production 中使用统一的消息对象和 BO，还有利于集中管理目标配置、查看处理过程，以及与其他集成组件协作。

两种通道如何使用？

企业微信应用消息

应用消息适合向企业内部的指定人员发送通知。使用前需要准备：

• 企业 CorpID；
• 自建应用的 AgentId 和 Secret；
• 应用的可见范围和接收对象；
• 企业微信要求的出口可信 IP 配置。

项目通过应用凭据获取和缓存 access_token，然后调用企业微信应用消息接口。接收目标可以是用户、部门或标签。

下面的示例展示了在 Business Process 或其他 Business Host 的实例方法中发送一条文本消息：

// 创建企业微信出站消息
set req = ##class(WeChat.Message.Outbound).%New()
set req.MsgType = "text"
set req.Content = "您的任务已完成"
set req.ToUser = "userid1|userid2"
set req.AgentId = 1000002  // 替换为与 BO 配置一致的应用 AgentId

// 可选：启用平台侧重复消息检查
set req.EnableDuplicateCheck = 1
set req.DuplicateCheckInterval = 1800

// 将消息发送到 Production 中配置的应用消息 BO
set resp = ""
set sc = ..SendRequestSync("SendWeComApp", req, .resp)

if $isobject(resp) {
    write !, "发送结果：", resp.Result
    write !, "错误码：", resp.ErrorCode
}

if $system.Status.IsError(sc) {
    do $system.Status.DisplayError(sc)
}

示例中的 SendWeComApp 是演示 Production 的配置名称；在自己的 Production 中，应替换为实际配置的 BO 名称。AgentId 和收件人均为示例值，实际使用时需要替换。调用示例应放在已编译的业务方法中。

企业微信消息推送

消息推送适合向群聊发送共享通知，例如系统告警或部署结果。该通道使用 webhook key，不需要获取应用 access_token。

// 创建群消息推送请求
set req = ##class(WeChat.Message.Outbound).%New()
set req.MsgType = "text"
set req.Content = "服务器磁盘使用率已达到 92%"

// 文本消息可以提醒群内所有人
do req.MentionedList.SetAt("@all", 1)

// 发送到 Production 中配置的消息推送 BO
set resp = ""
set sc = ..SendRequestSync("SendWeComRobot", req, .resp)

if $isobject(resp) {
    write !, "发送结果：", resp.Result
}

if $system.Status.IsError(sc) {
    do $system.Status.DisplayError(sc)
}

Webhook key 属于敏感凭据。建议通过 IRIS Interoperability 凭据管理配置，而不是把 key 写入代码、公开文档或版本库。

消息结果如何判断？

发送接口返回的结果并不总是简单的“成功”或“失败”。例如，平台可能接受了请求，但部分接收人无效；网络超时时，也可能出现消息已经送达、响应却没有返回的情况。

项目将发送结果分为四类：

accepted 表示适配器判定请求已受理，不等于接收人最终看到消息；应结合返回状态及 ErrorCodePresent、ErrorCode 判断。对于 partial，调用方可以检查 InvalidUser、InvalidParty、InvalidTag 和 UnlicensedUser 等字段，了解哪些接收对象存在问题。

对于 unknown，网关默认不自动重发，因为消息可能已经到达平台。业务系统可以先核查处理状态，再决定是否补发。应用消息的平台侧去重选项可以降低部分重复风险，但不能保证端到端恰好一次。

中文、长度和安全配置

企业微信不同通道、不同消息类型的内容长度限制不同。项目按 UTF-8 字节数校验消息，超长时在发送前拒绝，避免静默截断。

项目也考虑了中文和 emoji 的传输编码，并提供 token 缓存、凭据读取、错误分类和重试处理。配置企业微信 HTTPS 连接时，需要在 IRIS 中配置并验证客户端 TLS 和证书信任，将配置名填入对应 BO 的 Adapter SSLConfig。应用消息和消息推送的凭据分别通过 SecretCredential 和 RobotKeyCredential 配置。

启动项目

项目提供 Docker Compose 开发环境。先克隆仓库，再在项目根目录执行：

git clone https://github.com/boanerges1227/iris-wechat-gateway.git
cd iris-wechat-gateway
docker compose up -d --build

启动后可通过以下地址访问 IRIS 管理门户：

http://localhost:52774/csp/sys/UtilHome.csp

在 WECHAT 命名空间中，可以找到演示 Production：WeChat.Production.Demo。其中包含应用消息和消息推送两个 BO。在两个 BO 的 Adapter 设置中配置凭据、企业微信参数和 SSLConfig 后，业务流程即可按对应名称调用。应用消息的请求 AgentId 应与配置的应用一致。

更详细的配置项和使用步骤可参考项目的中文 README。

结语

iris-wechat-gateway 的目标是让企业微信通知融入现有 IRIS 集成流程：业务系统负责产生消息，Production 负责组织处理，企业微信则将通知送到需要它的人或工作群。

对于已经使用 IRIS Interoperability 的团队，这种方式可以把通知能力放在熟悉的集成架构中统一配置和管理。