chore(addon/huaweipay): 更新huaweipay

2025-12-04 10:32:00 +08:00
parent 09ed1bd427
commit a793ed541b
14 changed files with 1093 additions and 498 deletions
--- a/src/addon/huaweipay/MANUAL_TEST_GUIDE.md
+++ b/src/addon/huaweipay/MANUAL_TEST_GUIDE.md
@@ -0,0 +1,318 @@
+# 华为支付手动测试指南
+
+## 1. 测试环境准备
+
+### 1.1 配置文件准备
+
+#### 1.1.1 证书准备
+
+确保在 `mock/cert/` 目录下有以下证书文件：
+- `merchant_private_key.pem` - 商户应用私钥证书
+- `huawei_public_key.pem` - 华为平台公钥证书
+
+#### 1.1.2 配置文件设置
+
+编辑 `tests/mock/data.yml` 文件，确保以下配置项正确设置：
+
+```yaml
+# 华为支付测试配置
+HuaweiPay:
+  # 沙盒模式
+  sandbox: true
+  # 应用ID
+  app_id: 'test_app_id'
+  # 商户号
+  merc_no: 'test_merc_no'
+  # 授权ID
+  mch_auth_id: 'test_mch_auth_id'
+  # 证书文件路径（相对于项目根目录）
+  private_key: 'mock/cert/merchant_private_key.pem'
+  # 私钥文本内容
+  private_key_text: |
+    -----BEGIN PRIVATE KEY-----
+    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDLW1j8a1KQw7X2
+    ...
+    -----END PRIVATE KEY-----
+  # 华为公钥文件路径（相对于项目根目录）
+  huawei_public_key: 'mock/cert/huawei_public_key.pem'
+  # 华为公钥文本内容
+  huawei_public_key_text: |
+    -----BEGIN PUBLIC KEY-----
+    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw0T1JZ7X2Y5
+    ...
+    -----END PUBLIC KEY-----
+  # 异步通知URL
+  notify_url: 'https://your-domain.com/huaweipay/notify'
+  # 同步返回URL
+  return_url: 'https://your-domain.com/huaweipay/return'
+```
+
+### 1.2 系统配置
+
+1. 登录系统后台
+2. 进入「支付配置」页面
+3. 找到「华为支付」配置项
+4. 填写以下信息：
+   - 应用ID
+   - 商户号
+   - 授权ID
+   - 私钥（可以选择文件上传或文本输入）
+   - 华为公钥（可以选择文件上传或文本输入）
+   - 异步通知URL
+   - 同步返回URL
+5. 开启华为支付
+
+## 2. 单元测试
+
+### 2.1 运行证书格式化测试
+
+```bash
+./vendor/bin/phpunit addon/huaweipay/tests/HuaweiPayConfigTest.php
+```
+
+### 2.2 运行支付模型测试
+
+```bash
+./vendor/bin/phpunit addon/huaweipay/tests/PayModelTest.php
+```
+
+## 3. 功能测试
+
+### 3.1 H5支付测试
+
+1. 进入系统前台
+2. 选择一个商品加入购物车
+3. 提交订单
+4. 选择「华为支付」作为支付方式
+5. 点击「立即支付」
+6. 系统将跳转到华为H5支付页面
+7. 测试不同支付场景：
+   - 成功支付
+   - 取消支付
+   - 超时未支付
+
+### 3.2 微信小程序支付测试
+
+1. 打开微信开发者工具
+2. 导入小程序项目
+3. 登录小程序账号
+4. 选择一个商品加入购物车
+5. 提交订单
+6. 选择「华为支付」作为支付方式
+7. 点击「立即支付」
+8. 调用华为微信小程序支付接口
+9. 测试不同支付场景：
+   - 成功支付
+   - 取消支付
+   - 超时未支付
+
+### 3.3 APP支付测试
+
+1. 编译APP项目
+2. 在测试设备上安装APP
+3. 登录APP账号
+4. 选择一个商品加入购物车
+5. 提交订单
+6. 选择「华为支付」作为支付方式
+7. 点击「立即支付」
+8. 调用华为APP支付接口
+9. 测试不同支付场景：
+   - 成功支付
+   - 取消支付
+   - 超时未支付
+
+## 4. 回调测试
+
+### 4. 回调测试
+
+**测试目标**：验证华为支付异步通知处理流程是否正常工作，包括签名验证和订单状态更新。
+
+#### 4.1 测试准备
+1. **配置回调地址**：
+   - 在华为支付模型的配置中设置回调URL（通常为`http://your-domain.com/addon/huaweipay/shop/controller/pay/notify`）
+   - 开发环境可使用ngrok等工具进行本地端口映射：`ngrok http 80`
+
+2. **了解回调处理流程**：
+   - 华为支付异步回调通过`PayNotify`事件触发
+   - 事件监听器：`addon\huaweipay\event\PayNotify`
+   - 实际处理逻辑：`addon\huaweipay\model\Pay::notify()`方法
+
+#### 4.2 模拟回调测试
+
+**方法一：使用Postman模拟回调请求**
+
+1. **构造回调参数**：
+```json
+{
+  "pay_type": "huaweipay",
+  "out_trade_no": "TEST_ORDER_202310100001",
+  "trade_no": "HWPAY2023101000000001",
+  "total_amount": "1.00",
+  "trade_status": "SUCCESS",
+  "timestamp": "1696944000000",
+  "sign": "xxxxxxxxx",
+  "app_type": "h5"
+}
+```
+
+2. **发送POST请求**：
+   - URL: `http://your-domain.com/addon/huaweipay/shop/controller/pay/notify`
+   - Method: POST
+   - Body: 选择raw JSON格式，粘贴上面的测试数据
+
+3. **验证回调结果**：
+   - 检查响应是否为"success"字符串
+   - 查看系统日志（`runtime/log`目录）
+   - 确认订单状态是否已更新为已支付
+
+**方法二：使用命令行工具**
+
+```bash
+curl -X POST \
+  http://your-domain.com/addon/huaweipay/shop/controller/pay/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"pay_type":"huaweipay","out_trade_no":"TEST_ORDER_202310100001","trade_no":"HWPAY2023101000000001","total_amount":"1.00","trade_status":"SUCCESS","timestamp":"1696944000000","sign":"xxxxxxxxx"}'
+```
+
+#### 4.3 回调签名验证测试
+
+**测试目标**：验证回调签名验证逻辑是否正常工作
+
+**测试步骤**：
+1. 构造正确的回调参数和签名
+2. 发送回调请求，验证处理成功
+3. 修改签名为错误值，重新发送请求
+4. 验证签名错误时返回"fail"
+
+**测试要点**：
+- 检查`HuaweiPayClient::verifyNotify()`方法的实现
+- 确保使用正确的公钥进行签名验证
+- 验证失败时记录详细日志
+
+**日志检查**：
+```
+# 签名验证成功日志
+[info] 华为支付回调参数: {"out_trade_no":"TEST_ORDER_202310100001",...}
+[info] 华为支付回调处理成功，订单号: TEST_ORDER_202310100001
+
+# 签名验证失败日志
+[error] 华为支付回调签名验证失败: {"out_trade_no":"TEST_ORDER_202310100001",...}
+```
+
+**注意事项**：
+- 回调请求需要包含正确的签名，使用华为支付公钥进行验证
+- 回调处理完成后，必须向华为服务器返回"success"字符串，否则华为会持续发送通知（默认重试间隔为15s,30s,1m,2m,5m,10m,30m,1h,2h,6h,15h）
+- 回调处理逻辑需要支持幂等性，防止重复处理同一笔订单
+
+## 5. 常见问题排查
+
+### 5.1 证书加载失败
+
+**问题现象：** 系统提示「加载商户应用私有证书失败」或「加载华为平台支付证书失败」
+
+**解决方法：**
+- 检查证书文件路径是否正确
+- 验证证书格式是否符合要求（PEM格式）
+- 确保证书内容没有多余的空格或换行
+- 检查文件权限是否正确
+
+### 5.2 签名验证失败
+
+**问题现象：** 系统提示「签名验证失败」或华为支付API返回签名错误
+
+**解决方法：**
+- 检查私钥和公钥是否匹配
+- 验证签名算法是否正确（RSA2）
+- 确保请求参数没有被篡改
+- 检查时间戳是否在有效范围内
+
+### 5.3 支付接口调用失败
+
+**问题现象：** 调用华为支付API返回错误码
+
+**解决方法：**
+- 检查API请求参数是否完整
+- 验证参数格式是否符合要求
+- 检查网络连接是否正常
+- 查看华为支付API文档，了解错误码含义
+
+### 5.4 订单状态更新失败
+
+**问题现象：** 支付成功后，系统订单状态未更新
+
+**解决方法：**
+- 检查异步通知URL是否可访问
+- 验证通知签名是否正确
+- 查看系统日志，了解处理过程
+- 检查订单号是否正确匹配
+
+## 6. 测试注意事项
+
+1. **沙盒环境：** 测试时建议使用华为支付沙盒环境，避免产生真实交易
+2. **日志记录：** 开启详细日志记录，便于排查问题
+3. **安全防护：** 测试完成后，及时清理测试数据和敏感信息
+4. **兼容性测试：** 确保在不同浏览器、设备上都能正常支付
+5. **性能测试：** 测试高并发场景下的支付处理能力
+
+## 7. 测试报告模板
+
+```
+# 华为支付测试报告
+
+## 测试基本信息
+- 测试时间：YYYY-MM-DD
+- 测试环境：开发环境/测试环境/生产环境
+- 测试人员：XXX
+
+## 测试内容
+
+### 7.1 配置测试
+- [ ] 证书文件存在性检查
+- [ ] 配置文件格式检查
+- [ ] 证书加载测试
+
+### 7.2 功能测试
+- [ ] H5支付测试
+  - [ ] 成功支付流程
+  - [ ] 取消支付流程
+  - [ ] 超时未支付流程
+- [ ] 微信小程序支付测试
+  - [ ] 成功支付流程
+  - [ ] 取消支付流程
+  - [ ] 超时未支付流程
+- [ ] APP支付测试
+  - [ ] 成功支付流程
+  - [ ] 取消支付流程
+  - [ ] 超时未支付流程
+
+### 7.3 回调测试
+- [ ] 异步通知处理
+- [ ] 同步返回处理
+- [ ] 订单状态更新
+
+## 测试结果
+
+### 7.1 通过的测试
+- ...
+
+### 7.2 失败的测试
+- ...
+
+### 7.3 问题总结
+
+| 问题描述 | 严重程度 | 状态 | 解决方案 |
+|---------|---------|------|---------|
+| ... | 高/中/低 | 已解决/待解决 | ... |
+
+## 测试结论
+
+综合测试结果，华为支付模块是否满足上线要求：
+- [ ] 是
+- [ ] 否（需要进一步修复）
+
+## 建议
+
+1. ...
+2. ...
+3. ...
+```