# 微信公众号与微信支付集成使用指南

本文档说明如何配置和使用系统的微信公众号 OAuth 认证和微信支付功能。

## 目录

- [概述](#概述)
- [前置条件](#前置条件)
- [配置步骤](#配置步骤)
  - [1. 微信公众号配置](#1-微信公众号配置)
  - [2. 微信支付配置](#2-微信支付配置)
  - [3. 证书文件配置](#3-证书文件配置)
- [环境变量配置](#环境变量配置)
- [功能说明](#功能说明)
  - [微信 OAuth 登录](#微信-oauth-登录)
  - [微信 JSAPI 支付](#微信-jsapi-支付)
  - [微信 H5 支付](#微信-h5-支付)
  - [支付回调处理](#支付回调处理)
- [常见问题](#常见问题)

---

## 概述

系统集成了以下微信功能：

1. **微信公众号 OAuth 认证**：个人客户可以通过微信授权码登录/绑定账号
2. **微信 JSAPI 支付**：支持微信内网页支付
3. **微信 H5 支付**：支持微信外浏览器 H5 支付
4. **支付回调处理**：自动验证微信支付签名并处理回调

技术实现使用 [PowerWeChat v3 SDK](https://github.com/ArtisanCloud/PowerWeChat)。

---

## 前置条件

在开始配置之前，您需要：

1. **微信公众号**（已认证）
   - 公众号 AppID
   - 公众号 AppSecret
   - OAuth 回调域名（需在公众号后台配置）

2. **微信商户号**（已开通）
   - 商户号 MchID
   - APIv3 密钥（32位字符串）
   - APIv2 密钥（可选，部分接口需要）
   - 商户证书（apiclient_cert.pem）
   - 商户私钥（apiclient_key.pem）
   - 证书序列号

3. **服务器环境**
   - 可访问的 HTTPS 域名（用于接收微信回调）
   - Redis（用于缓存 AccessToken）

---

## 配置步骤

### 1. 微信公众号配置

#### 1.1 获取 AppID 和 AppSecret

登录 [微信公众平台](https://mp.weixin.qq.com/)，在"开发" → "基本配置"中获取：

- AppID（应用ID）
- AppSecret（应用密钥）

#### 1.2 配置 OAuth 回调域名

在"设置与开发" → "公众号设置" → "功能设置" → "网页授权域名"中配置：

```
your-domain.com
```

**注意**：
- 不要带 `http://` 或 `https://`
- 不要带端口号
- 需要验证域名所有权（下载验证文件到网站根目录）

### 2. 微信支付配置

#### 2.1 获取商户信息

登录 [微信支付商户平台](https://pay.weixin.qq.com/)：

1. **商户号（MchID）**：在"账户中心" → "商户信息"中查看
2. **APIv3 密钥**：在"账户中心" → "API安全" → "设置APIv3密钥"中设置（32位字符串）
3. **APIv2 密钥**：（可选）同上，设置API密钥（32位字符串）

#### 2.2 下载商户证书

在"账户中心" → "API安全" → "申请API证书"：

1. 下载证书工具
2. 生成证书请求文件
3. 上传请求文件
4. 下载证书文件：
   - `apiclient_cert.pem`（商户证书）
   - `apiclient_key.pem`（商户私钥）

#### 2.3 获取证书序列号

**方法1：使用 OpenSSL**
```bash
openssl x509 -in apiclient_cert.pem -noout -serial | cut -d= -f2
```

**方法2：从商户平台查看**
在"账户中心" → "API安全" → "API证书"中查看证书序列号。

#### 2.4 配置支付回调 URL

在"产品中心" → "开发配置" → "支付配置"中设置：

```
https://your-domain.com/api/callback/wechat-pay
```

**注意**：
- 必须使用 HTTPS
- 确保服务器可以接收微信的 POST 请求

### 3. 证书文件配置

将下载的证书文件放置到服务器：

```bash
# 创建证书目录
mkdir -p /app/certs

# 复制证书文件
cp apiclient_cert.pem /app/certs/
cp apiclient_key.pem /app/certs/

# 设置文件权限（仅所有者可读写）
chmod 600 /app/certs/*
```

**Docker 部署**：在 `docker-compose.yml` 中挂载证书目录：

```yaml
services:
  api:
    volumes:
      - ./certs:/app/certs:ro  # 只读挂载
```

---

## 环境变量配置

在 `.env.local` 或生产环境中设置以下环境变量：

```bash
# ===== 微信公众号配置 =====
export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID="wxabcdef1234567890"
export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET="your_app_secret_here"
export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN=""                    # 可选，服务器配置用
export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY=""                 # 可选，消息加解密用
export JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL=""      # 可选，自定义回调URL

# ===== 微信支付配置 =====
export JUNHONG_WECHAT_PAYMENT_APP_ID="wxabcdef1234567890"         # 与公众号 AppID 相同
export JUNHONG_WECHAT_PAYMENT_MCH_ID="1234567890"
export JUNHONG_WECHAT_PAYMENT_API_V3_KEY="your_apiv3_key_32_chars_here"
export JUNHONG_WECHAT_PAYMENT_API_V2_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="1234567890ABCDEF"
export JUNHONG_WECHAT_PAYMENT_NOTIFY_URL="https://your-domain.com/api/callback/wechat-pay"
export JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG=false
export JUNHONG_WECHAT_PAYMENT_TIMEOUT="30s"
```

**配置说明**：

| 配置项 | 必填 | 说明 |
|--------|------|------|
| `OFFICIAL_ACCOUNT_APP_ID` | ✅ | 公众号 AppID |
| `OFFICIAL_ACCOUNT_APP_SECRET` | ✅ | 公众号 AppSecret |
| `PAYMENT_APP_ID` | ✅ | 支付 AppID（通常与公众号相同） |
| `PAYMENT_MCH_ID` | ✅ | 商户号 |
| `PAYMENT_API_V3_KEY` | ✅ | APIv3 密钥（32位） |
| `PAYMENT_CERT_PATH` | ✅ | 商户证书路径 |
| `PAYMENT_KEY_PATH` | ✅ | 商户私钥路径 |
| `PAYMENT_SERIAL_NO` | ✅ | 证书序列号 |
| `PAYMENT_NOTIFY_URL` | ✅ | 支付回调 URL |
| `PAYMENT_TIMEOUT` | ❌ | HTTP 请求超时（默认30s） |
| `PAYMENT_HTTP_DEBUG` | ❌ | 开启 HTTP 调试日志 |

---

## 功能说明

### 微信 OAuth 登录

#### 业务流程

```
1. 前端引导用户点击"微信登录"
2. 跳转到微信授权页面（微信SDK处理）
3. 用户同意授权后，微信回调到前端
4. 前端获取授权码（code），调用后端登录接口
5. 后端通过 code 获取用户 OpenID/UnionID
6. 后端创建/查找用户，返回 JWT Token
```

#### API 端点

**POST `/api/c/v1/wechat/auth`**

请求体：
```json
{
  "code": "071abc123456789def"
}
```

响应：
```json
{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "customer_id": 123,
    "phone": "138****8888",
    "nickname": "微信用户",
    "is_new_user": false
  },
  "timestamp": "2025-01-30T12:00:00Z"
}
```

#### 前端集成示例

```javascript
// 1. 构造微信授权 URL（前端处理）
const redirectUri = encodeURIComponent('https://your-domain.com/wechat-callback');
const appId = 'wxabcdef1234567890';
const scope = 'snsapi_userinfo';  // 或 snsapi_base（静默授权）
const state = 'STATE';  // 自定义参数

const authUrl = `https://open.weixin.qq.com/connect/oauth2/authorize?appid=${appId}&redirect_uri=${redirectUri}&response_type=code&scope=${scope}&state=${state}#wechat_redirect`;

// 跳转到微信授权页面
window.location.href = authUrl;

// 2. 在回调页面获取 code 并调用后端
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');

fetch('https://api.your-domain.com/api/c/v1/wechat/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code })
})
.then(res => res.json())
.then(data => {
  if (data.code === 0) {
    localStorage.setItem('token', data.data.token);
    // 跳转到主页
  }
});
```

### 微信 JSAPI 支付

#### 业务流程

```
1. 前端调用后端创建支付订单
2. 后端调用微信支付接口，获取 prepay_id 和支付配置
3. 前端调用微信 JSAPI 唤起支付
4. 用户完成支付后，微信回调后端通知接口
5. 后端验证签名并处理订单状态
```

#### API 端点

**POST `/api/h5/orders/:id/wechat-pay/jsapi`**

请求体：
```json
{
  "open_id": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M"
}
```

响应：
```json
{
  "code": 0,
  "msg": "支付订单创建成功",
  "data": {
    "prepay_id": "wx30123456789012345678901234567890",
    "pay_config": {
      "appId": "wxabcdef1234567890",
      "timeStamp": "1706606400",
      "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
      "package": "prepay_id=wx30123456789012345678901234567890",
      "signType": "RSA",
      "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd..."
    }
  },
  "timestamp": "2025-01-30T12:00:00Z"
}
```

#### 前端集成示例（微信内网页）

```javascript
// 1. 调用后端创建支付订单
const response = await fetch(`/api/h5/orders/${orderId}/wechat-pay/jsapi`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    open_id: 'o6_bmjrPTlm6_2sgVt7hMZOPfL2M'
  })
});

const result = await response.json();

// 2. 调用微信 JSAPI 唤起支付
if (result.code === 0) {
  const payConfig = result.data.pay_config;
  
  wx.chooseWXPay({
    ...payConfig,
    success: function(res) {
      // 支付成功，跳转到订单详情页
      window.location.href = `/orders/${orderId}`;
    },
    fail: function(res) {
      // 支付失败
      alert('支付失败：' + res.err_msg);
    }
  });
}
```

### 微信 H5 支付

#### 业务流程

```
1. 前端调用后端创建 H5 支付订单
2. 后端调用微信支付接口，获取 H5 支付 URL
3. 前端跳转到 H5 支付 URL
4. 用户完成支付后，微信回调后端通知接口
5. 后端验证签名并处理订单状态
```

#### API 端点

**POST `/api/h5/orders/:id/wechat-pay/h5`**

请求体：
```json
{
  "scene_info": {
    "payer_client_ip": "123.12.12.123",
    "h5_type": "Wap"
  }
}
```

响应：
```json
{
  "code": 0,
  "msg": "H5 支付订单创建成功",
  "data": {
    "h5_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx..."
  },
  "timestamp": "2025-01-30T12:00:00Z"
}
```

#### 前端集成示例（浏览器）

```javascript
// 1. 调用后端创建 H5 支付订单
const response = await fetch(`/api/h5/orders/${orderId}/wechat-pay/h5`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    scene_info: {
      payer_client_ip: '123.12.12.123',
      h5_type: 'Wap'
    }
  })
});

const result = await response.json();

// 2. 跳转到微信 H5 支付页面
if (result.code === 0) {
  const returnUrl = encodeURIComponent(`https://your-domain.com/orders/${orderId}`);
  window.location.href = `${result.data.h5_url}&redirect_url=${returnUrl}`;
}
```

### 支付回调处理

#### 回调端点

**POST `/api/callback/wechat-pay`**

该端点接收微信支付的异步通知。系统会自动：

1. 验证微信签名（使用商户证书）
2. 解密通知数据
3. 更新订单状态
4. 处理业务逻辑（分佣、钱包充值等）
5. 返回成功响应给微信

#### 回调处理流程

```
1. 微信发送 POST 请求到回调 URL
2. 系统验证请求签名（PowerWeChat 自动处理）
3. 解析支付结果（交易状态、金额等）
4. 更新订单状态为"已支付"
5. 触发异步任务（分佣计算、套餐分配等）
6. 返回 200 OK 给微信（表示接收成功）
```

**注意**：
- 回调接口必须在 **10秒内** 返回响应，否则微信会重试
- 系统已实现幂等性处理，重复通知不会重复处理
- 如果处理失败，微信会重试多次（最多3次）

---

## 常见问题

### 1. 配置验证失败，服务启动失败

**错误日志**：
```
FATAL: 微信配置不完整或无效
```

**解决方法**：
- 检查所有必填环境变量是否设置
- 确认证书文件路径正确且文件存在
- 验证 APIv3 密钥是否为 32 位字符串

### 2. OAuth 授权失败，返回 1044 错误

**错误消息**：
```json
{
  "code": 1044,
  "msg": "微信 OAuth 授权失败"
}
```

**可能原因**：
- 授权码（code）已过期（5分钟有效期）
- 授权码已被使用过（一次性有效）
- AppID 或 AppSecret 配置错误
- 回调域名未在公众号后台配置

**解决方法**：
- 重新发起授权流程获取新 code
- 检查公众号配置是否正确
- 查看 `logs/app.log` 获取详细错误信息

### 3. 支付订单创建失败，返回 1046 错误

**错误消息**：
```json
{
  "code": 1046,
  "msg": "微信支付失败"
}
```

**可能原因**：
- 商户号配置错误
- 证书文件无效或过期
- APIv3 密钥错误
- 订单金额为0或负数

**解决方法**：
- 验证商户号和密钥是否正确
- 检查证书文件是否可读（权限问题）
- 确认证书序列号是否匹配
- 查看 `logs/app.log` 获取详细错误信息

### 4. 支付回调签名验证失败

**错误日志**：
```
ERROR: 支付回调签名验证失败
```

**可能原因**：
- 证书配置错误
- 证书序列号不匹配
- 证书已过期

**解决方法**：
- 重新下载最新的商户证书
- 更新证书序列号配置
- 确保证书文件路径正确

### 5. 如何测试微信支付？

**开发环境测试**：
1. 使用微信测试号（公众号测试账号）
2. 使用真实商户号的沙箱环境（需申请）
3. 使用 0.01 元测试订单（生产环境）

**注意**：
- 测试订单需要真实支付
- 可以通过退款功能退回测试金额
- 建议使用沙箱环境进行测试

### 6. Redis 连接失败，影响微信功能吗？

**是的**，微信功能依赖 Redis 缓存 AccessToken。

**解决方法**：
- 确保 Redis 服务正常运行
- 检查 Redis 连接配置（地址、端口、密码）
- 查看 `logs/app.log` 获取 Redis 连接错误

### 7. 如何调试微信支付问题？

**启用 HTTP 调试日志**：
```bash
export JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG=true
```

重启服务后，所有微信 API 请求和响应将记录到 `logs/app.log`。

**查看日志**：
```bash
tail -f logs/app.log | grep -i wechat
```

---

## 相关文档

- [微信公众号官方文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)
- [微信支付官方文档](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)
- [PowerWeChat SDK 文档](https://github.com/ArtisanCloud/PowerWeChat)
- [API 文档](./API文档.md)
- [环境变量配置](../environment-variables.md)