# 支付网关集成指南

## 概述
本文档说明如何配置和集成支付宝和微信支付网关。

## 环境配置

### 1. 配置文件
在 `.env` 文件中添加以下配置：

```env
# 支付宝配置
ALIPAY_APP_ID=your_app_id
ALIPAY_MERCHANT_PRIVATE_KEY=your_merchant_private_key
ALIPAY_PUBLIC_KEY=your_alipay_public_key
ALIPAY_NOTIFY_URL=https://yourdomain.com/api/order/alipay-notify
ALIPAY_RETURN_URL=https://yourdomain.com/order
ALIPAY_GATEWAY_URL=https://openapi.alipay.com/gateway.do

# 微信支付配置
WECHAT_APP_ID=your_app_id
WECHAT_MCH_ID=your_mch_id
WECHAT_API_KEY=your_api_key
WECHAT_NOTIFY_URL=https://yourdomain.com/api/order/wechat-notify
WECHAT_GATEWAY_URL=https://api.mch.weixin.qq.com
```

### 2. 数据库迁移
运行以下SQL添加 `trade_no` 字段到订单表：

```sql
ALTER TABLE `la_order` ADD COLUMN `trade_no` varchar(100) DEFAULT NULL COMMENT '第三方交易号' AFTER `payment_time`;
```

## 支付流程

### 正常支付流程
1. 用户点击"支付"按钮
2. 选择支付方式（支付宝或微信）
3. 点击"确认支付"
4. 前端调用 `/order.order/alipay` 或 `/order.order/wechat` 接口
5. 后端生成支付链接/数据并返回
6. 前端跳转到支付页面或显示二维码
7. 用户完成支付
8. 支付网关回调 `/api/order/alipay-notify` 或 `/api/order/wechat-notify`
9. 后端验证签名并更新订单状态

### 补单支付流程
1. 用户选择"补单支付"
2. 输入支付订单号
3. 选择支付方式
4. 点击"确认支付"
5. 前端调用支付接口，参数中 `is_supplement=1`
6. 后端不校验订单是否存在，直接生成支付链接/数据
7. 用户完成支付
8. 支付网关回调更新订单状态

## 支付宝集成

### 获取密钥
1. 登录 [支付宝开放平台](https://open.alipay.com/)
2. 进入"开发者中心" -> "应用管理"
3. 创建应用或选择已有应用
4. 在"应用信息"中获取 App ID
5. 在"开发设置"中生成密钥对
6. 下载商户私钥和支付宝公钥

### 配置回调
1. 在应用设置中配置"异步通知地址"
2. 地址格式：`https://yourdomain.com/api/order/alipay-notify`
3. 配置"同步返回地址"（可选）
4. 地址格式：`https://yourdomain.com/order`

### 测试
支付宝提供沙箱环境用于测试：
- 沙箱网址：https://openapi.alipaydev.com/gateway.do
- 在 `.env` 中设置 `ALIPAY_GATEWAY_URL=https://openapi.alipaydev.com/gateway.do`

## 微信支付集成

### 获取密钥
1. 登录 [微信商户平台](https://pay.weixin.qq.com/)
2. 进入"账户中心" -> "API安全"
3. 获取商户号（Mch ID）
4. 在"API密钥"中生成 API Key
5. 在"证书管理"中下载证书（如需要）

### 配置回调
1. 在商户平台配置"回调地址"
2. 地址格式：`https://yourdomain.com/api/order/wechat-notify`

### 测试
微信支付提供沙箱环境用于测试：
- 沙箱网址：https://api.mch.weixin.qq.com
- 使用测试商户号和 API Key

## 后端实现

### 支付逻辑（OrderLogic.php）
- `alipayPay()` - 生成支付宝支付URL
- `wechatPay()` - 生成微信支付数据
- `generateAlipayUrl()` - 生成支付宝支付链接
- `generateWechatPayData()` - 生成微信支付数据
- `generateAlipaySign()` - 生成支付宝签名
- `generateWechatSign()` - 生成微信签名

### 回调处理
- `AlipayNotifyController::notify()` - 处理支付宝异步通知
- `WechatNotifyController::notify()` - 处理微信异步通知

### 签名验证
- 支付宝：使用 RSA2 算法验证签名
- 微信：使用 MD5 算法验证签名

## 前端实现

### 支付流程
1. 用户选择支付方式
2. 调用 `alipayPay()` 或 `wechatPay()` API
3. 获取支付链接或支付数据
4. 支付宝：跳转到支付页面
5. 微信：显示二维码或其他处理

### 支付状态更新
- 支付完成后，后端通过回调更新订单状态
- 前端定时刷新订单列表以获取最新状态

## 常见问题

### 1. 签名验证失败
- 检查密钥是否正确
- 检查签名算法是否匹配
- 检查参数排序是否正确

### 2. 回调未收到
- 检查回调地址是否正确
- 检查防火墙是否允许回调
- 检查日志中是否有错误信息

### 3. 金额不匹配
- 检查前端传递的金额是否正确
- 检查后端计算的金额是否正确
- 微信支付需要将金额转换为分

## 安全建议

1. 不要在代码中硬编码密钥，使用环境变量
2. 验证所有回调请求的签名
3. 使用 HTTPS 传输敏感信息
4. 定期更新密钥
5. 记录所有支付相关的日志
6. 实现幂等性处理，防止重复支付

## 测试清单

- [ ] 支付宝支付流程测试
- [ ] 微信支付流程测试
- [ ] 补单支付流程测试
- [ ] 回调处理测试
- [ ] 签名验证测试
- [ ] 金额验证测试
- [ ] 异常处理测试
- [ ] 并发支付测试