liqupan/server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat ：init

Browse Source
This commit is contained in:
liqupan
2025-11-02 19:34:16 +08:00
commit b767041311
617 changed files with 124099 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

640
微信小程序支付上线配置修改清单.md Normal file
View File

@@ -0,0 +1,640 @@
# 微信小程序支付功能上线配置修改清单
## 文档说明
**文档版本：** 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助手 |
**文档审核：**
- **技术审核：** 待审核
- **安全审核：** 待审核
- **业务审核：** 待审核
**下次更新计划：**
- 根据实际上线情况更新配置参数
- 补充实际遇到的问题和解决方案
- 优化检查清单和操作步骤
---
> 📋 **使用说明：** 请严格按照本文档顺序执行配置修改，每完成一项请在对应的检查框中打勾。如遇到问题，请及时联系技术支持团队。
> 🔒 **安全提醒：** 本文档包含敏感配置信息，请妥善保管，不得外传。所有密钥和证书信息请通过安全渠道获取和传输。