junhong_cmp_fiber/openspec/changes/archive/2026-01-30-wechat-official-account-payment-integration/design.md

微信公众号与微信支付集成 - 技术设计

Context

当前系统已具备完整的个人客户体系（JWT 认证、手机号登录）和订单支付系统（订单模型、钱包支付、支付回调幂等处理），但缺少微信公众号和微信支付的真实 SDK 集成。

现有基础设施：

• ✅ 数据模型：tb_personal_customer 包含 wx_open_id、wx_union_id 字段（已建索引）
• ✅ 接口定义：pkg/wechat/wechat.go 定义了 Service 接口（当前为 Mock 实现）
• ✅ 支付回调：POST /api/callback/wechat-pay 已预留（基础参数验证，缺签名校验）
• ✅ 订单系统：完整的订单创建、支付状态更新、套餐激活流程（幂等设计）

集成目标：

• 使用 PowerWeChat v3 SDK 对接微信公众号和微信支付 API
• 支持个人客户通过微信 OAuth 登录/绑定
• 支持两种支付场景：JSAPI 支付（微信内）、H5 支付（浏览器）
• 补充支付回调的签名验证（PowerWeChat 自动处理）

Goals / Non-Goals

Goals:

1. 实现微信公众号 OAuth 2.0 授权流程，获取用户 OpenID/UnionID 和基本信息
2. 实现 H5 支付和 JSAPI 支付的订单创建和支付参数生成
3. 补充支付回调的签名验证，确保回调来源合法
4. 集成 Redis 缓存实现微信 Access Token 中控（多实例共享）
5. 配置管理遵循项目规范（Viper + 环境变量）
6. 完整的错误处理和日志记录

Non-Goals:

• 不实现微信模板消息、客服消息等公众号其他能力（按需后续扩展）
• 不实现微信 Native 支付（扫码支付）和 App 支付（当前无此场景）
• 不修改现有订单模型和支付流程（在现有基础上扩展）
• 不实现微信退款功能（后续单独实现）

Decisions

决策 1：SDK 选型 - PowerWeChat v3

选择理由：

• ✅ 官方文档推荐，Go 生态成熟度高
• ✅ 支持所有公众号和支付 API（包括 H5、JSAPI、Native、App 支付）
• ✅ 内置签名验证、Token 中控、日志集成
• ✅ 支持 Redis 缓存（与项目现有 Redis 无缝集成）
• ✅ 活跃维护，GitHub 2.5k+ stars

替代方案：

• silenceper/wechat：功能相似，但文档较少，社区活跃度较低
• 自行封装微信 API：工作量大，维护成本高，签名验证易出错

决策 2：架构设计 - 遵循项目分层

┌─────────────────────────────────────────────────────────────┐
│  pkg/wechat/                                                │
│  ├─ service.go          微信服务接口定义                     │
│  ├─ official_account.go OfficialAccount 实现（OAuth）        │
│  ├─ payment.go          Payment 实现（H5/JSAPI 支付）       │
│  └─ config.go           PowerWeChat 实例初始化              │
└─────────────────────────────────────────────────────────────┘
         ↓ 依赖注入
┌─────────────────────────────────────────────────────────────┐
│  internal/service/                                          │
│  ├─ personal_customer/service.go  调用 wechat.Service       │
│  └─ order/service.go              调用 wechat.Payment       │
└─────────────────────────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────────────────────────┐
│  internal/handler/                                          │
│  ├─ app/personal_customer.go   OAuth 登录端点              │
│  ├─ h5/order.go                 支付发起端点                │
│  └─ callback/payment.go         支付回调端点                │
└─────────────────────────────────────────────────────────────┘

依赖注入方式：

• pkg/wechat.Service 在 internal/bootstrap/services.go 中初始化
• 注入到 PersonalCustomerService 和 OrderService
• Handler 通过 Service 调用微信能力

选择理由：

• ✅ 符合项目 Handler → Service → Store → Model 分层
• ✅ pkg/wechat/ 作为基础设施层，独立于业务逻辑
• ✅ 通过接口隔离，便于测试（Mock 实现）

决策 3：配置管理 - Viper + 环境变量

配置结构：

wechat:
  official_account:
    app_id: ""           # JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID
    app_secret: ""       # JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET
    token: ""            # JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN
    aes_key: ""          # JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY
    oauth_redirect_url: ""  # JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL
  
  payment:
    app_id: ""           # JUNHONG_WECHAT_PAYMENT_APP_ID
    mch_id: ""           # JUNHONG_WECHAT_PAYMENT_MCH_ID
    api_v3_key: ""       # JUNHONG_WECHAT_PAYMENT_API_V3_KEY
    api_v2_key: ""       # JUNHONG_WECHAT_PAYMENT_API_V2_KEY
    cert_path: ""        # JUNHONG_WECHAT_PAYMENT_CERT_PATH
    key_path: ""         # JUNHONG_WECHAT_PAYMENT_KEY_PATH
    serial_no: ""        # JUNHONG_WECHAT_PAYMENT_SERIAL_NO
    notify_url: ""       # JUNHONG_WECHAT_PAYMENT_NOTIFY_URL

选择理由：

• ✅ 遵循项目现有配置管理模式
• ✅ 敏感信息通过环境变量覆盖，不提交代码库
• ✅ Docker 部署无需挂载配置文件

证书管理：

• 证书文件路径通过环境变量配置（如 /app/certs/apiclient_cert.pem）
• Docker 部署时通过 Volume 挂载证书目录
• 启动时验证证书文件存在性，缺失则报错退出

决策 4：支付场景识别 - 客户端传参

// JSAPI 支付请求
type WechatPayJSAPIRequest struct {
    OpenID string `json:"openid" validate:"required"`  // 用户 OpenID
}

// H5 支付请求
type WechatPayH5Request struct {
    SceneInfo WechatH5SceneInfo `json:"scene_info"`
}

type WechatH5SceneInfo struct {
    PayerClientIP string `json:"payer_client_ip" validate:"required"` // 用户终端 IP
    H5Info        struct {
        Type string `json:"type"` // 场景类型（iOS, Android, Wap）
    } `json:"h5_info"`
}

选择理由：

• ✅ 不在后端判断场景（User-Agent 不可靠）
• ✅ 前端明确调用对应端点：
  • /api/h5/orders/:id/wechat-pay/jsapi（微信内）
  • /api/h5/orders/:id/wechat-pay/h5（浏览器）

决策 5：支付回调处理 - 补充签名验证

现有实现：

// internal/handler/callback/payment.go
func (h *PaymentHandler) WechatPayCallback(c *fiber.Ctx) error {
    var req WechatPayCallbackRequest
    if err := c.BodyParser(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
    }
    
    // 调用 Service 处理支付（已实现幂等）
    if err := h.orderService.HandlePaymentCallback(ctx, req.OrderNo, model.PaymentMethodWechat); err != nil {
        return err
    }
    
    return response.Success(c, map[string]string{"return_code": "SUCCESS"})
}

增强设计：

func (h *PaymentHandler) WechatPayCallback(c *fiber.Ctx) error {
    // 1. PowerWeChat 自动处理签名验证
    res, err := h.wechatPayment.HandlePaidNotify(
        c.Request(),
        func(message *request.RequestNotify, transaction *models.Transaction, fail func(string)) interface{} {
            // 2. 检查事件类型
            if message.EventType != "TRANSACTION.SUCCESS" {
                return true
            }
            
            // 3. 调用现有 Service（幂等处理）
            orderNo := *transaction.OutTradeNo
            err := h.orderService.HandlePaymentCallback(ctx, orderNo, model.PaymentMethodWechat)
            if err != nil {
                fail("payment processing failed")
                return nil
            }
            
            return true
        },
    )
    
    // 4. PowerWeChat 自动回复微信
    return res.Write(c.Writer)
}

选择理由：

• ✅ PowerWeChat 自动验证签名（无需手动实现复杂的验签逻辑）
• ✅ 保留现有 HandlePaymentCallback 的幂等设计
• ✅ 统一错误处理和日志记录

决策 6：Token 中控 - Redis 缓存

实现方式：

import "github.com/ArtisanCloud/PowerWeChat/v3/src/kernel"

cache := kernel.NewRedisClient(&kernel.UniversalOptions{
    Addrs:    []string{config.Redis.Address},
    Password: config.Redis.Password,
    DB:       config.Redis.DB,
})

officialAccountApp, err := officialAccount.NewOfficialAccount(&officialAccount.UserConfig{
    AppID:  config.Wechat.OfficialAccount.AppID,
    Secret: config.Wechat.OfficialAccount.AppSecret,
    Cache:  cache,  // 共享 Redis 实例
})

Cache Key 格式：

powerwechat.access_token.{MD5(appid+secret)}

选择理由：

• ✅ 多实例共享 Access Token，避免重复获取（每日限额 2000 次）
• ✅ 使用项目现有 Redis 实例，无需额外部署
• ✅ Token 过期自动刷新（PowerWeChat 内置处理）

决策 7：错误处理 - 统一错误码

新增错误码（pkg/errors/codes.go）：

// 微信相关错误码（1040-1049）
CodeWechatOAuthFailed     = 1040  // 微信 OAuth 授权失败
CodeWechatUserInfoFailed  = 1041  // 获取微信用户信息失败
CodeWechatPayFailed       = 1042  // 微信支付发起失败
CodeWechatCallbackInvalid = 1043  // 微信回调签名验证失败

错误消息格式：

return errors.Wrap(CodeWechatOAuthFailed, err, "微信授权失败，请重试")

选择理由：

• ✅ 符合项目错误处理规范（pkg/errors/）
• ✅ 客户端可根据错误码区分微信相关错误
• ✅ 敏感信息不对外暴露（详细错误写日志）

Risks / Trade-offs

风险 1：微信 API 调用失败

场景：网络超时、微信服务异常、配置错误

缓解措施：

• 设置合理的 HTTP 超时（30 秒）
• 记录完整的请求/响应日志（HttpDebug: true 在测试环境）
• 错误消息包含 Request ID 便于排查
• 支付失败时订单状态保持 pending，用户可重试

风险 2：证书文件管理

场景：证书过期、文件路径错误、权限问题

缓解措施：

• 启动时验证证书文件可读性，不通过则退出
• 证书序列号配置错误时 PowerWeChat 会报错
• 文档中说明证书获取和更新流程
• 使用 Docker Secrets 或 Volume 挂载证书（避免镜像包含证书）

风险 3：支付回调重复通知

场景：微信可能多次发送同一支付成功通知

缓解措施：

• ✅ 现有 HandlePaymentCallback 已实现幂等（条件更新：WHERE id = ? AND payment_status = ?）
• ✅ 已支付订单返回成功，不报错
• 无需额外处理

风险 4：Access Token 缓存失效

场景：Redis 重启、缓存过期、网络问题

缓解措施：

• PowerWeChat 自动重新获取 Token（失败时重试）
• Redis 持久化配置确保重启后数据不丢失
• Token 获取失败记录错误日志

权衡 1：配置复杂度 vs 安全性

权衡：微信支付需要大量配置项（AppID、商户号、密钥、证书等）

决策：优先保证安全性

• 敏感信息全部通过环境变量配置
• 证书文件路径可配置，不硬编码
• 提供完整的配置文档和示例

权衡 2：功能完整性 vs 实现成本

权衡：微信支付支持多种场景（Native、App、小程序等）

决策：仅实现当前需求（H5 + JSAPI）

• Native、App 支付后续按需扩展
• 架构设计预留扩展性（新增支付类型只需加端点）

Migration Plan

部署步骤

1. 配置环境变量

   export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID="wx..."
   export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET="..."
   export JUNHONG_WECHAT_PAYMENT_MCH_ID="..."
   export JUNHONG_WECHAT_PAYMENT_API_V3_KEY="..."
   export JUNHONG_WECHAT_PAYMENT_CERT_PATH="/app/certs/apiclient_cert.pem"
   export JUNHONG_WECHAT_PAYMENT_KEY_PATH="/app/certs/apiclient_key.pem"
   export JUNHONG_WECHAT_PAYMENT_SERIAL_NO="..."
   export JUNHONG_WECHAT_PAYMENT_NOTIFY_URL="https://api.example.com/api/callback/wechat-pay"
   

2. 挂载证书文件（Docker）

   volumes:
     - ./wechat-certs:/app/certs:ro
   

3. 验证配置

   • 启动服务，检查日志无配置错误
   • 调用健康检查端点（可选：新增 /api/health/wechat 验证微信 API 可达性）

4. 微信后台配置

   • 公众号后台：设置 OAuth 回调域名
   • 商户平台：设置支付回调 URL 白名单

5. 灰度测试

   • 小范围用户测试微信登录和支付
   • 验证支付回调正常触发

回滚策略

• 配置错误：修改环境变量重启即可
• 功能异常：移除微信支付选项，用户使用钱包支付
• 数据库：无数据库变更，无需回滚

监控指标

• 微信 OAuth 成功率/失败率
• 支付发起成功率/失败率
• 支付回调接收数量/验证失败数量
• Access Token 获取次数（监控是否频繁刷新）

Open Questions

1. 证书更新流程：商户证书每年需更新，是否需要热加载机制？

   • 暂定：手动更新证书文件后重启服务（证书过期前提前通知）

2. 微信用户信息更新：用户在微信更新昵称/头像后，系统如何同步？

   • 暂定：每次 OAuth 登录时更新用户信息
   • 后续可考虑定期同步任务

3. 支付超时处理：订单创建后 30 分钟未支付，是否自动关闭？

   • 暂定：前端超时提示用户，后端暂不自动关闭
   • 后续可使用 Asynq 延迟任务实现自动关闭

4. 测试环境配置：如何在测试环境使用微信沙盒？

   • PowerWeChat 支持沙盒环境（配置 Http.BaseURI 为沙盒地址）
   • 需要微信商户平台申请沙盒权限