小程序订阅消息与消息触达体系

旧模板消息：用户在小程序里点一次 → 小程序可在任意时间无限推送
新订阅消息：用户每订阅一次 → 小程序最多推送一条（一次性订阅）

// 服务端发送订阅消息（send 后消耗一次授权）
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send
{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "pages/order/detail?orderId=123",
  "data": {
    "order_no": { "value": "20260928001" },
    "status": { "value": "已发货" },
    "express_company": { "value": "顺丰速运" },
    "express_no": { "value": "SF1234567890" }
  }
}

// 在小程序端引导订阅（onShareAppMessage 同级的授权 API）
Page({
  async onOrderPaid() {
    // 支付成功瞬间，用户刚完成行为，订阅意愿最强
    const res = await wx.requestSubscribeMessage({
      tmplIds: ['TEMPLATE_1', 'TEMPLATE_2']
    });
    // 返回 res['TEMPLATE_1'] === 'accept' 表示授权成功
    if (res['TEMPLATE_1'] === 'accept') {
      wx.showToast({ title: '已订阅发货提醒' });
    }
  }
});

小程序端订阅授权
      ↓ 授权结果（accept）
服务端存储授权记录（openid + template_id + 剩余次数）
      ↓ 业务事件触发（发货/活动/审核）
服务端调用 subscribe/send 接口
      ↓ access_token 鉴权
微信推送至用户服务通知

// Node.js 服务端：订阅消息发送封装
const axios = require('axios');

class SubscribeMessage {
  constructor(appid, secret) {
    this.appid = appid;
    this.secret = secret;
    this.tokenCache = null;
  }

  async getAccessToken(forceRefresh = false) {
    // access_token 有效期 7200s，需缓存避免频繁刷新
    if (this.tokenCache && !forceRefresh && Date.now() < this.tokenCache.expireAt) {
      return this.tokenCache.value;
    }
    const { data } = await axios.get(
      `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${this.appid}&secret=${this.secret}`
    );
    this.tokenCache = {
      value: data.access_token,
      expireAt: Date.now() + (data.expires_in - 300) * 1000  // 提前 5 分钟刷新
    };
    return data.access_token;
  }

  async send(openid, templateId, data, page) {
    const token = await this.getAccessToken();
    const { data: resp } = await axios.post(
      `https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=${token}`,
      { touser: openid, template_id: templateId, data, page }
    );
    // errcode 0 成功；43101 表示该用户订阅次数已用完
    if (resp.errcode === 43101) {
      // 次数耗尽：记日志、触发补订阅引导
      await this.notifyNeedResubscribe(openid);
    }
    return resp;
  }
}

{
  "thing1": { "value": "您的包裹已发货" },   // 字符型，最长 20 字
  "character_string2": { "value": "SF123456" }, // 数字/字母组合
  "time3": { "value": "2026-09-28 15:00" }    // 时间型
}