csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

微信相关能力

Browse Source
This commit is contained in:
huang
2026-01-30 17:25:30 +08:00
parent 4856a88d41
commit bf591095a2
43 changed files with 4297 additions and 391 deletions
Download Patch File Download Diff File Expand all files Collapse all files

562
docs/wechat-integration/使用指南.md Normal file
View File

@@ -0,0 +1,562 @@
# 微信公众号与微信支付集成使用指南
本文档说明如何配置和使用系统的微信公众号 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)