【v4版消息推送】公众号消息订阅功能介绍与使用指南

一、功能概述

公众号消息订阅功能允许表单系统通过 微信公众号 向用户推送通知消息。当表单数据发生提交、更新、审批等操作时，系统自动将消息推送到用户的微信中，实现即时通知。

系统支持两种订阅模式：

二、前置配置

2.1 进入系统后台，点击系统管理菜单，设置公众号参数：

2.2 微信公众平台配置

1. 登录 微信公众平台

2. 进入 设置与开发 → 公众号设置 → 功能设置

3. 配置以下域名：

- JS接口安全域名 ： your-domain.com

- 网页授权域名 ： your-domain.com

2.3 申请订阅消息模板

一次性订阅模板 ：

1. 进入 接口权限 → 订阅消息

2. 查看可用的订阅消息模板ID

长期订阅模板 ：

1. 进入 订阅通知 → 模板库

2. 选择合适的模板并选用

3. 复制模板ID

4. 记录模板中各字段的KEY和类型（如 thing1 、 time2 、 name3 ）

三、表单配置公众号消息

3.1 进入消息配置

1. 打开PC管理后台，进入表单编辑页面

2. 切换到 消息推送 标签页

3. 点击 添加消息配置

3.2 选择消息类型

在消息类型下拉框中选择 公众号 。

3.3 配置基本信息

3.4 编辑公众号内容

点击 编辑内容 按钮，打开公众号消息编辑弹窗：

选择订阅类型 ：一次性订阅 / 长期订阅

填写模板ID ：将从微信公众平台复制的模板ID粘贴到输入框中。

配置消息内容 ：

一次性订阅 — 直接编写消息文本，支持变量插入：

长期订阅 — 按模板字段逐行配置：

点击 插入 按钮可快速插入系统变量或表单字段变量。

3.5 长期订阅字段类型与字数限制

系统会自动根据字段类型截断超长内容，无需手动处理。

四、可用模板变量

4.1 系统变量

4.2 表单字段变量

表单中的每个字段都可以通过字段KEY直接访问：

在编辑弹窗中点击 插入 按钮，下拉列表会自动显示当前表单的所有字段名称和对应变量。

4.3 特殊变量

五、用户订阅流程

5.1 一次性订阅流程

用户点击"订阅消息" → 跳转微信授权页 → 用户确认授权 → 回调记录订阅 → 触发事件时发送1条消息

1. 用户在移动端"我的消息"页面点击 订阅消息 按钮

2. 系统调用接口获取授权链接

3. 页面跳转到微信授权页，用户点击"允许"

4. 微信回调在数据表gzh_subscriptions 中记录用户订阅关系

5. 当对应事件触发时，系统查询未使用的订阅记录，发送消息并标记为已使用

5.2 长期订阅流程

用户点击"订阅消息" → 跳转长期订阅页面 → OAuth静默授权获取openID → 绑定到

用户 → 渲染wx-open-subscribe → 用户点击"允许通知" → 订阅成功

长期订阅基本操作一样，区别是用户只需要订阅一次。当对应事件触发时，系统根据接收人类型从数据库查询用户的 GzhOpenID ，调用微信长期订阅消息接口发送。

六、消息发送机制

6.1 触发时机

6.2 接收人类型

6.3 消息点击跳转

发送的公众号消息自带跳转链接，用户点击消息可直接跳转到对应的记录详情页面。链接地址由系统自动生成：

七、预设模板

系统内置了以下公众号消息模板，可在消息配置中直接选用：

一次性订阅模板 ：提交通知、审批通过通知、审批拒绝通知、管理者指派通知、预约取消通知、预约提醒通知

长期订阅模板 ：提交通知、审批通过通知、审批拒绝通知、预约成功通知、管理者指派通知、预约取消通知、预约提醒通知

使用预设模板时，仍需手动填写从微信公众平台获取的模板ID。

八、常见问题排查

Q1：提示"公众号未配置" 原因： config.yaml 中未配置 wechat.gzhappid 或 wechat.gzhsecret 。

解决：补充公众号AppID和AppSecret配置，并重启服务。

Q2：提示"应用跳转的域名非法" 原因： server.url 配置的域名与微信公众平台中配置的授权域名不一致。

解决：确认 config.yaml 中 server.url 的域名正确，并在微信公众平台 → 功能设置中添加到"网页授权域名"和"JS接口安全域名"。

Q3：提示"未找到可用的订阅模板" 原因：表单消息配置中未填写公众号模板ID。

解决：在表单的消息推送配置中，编辑公众号内容并填写模板ID。

Q4：长期订阅成功但收不到通知 原因：用户的 GzhOpenID 未绑定。

解决：确认用户是通过长期订阅页面（含OAuth授权流程）完成订阅的，检查数据库 users 表中 gzh_open_id 字段是否有值，查看后端日志是否有 [GZH通知] 无有效接收人 提示。

Q5：消息内容显示 <no value> 原因：模板中使用了不存在的变量名。

解决：确认变量名拼写正确（如 {{.K0}} 而非 {{.k00}} ），长期订阅使用扁平化变量（如 {{.K0}} ），不要使用 {{.Data.K0}} ，建议通过"插入"按钮选择变量。

Q6：一次性订阅授权后仍收不到消息 原因：一次性订阅每次授权仅可发送1条消息，发送后即标记为已使用。

解决：用户需要重新授权订阅。如需多次通知，建议改用长期订阅模式。

Q7：长期订阅模板提示"模板id出错" 原因：长期订阅模板ID与一次性订阅模板ID不兼容，两者使用不同的接口。

解决：确保长期订阅使用的模板ID来自微信公众平台 → 订阅通知 → 模板库（而非接口权限中的订阅消息模板）。

九、技术架构

核心文件

API接口

消息发送流程

表单操作（提交/审批/预约等）
        │
        ▼
HandleMessageNotifications()
        │
        ├── 解析消息配置列表
        │
        ├── 构建模板数据（prepareMessageTemplateData）
        │   ├── 系统变量（FormName, Submitter, SubmitTime...）
        │   ├── 表单字段数据（K0, K1, K2...扁平化）
        │   └── 跳转链接（RecordURL）
        │
        └── 遍历消息配置，按类型分发
            │
            ├── type=gzh → sendGzhNotification()
            │   ├── subscribeType=once → 渲染自由文本 → 查询gzh_subscriptions → SendSubscription()
            │   └── subscribeType=longterm → 渲染结构化字段 → 按类型截断 → 查询GzhOpenID → BizSend()
            │
            ├── type=email → sendEmailNotification()
            ├── type=sms → sendSmsNotification()
            ├── type=app → sendAppNotification()
            ├── type=wecom → sendWecomNotification()
            └── type=dingtalk → sendDingtalkNotification()