微信开放平台接入实战：打通授权事件与心跳回调

[微信开放平台后台详情页 - 关键配置一览]
   ├── 1. 记下凭据：开发者ID (AppId) & 开发者密码 (AppSecret)
   ├── 2. 配置白名单：把本地电脑的公网出口 IP 加入【IP白名单】
   ├── 3. 基础安全配置：消息校验Token & 消息加解密Key (EncodingAESKey)
   ├── 4. 核心回调配置：授权事件接收URL & 公众号消息接收URL
   └── 5. 开发沙箱配置：在【测试公众号列表】中绑定你的测试公众号

cpolar http 4307

Forwarding          https://scrm-dev.r10.cpolar.top -> http://localhost:4307

open_platform:
  app_id: "wx58xxxxxxxxxxxxxx"                   # 开发者ID (AppId)
  app_secret: "22a91933f4664a4119118bfd2dacd489" # 开发者密码 (AppSecret)
  token: "my_scrm_token_2026"                    # 消息校验 Token
  encoding_aes_key: "xxx"                        # 消息加解密 Key (EncodingAESKey)

     微信开放平台服务器（open.weixin.qq.com）
                  │
                  │ 主动 POST：每 10 分钟一次心跳；在后台改任意配置保存也会立刻触发一次
                  │ 查询参数：msg_signature · timestamp · nonce
                  │ 请求体：AES 加密的 XML 报文
                  ▼
   POST https://你的域名/v1/open/auth-callback
   ⚠️ 免登录放行 —— 这条路由不挂 JWT 中间件
      （发起方是微信服务器，没有用户身份可校验）
                  │
                  ▼
        ① 验签   Token + timestamp + nonce + msg_signature
                  ▼
        ② 解密   AES（EncodingAESKey）→ 明文 XML
                  ▼
        ③ 解析   xml.Unmarshal → 读 InfoType
                  ▼
        ④ 存票据  InfoType == component_verify_ticket（打通阶段只会收到这一类）
                  │
                  ▼
        写 Redis：scrm:open:ticket:{appid}，TTL 12h 滚动
                  ▼
   回复 "success"（5 秒内；解析失败也回 success，避免微信重发风暴）

func (h *OpenPlatformHandler) RegisterRoutes(server *gin.Engine) {
	// 微信开放平台（第三方平台）路由组
	g := server.Group("/v1/open")
	{
		// 1. 授权事件接收 URL（接收 ticket、授权/取消授权事件）- 对微信服务器免登录放行
		g.POST("/auth-callback", h.ReceiveAuthEvent)
	}
}

// ReceiveAuthEvent 处理微信推送的 component_verify_ticket 及授权变更事件
func (h *OpenPlatformHandler) ReceiveAuthEvent(ctx *gin.Context) {
	msgSignature := ctx.Query("msg_signature")
	timestamp := ctx.Query("timestamp")
	nonce := ctx.Query("nonce")

	body, err := io.ReadAll(ctx.Request.Body)
	if err != nil {
		h.l.Error("读取授权事件请求体失败", zap.Error(err))
		ctx.String(http.StatusBadRequest, "fail")
		return
	}

	event, err := h.svc.ReceiveVerifyTicket(ctx, msgSignature, timestamp, nonce, body)
	if err != nil {
		h.l.Warn("解析授权事件失败", zap.Error(err))
		ctx.String(http.StatusOK, "success") // 无论成功失败均回复 success，避免微信重发风暴
		return
	}

	h.l.Info("处理微信开放平台授权事件成功", zap.String("infoType", event.InfoType))
	ctx.String(http.StatusOK, "success")
}

// TicketXML 微信开放平台推送事件报文结构
type TicketXML struct {
	XMLName               xml.Name `xml:"xml"`
	AppId                 string   `xml:"AppId"`
	CreateTime            int64    `xml:"CreateTime"`
	InfoType              string   `xml:"InfoType"`
	ComponentVerifyTicket string   `xml:"ComponentVerifyTicket"`
	AuthorizerAppid       string   `xml:"AuthorizerAppid"`
	AuthorizationCode     string   `xml:"AuthorizationCode"`
}

func (s *openPlatformService) ReceiveVerifyTicket(ctx context.Context, msgSignature, timestamp, nonce string, encryptedXML []byte) (*TicketXML, error) {
	appID := s.cfg.OpenPlatform.AppId
	token := s.cfg.OpenPlatform.Token
	aesKey := s.cfg.OpenPlatform.EncodingAESKey

	// 1. 初始化微信加解密工具包
	crypt, err := crypto.NewWXBizMsgCrypt(token, aesKey, appID)
	if err != nil {
		return nil, fmt.Errorf("create wxbizmsgcrypt failed: %w", err)
	}

	// 2. 验签并解密 XML 载荷
	decrypted, err := crypt.DecryptMsg(msgSignature, timestamp, nonce, encryptedXML)
	if err != nil {
		return nil, fmt.Errorf("decrypt msg failed: %w", err)
	}

	var event TicketXML
	if err := xml.Unmarshal(decrypted, &event); err != nil {
		return nil, fmt.Errorf("unmarshal decrypted ticket xml failed: %w", err)
	}

	// 3. 提取 component_verify_ticket 并持久化至 Redis（缓存 12 小时滚动更新）
	if event.InfoType == "component_verify_ticket" && event.ComponentVerifyTicket != "" {
		s.l.Info("成功接收并解析微信 component_verify_ticket", zap.String("appId", event.AppId))
		if err := s.repo.SetVerifyTicket(ctx, event.AppId, event.ComponentVerifyTicket, 12*time.Hour); err != nil {
			s.l.Error("保存 component_verify_ticket 至缓存失败", zap.Error(err))
			return &event, err
		}
	}

	return &event, nil
}

package crypto

import (
	"bytes"
	"crypto/aes"
	"crypto/cipher"
	"crypto/rand"
	"crypto/sha1"
	"encoding/base64"
	"encoding/binary"
	"encoding/hex"
	"encoding/xml"
	"errors"
	"fmt"
	"io"
	"sort"
)

// CDATA 结构
type CDATA struct {
	Value string `xml:",cdata"`
}

// EncryptedXMLMsg 微信加密 XML 消息通用外层结构
type EncryptedXMLMsg struct {
	XMLName    xml.Name `xml:"xml"`
	ToUserName string   `xml:"ToUserName"`
	AppId      string   `xml:"AppId"`
	Encrypt    string   `xml:"Encrypt"`
}

// ResponseXMLMsg 被动回复加密 XML 结构
type ResponseXMLMsg struct {
	XMLName      xml.Name `xml:"xml"`
	Encrypt      CDATA    `xml:"Encrypt"`
	MsgSignature CDATA    `xml:"MsgSignature"`
	TimeStamp    string   `xml:"TimeStamp"`
	Nonce        CDATA    `xml:"Nonce"`
}

// WXBizMsgCrypt 微信消息加解密处理器
type WXBizMsgCrypt struct {
	token          string
	encodingAESKey string
	appID          string
	aesKey         []byte
}

func NewWXBizMsgCrypt(token, encodingAESKey, appID string) (*WXBizMsgCrypt, error) {
	if len(encodingAESKey) != 43 {
		return nil, errors.New("EncodingAESKey 长度必须为 43 位")
	}
	aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
	if err != nil {
		return nil, fmt.Errorf("decode aesKey failed: %w", err)
	}
	return &WXBizMsgCrypt{
		token:          token,
		encodingAESKey: encodingAESKey,
		appID:          appID,
		aesKey:         aesKey,
	}, nil
}

// CalcSignature 计算微信签名
func CalcSignature(token, timestamp, nonce, msgEncrypt string) string {
	params := []string{token, timestamp, nonce, msgEncrypt}
	sort.Strings(params)
	h := sha1.New()
	for _, p := range params {
		h.Write([]byte(p))
	}
	return hex.EncodeToString(h.Sum(nil))
}

// VerifySignature 验证签名
func (c *WXBizMsgCrypt) VerifySignature(msgSignature, timestamp, nonce, msgEncrypt string) bool {
	sig := CalcSignature(c.token, timestamp, nonce, msgEncrypt)
	return sig == msgSignature
}

// DecryptMsg 解密微信加密报文，返回明文字节
//
// 官方开发文档（消息推送与加解密方案）:
// https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/message_push.html
// 官方多语言示例 (Java/Python/C++/PHP): https://wximg.gtimg.com/shake_tv/mpwiki/cryptoDemo.zip
//
// 核心解密步骤说明:
// 1. 提取密文: 从 HTTP POST 的 XML 报文中解析出 <Encrypt> 密文字符串；
// 2. 防篡改验签: 将 [token, timestamp, nonce, encrypt] 字典排序后计算 SHA-1 签名，与 msg_signature 比对；
// 3. AES-CBC 解密: 对 Encrypt 进行 Base64 解码，使用 32 字节 AESKey 和 IV (固定为 AESKey 前 16 字节) 进行 CBC 解密；
// 4. PKCS#7 剔除: 去除解密内容末尾的 PKCS#7 填充字节，得到 FullStr 二进制混合数据包；
// 5. 协议拆包 (FullStr 内存排布):
//    FullStr = random(16B) + msg_len(4B) + msg + appid
//    - random(16B): 0~16 字节为 16 字节随机串，起混淆与防重放作用，解密端跳过；
//    - msg_len(4B): 16~20 字节为 msg 长度，占 4 字节，采用网络字节序 (大端序 BigEndian)；
//    - msg (变长): 从第 20 字节开始截取 msgLen 长度，即公众号/事件的原始 XML 明文 (对应代码 xmlContent)；
//    - appid (变长): 20+msgLen 之后直至末尾的字符串，为接收方的 AppID (对应官方示例 from_appid)；
// 6. 平台校验: 验证 appIDFromMsg 是否与本第三方平台 AppID 一致，防止多租户/跨平台串包。
func (c *WXBizMsgCrypt) DecryptMsg(msgSignature, timestamp, nonce string, postData []byte) ([]byte, error) {
	// 步骤 1: 解析外层 XML，获取 Encrypt 密文
	var encMsg EncryptedXMLMsg
	if err := xml.Unmarshal(postData, &encMsg); err != nil {
		return nil, fmt.Errorf("unmarshal encrypted xml failed: %w", err)
	}

	// 步骤 2: 验证 SHA-1 安全签名（防篡改）
	if !c.VerifySignature(msgSignature, timestamp, nonce, encMsg.Encrypt) {
		return nil, errors.New("signature verification failed")
	}

	// 步骤 3.1: Base64 解码得到 AES 原始密文字节
	cipherBytes, err := base64.StdEncoding.DecodeString(encMsg.Encrypt)
	if err != nil {
		return nil, fmt.Errorf("base64 decode encrypt failed: %w", err)
	}

	block, err := aes.NewCipher(c.aesKey)
	if err != nil {
		return nil, fmt.Errorf("aes new cipher failed: %w", err)
	}

	if len(cipherBytes) < aes.BlockSize || len(cipherBytes)%aes.BlockSize != 0 {
		return nil, errors.New("cipher text length is invalid")
	}

	// 步骤 3.2: AES-256-CBC 解密
	// 微信官方规范约定: IV 取 AESKey 的前 16 个字节 (而不是另外传输随机 IV)
	iv := c.aesKey[:16]
	mode := cipher.NewCBCDecrypter(block, iv)
	plainBytes := make([]byte, len(cipherBytes))
	mode.CryptBlocks(plainBytes, cipherBytes)

	// 步骤 4: 剔除末尾 PKCS#7 填充字节，还原原始 FullStr 数据包
	plainBytes = pkcs7Unpad(plainBytes)
	if len(plainBytes) < 20 {
		return nil, errors.New("plain text length too short")
	}

	// 步骤 5: 拆解 FullStr 二进制封包
	// 官方结构: random(16B) + msg_len(4B) + msg + appid

	// 5.1 读取 4 字节的 msg_len (网络字节序 / 大端序 Big-Endian，对应官方示例中的 msg_len / xmlLength)
	msgLen := binary.BigEndian.Uint32(plainBytes[16:20])
	totalLen := len(plainBytes)
	if totalLen < 20+int(msgLen) {
		return nil, errors.New("invalid msg len in decrypted content")
	}

	// 5.2 截取真实业务明文 XML 报文 (对应官方文档中的 msg、官方 Java 示例的 xmlContent)
	xmlContent := plainBytes[20 : 20+msgLen]

	// 5.3 截取尾部携带的目标 AppID (对应官方示例中的 from_appid)
	appIDFromMsg := string(plainBytes[20+msgLen:])

	// 步骤 6: 校验 AppID 是否与当前配置一致，防止跨平台错推或串包攻击
	if c.appID != "" && appIDFromMsg != c.appID {
		return nil, fmt.Errorf("appID mismatch: expected %s, got %s", c.appID, appIDFromMsg)
	}

	return xmlContent, nil
}

// EncryptMsg 加密回复明文并组装成微信标准加密 XML
//
// 封包与加密逆过程 (与 DecryptMsg 镜像对称):
// 1. 生成 16 字节随机串 random(16B)，作为混淆盐；
// 2. 将回复明文长度 replyXML 转换为 4 字节网络字节序 (大端序 BigEndian)；
// 3. 组装 FullStr: random(16B) + msg_len(4B) + replyXML + appid；
// 4. PKCS#7 补位填充对齐；
// 5. AES-256-CBC 加密 (IV 固定为 AESKey 前 16 字节)；
// 6. Base64 编码并计算 SHA-1 签名，组装成带有 CDATA 的微信加密响应报文。
func (c *WXBizMsgCrypt) EncryptMsg(replyXML []byte, timestamp, nonce string) ([]byte, error) {
	// 步骤 1: 生成 16 字节安全随机字符串
	rand16 := make([]byte, 16)
	if _, err := io.ReadFull(rand.Reader, rand16); err != nil {
		return nil, fmt.Errorf("generate random bytes failed: %w", err)
	}

	// 步骤 2: 将明文长度转换为 4 字节网络字节序 (大端序)
	msgLenBytes := make([]byte, 4)
	binary.BigEndian.PutUint32(msgLenBytes, uint32(len(replyXML)))

	// 步骤 3: 拼装 FullStr = random(16B) + msg_len(4B) + replyXML + appID
	var rawBuf bytes.Buffer
	rawBuf.Write(rand16)
	rawBuf.Write(msgLenBytes)
	rawBuf.Write(replyXML)
	rawBuf.WriteString(c.appID)

	// 步骤 4: PKCS#7 补位填充
	padded := pkcs7Pad(rawBuf.Bytes(), aes.BlockSize)

	block, err := aes.NewCipher(c.aesKey)
	if err != nil {
		return nil, fmt.Errorf("aes new cipher failed: %w", err)
	}

	iv := c.aesKey[:16]
	mode := cipher.NewCBCEncrypter(block, iv)
	cipherText := make([]byte, len(padded))
	mode.CryptBlocks(cipherText, padded)

	encryptB64 := base64.StdEncoding.EncodeToString(cipherText)
	signature := CalcSignature(c.token, timestamp, nonce, encryptB64)

	res := ResponseXMLMsg{
		Encrypt:      CDATA{Value: encryptB64},
		MsgSignature: CDATA{Value: signature},
		TimeStamp:    timestamp,
		Nonce:        CDATA{Value: nonce},
	}

	return xml.MarshalIndent(res, "", "  ")
}

func pkcs7Pad(data []byte, blockSize int) []byte {
	padding := blockSize - len(data)%blockSize
	padText := bytes.Repeat([]byte{byte(padding)}, padding)
	return append(data, padText...)
}

func pkcs7Unpad(data []byte) []byte {
	length := len(data)
	if length == 0 {
		return nil
	}
	padding := int(data[length-1])
	if padding > length || padding > 32 || padding == 0 {
		return data
	}
	return data[:length-padding]
}

func (r *openPlatformRepository) SetVerifyTicket(ctx context.Context, platformAppID, ticket string, ttl time.Duration) error {
	// 1. 写入 Redis 缓存
	cacheErr := r.cache.SetVerifyTicket(ctx, platformAppID, ticket, ttl)

	// 2. 双写持久化到 MySQL，并记录绝对过期时间戳 (当前时间 + ttl)
	expiresAt := time.Now().Add(ttl).UnixMilli()
	_ = r.dao.SaveOrUpdateVerifyTicket(ctx, platformAppID, ticket, expiresAt)

	return cacheErr
}

func (c *openPlatformCache) SetVerifyTicket(ctx context.Context, platformAppID, ticket string, ttl time.Duration) error {
	key := fmt.Sprintf("scrm:open:ticket:%s", platformAppID)
	return c.redis.Set(ctx, key, ticket, ttl).Err()
}

func (d *openPlatformDAO) SaveOrUpdateVerifyTicket(ctx context.Context, appID, ticket string, expiresAt int64) error {
	now := time.Now().UnixMilli()
	return d.db.WithContext(ctx).Clauses(clause.OnConflict{
		Columns: []clause.Column{{Name: "app_id"}},
		DoUpdates: clause.Assignments(map[string]any{
			"component_verify_ticket": ticket,
			"ticket_expires_at":       expiresAt,
			"updated_at":              now,
		}),
	}).Create(&WxOpenPlatform{
		ID:                    uuid.NewV4().String(),
		AppID:                 appID,
		ComponentVerifyTicket: ticket,
		TicketExpiresAt:       expiresAt,
		CreatedAt:             now,
		UpdatedAt:             now,
	}).Error
}

func (s *openPlatformService) GetComponentAccessToken(ctx context.Context, platformAppID string) (string, error) {
	if platformAppID == "" {
		platformAppID = s.cfg.OpenPlatform.AppId
	}

	// 1. 先查缓存
	token, err := s.repo.GetComponentAccessToken(ctx, platformAppID)
	if err == nil && token != "" {
		return token, nil
	}

	// 2. singleflight 保护防击穿
	val, err, _ := s.sf.Do("component_token:"+platformAppID, func() (any, error) {
		token, err := s.repo.GetComponentAccessToken(ctx, platformAppID)
		if err == nil && token != "" {
			return token, nil
		}

		ticket, err := s.repo.GetVerifyTicket(ctx, platformAppID)
		if err != nil || ticket == "" {
			// 异步触发微信主动补发推送，不阻塞当前请求过长时间
			go func() {
				bgCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
				defer cancel()
				if pushErr := s.TriggerStartPushTicket(bgCtx, platformAppID); pushErr != nil {
					s.l.Warn("主动触发微信推送 component_verify_ticket 失败", zap.Error(pushErr), zap.String("platformAppID", platformAppID))
				} else {
					s.l.Info("已触发微信推送 component_verify_ticket 补发流程，等待微信异步推送...", zap.String("platformAppID", platformAppID))
				}
			}()
			return "", fmt.Errorf("开放平台验证票据未就绪，已触发微信推送补偿，请等待约1分钟后重试")
		}

		reqBody, _ := json.Marshal(map[string]string{
			"component_appid":         platformAppID,
			"component_appsecret":     s.cfg.OpenPlatform.AppSecret,
			"component_verify_ticket": ticket,
		})

		url := "https://api.weixin.qq.com/cgi-bin/component/api_component_token"
		resp, err := s.httpClient.Post(url, "application/json", bytes.NewReader(reqBody))
		if err != nil {
			return "", fmt.Errorf("request api_component_token failed: %w", err)
		}
		defer resp.Body.Close()

		body, err := io.ReadAll(resp.Body)
		if err != nil {
			return "", fmt.Errorf("read component token response failed: %w", err)
		}

		var res struct {
			ComponentAccessToken string `json:"component_access_token"`
			ExpiresIn            int    `json:"expires_in"`
			ErrCode              int    `json:"errcode"`
			ErrMsg               string `json:"errmsg"`
		}

		if err := json.Unmarshal(body, &res); err != nil {
			return "", fmt.Errorf("unmarshal component token response failed: %w", err)
		}

		if res.ErrCode != 0 || res.ComponentAccessToken == "" {
			return "", fmt.Errorf("wechat api_component_token error [%d]: %s", res.ErrCode, res.ErrMsg)
		}

		ttl := time.Duration(res.ExpiresIn-200) * time.Second
		if ttl <= 0 {
			ttl = 7000 * time.Second
		}

		_ = s.repo.SetComponentAccessToken(ctx, platformAppID, res.ComponentAccessToken, ttl)
		return res.ComponentAccessToken, nil
	})

	if err != nil {
		return "", err
	}
	return val.(string), nil
}

// TriggerStartPushTicket 向微信官方主动申请补发 component_verify_ticket
// 官方文档：https://developers.weixin.qq.com/doc/oplatform/openApi/ticket-token/api_startpushticket.html
func (s *openPlatformService) TriggerStartPushTicket(ctx context.Context) error {
	platformAppID := s.cfg.OpenPlatform.AppId
	appSecret := s.cfg.OpenPlatform.AppSecret
	if appSecret == "" {
		return errors.New("开放平台 AppSecret 未配置")
	}

	// 频率保护：单平台原子时间戳判断，1 分钟内限制调用一次 (防抖保护与限流拦截)
	nowMs := time.Now().UnixMilli()
	lastMs := s.lastPushTriggerMs.Load()
	if nowMs-lastMs < 60*1000 {
		s.l.Info("1分钟内已触发过微信推送补发，跳过本次请求",
			zap.String("platformAppID", platformAppID),
			zap.Int64("remainingCooldownMs", 60*1000-(nowMs-lastMs)),
		)
		return nil
	}

	reqBody, _ := json.Marshal(map[string]string{
		"component_appid":  platformAppID,
		"component_secret": appSecret,
	})

	url := "https://api.weixin.qq.com/cgi-bin/component/api_start_push_ticket"
	resp, err := s.httpClient.Post(url, "application/json", bytes.NewReader(reqBody))
	if err != nil {
		return fmt.Errorf("request api_start_push_ticket failed: %w", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return fmt.Errorf("read api_start_push_ticket response failed: %w", err)
	}

	var res struct {
		ErrCode int    `json:"errcode"`
		ErrMsg  string `json:"errmsg"`
	}
	if err := json.Unmarshal(body, &res); err != nil {
		return fmt.Errorf("unmarshal api_start_push_ticket response failed: %w", err)
	}

	if res.ErrCode != 0 {
		return fmt.Errorf("wechat api_start_push_ticket error [%d]: %s", res.ErrCode, res.ErrMsg)
	}

	s.lastPushTriggerMs.Store(time.Now().UnixMilli())
	s.l.Info("成功调用微信 api_start_push_ticket 申请补推 ticket", zap.String("platformAppID", platformAppID))
	return nil
}