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

## 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 + 环境变量

**配置结构**：
```yaml
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：支付场景识别 - 客户端传参

```go
// 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：支付回调处理 - 补充签名验证

**现有实现**：
```go
// 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"})
}
```

**增强设计**：
```go
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 缓存

**实现方式**：
```go
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`）：
```go
// 微信相关错误码（1040-1049）
CodeWechatOAuthFailed     = 1040  // 微信 OAuth 授权失败
CodeWechatUserInfoFailed  = 1041  // 获取微信用户信息失败
CodeWechatPayFailed       = 1042  // 微信支付发起失败
CodeWechatCallbackInvalid = 1043  // 微信回调签名验证失败
```

**错误消息格式**：
```go
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. **配置环境变量**
   ```bash
   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）
   ```yaml
   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` 为沙盒地址）
   - 需要微信商户平台申请沙盒权限