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