liqupan/server

Fork 0

Files

liqupan b767041311 feat ：init

2025-11-02 19:34:16 +08:00

17 KiB

Raw Permalink Blame History

微信小程序支付功能上线配置修改清单

文档说明

文档版本： 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接口地址

需要修改的配置项：

# 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 密钥配置更新

⚠️ 敏感信息 - 需要从运维团队获取正式密钥

# 需要替换的密钥配置
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 修改执行步骤

备份当前配置文件

cp src/main/resources/application.yml src/main/resources/application.yml.backup

更新配置文件
- 修改 application-prod.yml 中的API地址
- 配置生产环境密钥（使用环境变量）
验证配置
- 确认所有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安全要求

HTTPS协议要求
- ✅ 必须使用HTTPS协议
- ✅ SSL证书必须有效
- ✅ 支持TLS 1.2及以上版本
域名要求
- ✅ 使用已备案的正式域名
- ✅ 域名必须与微信商户平台配置一致
- ❌ 不能使用IP地址
端口要求
- ✅ 使用标准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 配置文件更新示例

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

生产服务器需要设置的环境变量：

# 微信小程序配置
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 证书获取和安装步骤

从微信商户平台下载正式证书
- 登录微信商户平台
- 进入账户中心 → API安全 → 证书下载
- 下载最新的API证书

证书文件部署

# 创建证书目录
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/*

配置文件更新

# 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 业务参数配置

# 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 支付场景配置

需要配置的支付场景：

商品购买支付
- 支付描述格式：小智AI-{商品名称}
- 订单号前缀：XZ
- 超时时间：30分钟
会员充值支付
- 支付描述格式：小智AI会员充值
- 订单号前缀：VIP
- 超时时间：15分钟
设备激活支付
- 支付描述格式：小智设备激活
- 订单号前缀：DEV
- 超时时间：60分钟

7. 测试数据和模拟账号清理清单

7.1 需要清理的测试数据

数据库清理清单：

-- 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 配置文件清理

需要移除的测试配置：

# 移除测试环境特有配置
# application.yml 中需要删除的配置项：

# 测试模式配置（需要删除）
test:
  mode: true
  mock-payment: true
  skip-signature-verify: true

# 调试配置（需要删除）
debug:
  enable-sql-log: true
  enable-request-log: true

7.4 代码中的测试标记清理

需要检查和移除的代码：

// 搜索并移除以下测试相关代码
// 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

# 支付相关文案
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分）
- 正常金额支付测试（100元）
- 大额支付测试（1000元）
- 支付失败场景测试
回调功能测试
- 支付成功回调处理
- 支付失败回调处理
- 回调签名验证
订单查询测试
- 成功订单查询
- 失败订单查询
- 不存在订单查询
异常处理测试
- 网络异常处理
- 参数错误处理
- 系统异常处理

9.3 监控和日志配置

生产环境监控配置：

# 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 回滚方案

如果上线后发现问题，按以下步骤回滚：

立即停止服务
```
sudo systemctl stop xiaozhi-server
```

恢复备份配置

cp application.yml.backup application.yml

重启服务
```
sudo systemctl start xiaozhi-server
```

验证服务状态

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助手

文档审核：

技术审核： 待审核
安全审核： 待审核
业务审核： 待审核

下次更新计划：

根据实际上线情况更新配置参数
补充实际遇到的问题和解决方案
优化检查清单和操作步骤

📋 使用说明： 请严格按照本文档顺序执行配置修改，每完成一项请在对应的检查框中打勾。如遇到问题，请及时联系技术支持团队。

🔒 安全提醒： 本文档包含敏感配置信息，请妥善保管，不得外传。所有密钥和证书信息请通过安全渠道获取和传输。

17 KiB Raw Permalink Blame History Unescape Escape

微信小程序支付功能上线配置修改清单

文档说明

1. 测试环境与正式环境差异对比

1.1 环境配置差异表

1.2 配置文件修改位置

2. API接口地址和密钥替换清单

2.1 微信支付API接口地址

2.2 密钥配置更新

2.3 修改执行步骤

3. 支付回调URL更新要求

3.1 回调URL配置

3.2 回调URL安全要求

3.3 微信商户平台配置

4. 商户号、AppID等敏感信息变更清单

4.1 微信小程序信息

4.2 微信支付商户信息

4.3 配置文件更新示例

4.4 环境变量配置

5. 支付证书和密钥文件更换说明

5.1 证书文件清单

5.2 证书获取和安装步骤

5.3 证书安全要求

6. 支付限额和业务参数调整建议

6.1 支付限额配置

6.2 业务参数配置

6.3 支付场景配置

7. 测试数据和模拟账号清理清单

7.1 需要清理的测试数据

7.2 需要移除的测试账号

7.3 配置文件清理

7.4 代码中的测试标记清理

8. 支付成功页面正式文案要求

8.1 支付成功页面文案

8.2 支付失败页面文案

8.3 支付中页面文案

8.4 文案配置文件

9. 上线前检查清单

9.1 配置检查清单

9.2 测试验证清单

9.3 监控和日志配置

10. 应急预案

10.1 回滚方案

10.2 常见问题处理

10.3 联系方式

11. 文档维护

17 KiB

Raw Permalink Blame History