640 lines
17 KiB
Markdown
640 lines
17 KiB
Markdown
# 微信小程序支付功能上线配置修改清单
|
||
|
||
## 文档说明
|
||
|
||
**文档版本：** v1.0
|
||
**创建日期：** 2025年9月30日
|
||
**适用项目：** xiaozhi-server 微信小程序支付功能
|
||
**执行优先级：** 🔴 高优先级（上线前必须完成）
|
||
|
||
> ⚠️ **重要提醒：** 本文档包含生产环境配置信息，请严格按照公司信息安全规范执行，确保敏感信息不被泄露。
|
||
|
||
---
|
||
|
||
## 1. 测试环境与正式环境差异对比
|
||
|
||
### 1.1 环境配置差异表
|
||
|
||
| 配置项 | 测试环境 | 正式环境 | 修改优先级 |
|
||
|--------|----------|----------|------------|
|
||
| 服务器地址 | localhost:8091 | https://api.xiaozhi.com | 🔴 高 |
|
||
| 数据库环境 | 本地MySQL | 生产MySQL集群 | 🔴 高 |
|
||
| 微信支付环境 | 沙箱环境 | 正式环境 | 🔴 高 |
|
||
| 日志级别 | DEBUG | INFO/WARN | 🟡 中 |
|
||
| 缓存配置 | 本地Redis | Redis集群 | 🔴 高 |
|
||
| SSL证书 | 自签名证书 | 正式SSL证书 | 🔴 高 |
|
||
|
||
### 1.2 配置文件修改位置
|
||
|
||
**主要配置文件：**
|
||
- `src/main/resources/application.yml` - 主配置文件
|
||
- `src/main/resources/application-prod.yml` - 生产环境配置
|
||
- `src/main/java/com/xiaozhi/plus/utils/api/WxMpApi.java` - 微信API配置
|
||
|
||
---
|
||
|
||
## 2. API接口地址和密钥替换清单
|
||
|
||
### 2.1 微信支付API接口地址
|
||
|
||
**需要修改的配置项：**
|
||
|
||
```yaml
|
||
# application-prod.yml
|
||
wechat:
|
||
pay:
|
||
# 测试环境 -> 正式环境
|
||
api-url:
|
||
old: "https://api.mch.weixin.qq.com/sandboxnew" # 测试环境
|
||
new: "https://api.mch.weixin.qq.com" # 正式环境
|
||
|
||
# 统一下单接口
|
||
unifiedorder-url:
|
||
old: "https://api.mch.weixin.qq.com/sandboxnew/pay/unifiedorder"
|
||
new: "https://api.mch.weixin.qq.com/pay/unifiedorder"
|
||
|
||
# 订单查询接口
|
||
orderquery-url:
|
||
old: "https://api.mch.weixin.qq.com/sandboxnew/pay/orderquery"
|
||
new: "https://api.mch.weixin.qq.com/pay/orderquery"
|
||
```
|
||
|
||
### 2.2 密钥配置更新
|
||
|
||
**⚠️ 敏感信息 - 需要从运维团队获取正式密钥**
|
||
|
||
```yaml
|
||
# 需要替换的密钥配置
|
||
wechat:
|
||
pay:
|
||
# 商户密钥（32位）
|
||
mch-key:
|
||
old: "test_mch_key_32_characters_long" # 测试密钥
|
||
new: "${WECHAT_MCH_KEY}" # 生产密钥（环境变量）
|
||
|
||
# API密钥（32位）
|
||
api-key:
|
||
old: "test_api_key_32_characters_long" # 测试密钥
|
||
new: "${WECHAT_API_KEY}" # 生产密钥（环境变量）
|
||
```
|
||
|
||
### 2.3 修改执行步骤
|
||
|
||
1. **备份当前配置文件**
|
||
```bash
|
||
cp src/main/resources/application.yml src/main/resources/application.yml.backup
|
||
```
|
||
|
||
2. **更新配置文件**
|
||
- 修改 `application-prod.yml` 中的API地址
|
||
- 配置生产环境密钥（使用环境变量）
|
||
|
||
3. **验证配置**
|
||
- 确认所有URL指向正式环境
|
||
- 验证密钥格式正确（32位字符串）
|
||
|
||
---
|
||
|
||
## 3. 支付回调URL更新要求
|
||
|
||
### 3.1 回调URL配置
|
||
|
||
**当前测试环境回调URL：**
|
||
```
|
||
http://localhost:8091/api/wechat/pay/notify
|
||
```
|
||
|
||
**正式环境回调URL：**
|
||
```
|
||
https://api.xiaozhi.com/api/wechat/pay/notify
|
||
```
|
||
|
||
### 3.2 回调URL安全要求
|
||
|
||
1. **HTTPS协议要求**
|
||
- ✅ 必须使用HTTPS协议
|
||
- ✅ SSL证书必须有效
|
||
- ✅ 支持TLS 1.2及以上版本
|
||
|
||
2. **域名要求**
|
||
- ✅ 使用已备案的正式域名
|
||
- ✅ 域名必须与微信商户平台配置一致
|
||
- ❌ 不能使用IP地址
|
||
|
||
3. **端口要求**
|
||
- ✅ 使用标准HTTPS端口（443）
|
||
- ❌ 不使用自定义端口
|
||
|
||
### 3.3 微信商户平台配置
|
||
|
||
**配置路径：** 微信商户平台 → 产品中心 → 开发配置 → 支付配置
|
||
|
||
**需要配置的回调URL：**
|
||
- **支付结果通知URL：** `https://api.xiaozhi.com/api/wechat/pay/notify`
|
||
- **退款结果通知URL：** `https://api.xiaozhi.com/api/wechat/pay/refund/notify`
|
||
|
||
---
|
||
|
||
## 4. 商户号、AppID等敏感信息变更清单
|
||
|
||
### 4.1 微信小程序信息
|
||
|
||
| 配置项 | 测试环境值 | 正式环境值 | 获取方式 |
|
||
|--------|------------|------------|----------|
|
||
| **AppID** | `wxff56c34ef9aceb62` | `wx[16位正式AppID]` | 微信公众平台 |
|
||
| **AppSecret** | `f2c900d3296ce82a91dbc46de56a9fc3` | `[32位正式AppSecret]` | 微信公众平台 |
|
||
|
||
### 4.2 微信支付商户信息
|
||
|
||
| 配置项 | 测试环境值 | 正式环境值 | 获取方式 |
|
||
|--------|------------|------------|----------|
|
||
| **商户号(mch_id)** | `1234567890` | `[10位正式商户号]` | 微信商户平台 |
|
||
| **商户密钥(mch_key)** | `test_key_32_chars` | `[32位正式密钥]` | 微信商户平台 |
|
||
| **子商户号(sub_mch_id)** | 无 | `[如有子商户]` | 微信商户平台 |
|
||
|
||
### 4.3 配置文件更新示例
|
||
|
||
```yaml
|
||
# application-prod.yml
|
||
wechat:
|
||
mp:
|
||
appid: ${WECHAT_APPID} # 从环境变量读取
|
||
secret: ${WECHAT_APPSECRET} # 从环境变量读取
|
||
|
||
pay:
|
||
mch-id: ${WECHAT_MCH_ID} # 商户号
|
||
mch-key: ${WECHAT_MCH_KEY} # 商户密钥
|
||
app-id: ${WECHAT_APPID} # 应用ID
|
||
notify-url: "https://api.xiaozhi.com/api/wechat/pay/notify"
|
||
```
|
||
|
||
### 4.4 环境变量配置
|
||
|
||
**生产服务器需要设置的环境变量：**
|
||
```bash
|
||
# 微信小程序配置
|
||
export WECHAT_APPID="wx[正式AppID]"
|
||
export WECHAT_APPSECRET="[正式AppSecret]"
|
||
|
||
# 微信支付配置
|
||
export WECHAT_MCH_ID="[正式商户号]"
|
||
export WECHAT_MCH_KEY="[正式商户密钥]"
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 支付证书和密钥文件更换说明
|
||
|
||
### 5.1 证书文件清单
|
||
|
||
**需要更换的证书文件：**
|
||
|
||
| 文件名 | 用途 | 测试环境路径 | 正式环境路径 |
|
||
|--------|------|--------------|--------------|
|
||
| `apiclient_cert.p12` | API客户端证书 | `/test/cert/` | `/prod/cert/` |
|
||
| `apiclient_cert.pem` | API客户端证书(PEM格式) | `/test/cert/` | `/prod/cert/` |
|
||
| `apiclient_key.pem` | API客户端私钥 | `/test/cert/` | `/prod/cert/` |
|
||
| `rootca.pem` | 根证书 | `/test/cert/` | `/prod/cert/` |
|
||
|
||
### 5.2 证书获取和安装步骤
|
||
|
||
1. **从微信商户平台下载正式证书**
|
||
- 登录微信商户平台
|
||
- 进入 账户中心 → API安全 → 证书下载
|
||
- 下载最新的API证书
|
||
|
||
2. **证书文件部署**
|
||
```bash
|
||
# 创建证书目录
|
||
mkdir -p /opt/xiaozhi/cert
|
||
|
||
# 复制证书文件（权限设置为600）
|
||
cp apiclient_cert.p12 /opt/xiaozhi/cert/
|
||
chmod 600 /opt/xiaozhi/cert/apiclient_cert.p12
|
||
|
||
# 设置证书文件所有者
|
||
chown xiaozhi:xiaozhi /opt/xiaozhi/cert/*
|
||
```
|
||
|
||
3. **配置文件更新**
|
||
```yaml
|
||
# application-prod.yml
|
||
wechat:
|
||
pay:
|
||
cert-path: "/opt/xiaozhi/cert/apiclient_cert.p12"
|
||
cert-password: "${WECHAT_CERT_PASSWORD}" # 证书密码
|
||
```
|
||
|
||
### 5.3 证书安全要求
|
||
|
||
- ✅ 证书文件权限设置为 600 (仅所有者可读写)
|
||
- ✅ 证书密码通过环境变量配置
|
||
- ✅ 定期检查证书有效期（建议每3个月检查一次）
|
||
- ❌ 禁止将证书文件提交到代码仓库
|
||
|
||
---
|
||
|
||
## 6. 支付限额和业务参数调整建议
|
||
|
||
### 6.1 支付限额配置
|
||
|
||
**当前测试环境限额：**
|
||
- 单笔支付限额：无限制
|
||
- 日累计限额：无限制
|
||
- 月累计限额：无限制
|
||
|
||
**建议正式环境限额：**
|
||
|
||
| 限额类型 | 建议值 | 配置位置 | 业务考虑 |
|
||
|----------|--------|----------|----------|
|
||
| 单笔最小金额 | 1分 | 代码校验 | 微信支付最小限额 |
|
||
| 单笔最大金额 | 50,000元 | 代码校验 | 风控要求 |
|
||
| 用户日限额 | 10,000元 | 业务逻辑 | 用户体验平衡 |
|
||
| 用户月限额 | 100,000元 | 业务逻辑 | 合规要求 |
|
||
|
||
### 6.2 业务参数配置
|
||
|
||
```yaml
|
||
# application-prod.yml
|
||
business:
|
||
payment:
|
||
# 支付限额配置
|
||
limits:
|
||
min-amount: 1 # 最小支付金额（分）
|
||
max-amount: 5000000 # 最大支付金额（分）= 50,000元
|
||
daily-limit: 1000000 # 日限额（分）= 10,000元
|
||
monthly-limit: 10000000 # 月限额（分）= 100,000元
|
||
|
||
# 订单配置
|
||
order:
|
||
timeout: 1800 # 订单超时时间（秒）= 30分钟
|
||
retry-times: 3 # 支付重试次数
|
||
|
||
# 风控配置
|
||
risk:
|
||
enable-frequency-limit: true # 启用频率限制
|
||
max-requests-per-minute: 10 # 每分钟最大请求次数
|
||
```
|
||
|
||
### 6.3 支付场景配置
|
||
|
||
**需要配置的支付场景：**
|
||
|
||
1. **商品购买支付**
|
||
- 支付描述格式：`小智AI-{商品名称}`
|
||
- 订单号前缀：`XZ`
|
||
- 超时时间：30分钟
|
||
|
||
2. **会员充值支付**
|
||
- 支付描述格式：`小智AI会员充值`
|
||
- 订单号前缀：`VIP`
|
||
- 超时时间：15分钟
|
||
|
||
3. **设备激活支付**
|
||
- 支付描述格式：`小智设备激活`
|
||
- 订单号前缀：`DEV`
|
||
- 超时时间：60分钟
|
||
|
||
---
|
||
|
||
## 7. 测试数据和模拟账号清理清单
|
||
|
||
### 7.1 需要清理的测试数据
|
||
|
||
**数据库清理清单：**
|
||
|
||
```sql
|
||
-- 1. 清理测试订单数据
|
||
DELETE FROM wechat_pay_order
|
||
WHERE openid LIKE 'test_%'
|
||
OR body LIKE '%测试%'
|
||
OR out_trade_no LIKE '%test%';
|
||
|
||
-- 2. 清理测试用户数据
|
||
DELETE FROM user_info
|
||
WHERE openid LIKE 'test_%'
|
||
OR nickname LIKE '%测试%';
|
||
|
||
-- 3. 清理测试设备数据
|
||
DELETE FROM device_info
|
||
WHERE device_id LIKE 'test_%'
|
||
OR device_name LIKE '%测试%';
|
||
|
||
-- 4. 清理测试日志数据（保留最近7天）
|
||
DELETE FROM system_log
|
||
WHERE create_time < DATE_SUB(NOW(), INTERVAL 7 DAY)
|
||
AND (content LIKE '%test%' OR content LIKE '%测试%');
|
||
```
|
||
|
||
### 7.2 需要移除的测试账号
|
||
|
||
**测试OpenID清单：**
|
||
- `test_normal_001` - 正常支付测试账号
|
||
- `test_normal_002` - 高价值商品测试账号
|
||
- `test_boundary_001` - 边界值测试账号
|
||
- `test_boundary_002` - 零金额测试账号
|
||
- `test_boundary_003` - 负数金额测试账号
|
||
- `test_boundary_004` - 极大金额测试账号
|
||
- `test_duplicate_001` - 重复支付测试账号
|
||
|
||
### 7.3 配置文件清理
|
||
|
||
**需要移除的测试配置：**
|
||
|
||
```yaml
|
||
# 移除测试环境特有配置
|
||
# application.yml 中需要删除的配置项：
|
||
|
||
# 测试模式配置（需要删除）
|
||
test:
|
||
mode: true
|
||
mock-payment: true
|
||
skip-signature-verify: true
|
||
|
||
# 调试配置（需要删除）
|
||
debug:
|
||
enable-sql-log: true
|
||
enable-request-log: true
|
||
```
|
||
|
||
### 7.4 代码中的测试标记清理
|
||
|
||
**需要检查和移除的代码：**
|
||
|
||
```java
|
||
// 搜索并移除以下测试相关代码
|
||
// 1. 测试模式判断
|
||
if (isTestMode()) {
|
||
// 测试逻辑 - 需要移除
|
||
}
|
||
|
||
// 2. Mock数据返回
|
||
// WechatPayServiceImpl.java 中的模拟返回
|
||
return mockPaymentResponse(); // 需要移除
|
||
|
||
// 3. 跳过签名验证的代码
|
||
if (!isProduction()) {
|
||
return true; // 跳过验证 - 需要移除
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 支付成功页面正式文案要求
|
||
|
||
### 8.1 支付成功页面文案
|
||
|
||
**页面标题：**
|
||
```
|
||
支付成功
|
||
```
|
||
|
||
**成功提示文案：**
|
||
```
|
||
恭喜您，支付已完成！
|
||
您的订单正在处理中，请耐心等待。
|
||
```
|
||
|
||
**订单信息展示：**
|
||
```
|
||
订单号：{订单号}
|
||
支付金额：¥{金额}
|
||
支付时间：{时间}
|
||
商品名称：{商品名称}
|
||
```
|
||
|
||
**操作按钮文案：**
|
||
- 主按钮：`返回首页`
|
||
- 次按钮：`查看订单`
|
||
|
||
### 8.2 支付失败页面文案
|
||
|
||
**页面标题：**
|
||
```
|
||
支付失败
|
||
```
|
||
|
||
**失败提示文案：**
|
||
```
|
||
很抱歉，支付未能完成
|
||
请检查网络连接或稍后重试
|
||
```
|
||
|
||
**常见错误提示：**
|
||
- 余额不足：`账户余额不足，请充值后重试`
|
||
- 网络错误：`网络连接异常，请检查网络后重试`
|
||
- 系统繁忙：`系统繁忙，请稍后重试`
|
||
|
||
**操作按钮文案：**
|
||
- 主按钮：`重新支付`
|
||
- 次按钮：`返回首页`
|
||
|
||
### 8.3 支付中页面文案
|
||
|
||
**页面标题：**
|
||
```
|
||
支付处理中
|
||
```
|
||
|
||
**处理提示文案：**
|
||
```
|
||
正在处理您的支付请求
|
||
请不要关闭页面或重复操作
|
||
```
|
||
|
||
**等待动画文案：**
|
||
```
|
||
支付处理中，请稍候...
|
||
```
|
||
|
||
### 8.4 文案配置文件
|
||
|
||
**创建文案配置文件：** `src/main/resources/messages.properties`
|
||
|
||
```properties
|
||
# 支付相关文案
|
||
payment.success.title=支付成功
|
||
payment.success.message=恭喜您，支付已完成！您的订单正在处理中，请耐心等待。
|
||
payment.success.button.home=返回首页
|
||
payment.success.button.order=查看订单
|
||
|
||
payment.failed.title=支付失败
|
||
payment.failed.message=很抱歉，支付未能完成，请检查网络连接或稍后重试
|
||
payment.failed.button.retry=重新支付
|
||
payment.failed.button.home=返回首页
|
||
|
||
payment.processing.title=支付处理中
|
||
payment.processing.message=正在处理您的支付请求，请不要关闭页面或重复操作
|
||
payment.processing.waiting=支付处理中，请稍候...
|
||
|
||
# 错误提示文案
|
||
payment.error.insufficient_balance=账户余额不足，请充值后重试
|
||
payment.error.network_error=网络连接异常，请检查网络后重试
|
||
payment.error.system_busy=系统繁忙，请稍后重试
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 上线前检查清单
|
||
|
||
### 9.1 配置检查清单
|
||
|
||
**🔴 必须完成项：**
|
||
|
||
- [ ] **API接口地址更新**
|
||
- [ ] 统一下单接口地址已更新为正式环境
|
||
- [ ] 订单查询接口地址已更新为正式环境
|
||
- [ ] 支付回调URL已配置为HTTPS正式地址
|
||
|
||
- [ ] **密钥和证书更新**
|
||
- [ ] 商户密钥已更换为正式密钥
|
||
- [ ] API证书已更换为正式证书
|
||
- [ ] 证书文件权限已正确设置（600）
|
||
|
||
- [ ] **商户信息更新**
|
||
- [ ] AppID已更新为正式AppID
|
||
- [ ] 商户号已更新为正式商户号
|
||
- [ ] 微信商户平台回调URL已配置
|
||
|
||
- [ ] **测试数据清理**
|
||
- [ ] 测试订单数据已清理
|
||
- [ ] 测试用户数据已清理
|
||
- [ ] 测试配置已移除
|
||
|
||
**🟡 建议完成项：**
|
||
|
||
- [ ] **业务参数优化**
|
||
- [ ] 支付限额已配置
|
||
- [ ] 订单超时时间已设置
|
||
- [ ] 风控参数已配置
|
||
|
||
- [ ] **文案更新**
|
||
- [ ] 支付成功页面文案已更新
|
||
- [ ] 支付失败页面文案已更新
|
||
- [ ] 错误提示文案已完善
|
||
|
||
### 9.2 测试验证清单
|
||
|
||
**上线前必须测试的功能：**
|
||
|
||
1. **支付功能测试**
|
||
- [ ] 小额支付测试（1分）
|
||
- [ ] 正常金额支付测试（100元）
|
||
- [ ] 大额支付测试（1000元）
|
||
- [ ] 支付失败场景测试
|
||
|
||
2. **回调功能测试**
|
||
- [ ] 支付成功回调处理
|
||
- [ ] 支付失败回调处理
|
||
- [ ] 回调签名验证
|
||
|
||
3. **订单查询测试**
|
||
- [ ] 成功订单查询
|
||
- [ ] 失败订单查询
|
||
- [ ] 不存在订单查询
|
||
|
||
4. **异常处理测试**
|
||
- [ ] 网络异常处理
|
||
- [ ] 参数错误处理
|
||
- [ ] 系统异常处理
|
||
|
||
### 9.3 监控和日志配置
|
||
|
||
**生产环境监控配置：**
|
||
|
||
```yaml
|
||
# application-prod.yml
|
||
logging:
|
||
level:
|
||
com.xiaozhi.pay: INFO # 支付相关日志级别
|
||
org.springframework: WARN # Spring框架日志级别
|
||
file:
|
||
name: /var/log/xiaozhi/payment.log # 支付日志文件
|
||
max-size: 100MB # 单个日志文件最大大小
|
||
max-history: 30 # 保留日志文件天数
|
||
|
||
# 监控配置
|
||
management:
|
||
endpoints:
|
||
web:
|
||
exposure:
|
||
include: health,info,metrics # 暴露的监控端点
|
||
endpoint:
|
||
health:
|
||
show-details: when-authorized # 健康检查详情显示条件
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 应急预案
|
||
|
||
### 10.1 回滚方案
|
||
|
||
**如果上线后发现问题，按以下步骤回滚：**
|
||
|
||
1. **立即停止服务**
|
||
```bash
|
||
sudo systemctl stop xiaozhi-server
|
||
```
|
||
|
||
2. **恢复备份配置**
|
||
```bash
|
||
cp application.yml.backup application.yml
|
||
```
|
||
|
||
3. **重启服务**
|
||
```bash
|
||
sudo systemctl start xiaozhi-server
|
||
```
|
||
|
||
4. **验证服务状态**
|
||
```bash
|
||
curl -X GET http://localhost:8091/actuator/health
|
||
```
|
||
|
||
### 10.2 常见问题处理
|
||
|
||
**问题1：支付接口返回签名错误**
|
||
- **原因：** 商户密钥配置错误
|
||
- **解决：** 检查并更新正确的商户密钥
|
||
|
||
**问题2：回调接口无法访问**
|
||
- **原因：** 回调URL配置错误或SSL证书问题
|
||
- **解决：** 检查回调URL和SSL证书配置
|
||
|
||
**问题3：订单查询失败**
|
||
- **原因：** API接口地址未更新或证书问题
|
||
- **解决：** 检查API地址和证书配置
|
||
|
||
### 10.3 联系方式
|
||
|
||
**技术支持联系方式：**
|
||
- **开发团队负责人：** [姓名] - [电话] - [邮箱]
|
||
- **运维团队负责人：** [姓名] - [电话] - [邮箱]
|
||
- **微信支付技术支持：** 400-xxx-xxxx
|
||
|
||
---
|
||
|
||
## 11. 文档维护
|
||
|
||
**文档更新记录：**
|
||
|
||
| 版本 | 更新日期 | 更新内容 | 更新人 |
|
||
|------|----------|----------|--------|
|
||
| v1.0 | 2025-09-30 | 初始版本创建 | AI助手 |
|
||
|
||
**文档审核：**
|
||
- **技术审核：** 待审核
|
||
- **安全审核：** 待审核
|
||
- **业务审核：** 待审核
|
||
|
||
**下次更新计划：**
|
||
- 根据实际上线情况更新配置参数
|
||
- 补充实际遇到的问题和解决方案
|
||
- 优化检查清单和操作步骤
|
||
|
||
---
|
||
|
||
> 📋 **使用说明：** 请严格按照本文档顺序执行配置修改，每完成一项请在对应的检查框中打勾。如遇到问题，请及时联系技术支持团队。
|
||
|
||
> 🔒 **安全提醒：** 本文档包含敏感配置信息，请妥善保管，不得外传。所有密钥和证书信息请通过安全渠道获取和传输。 |