# 订单支付功能完整指南

## 📋 目录

1. [快速开始](#快速开始)
2. [功能概述](#功能概述)
3. [系统架构](#系统架构)
4. [配置指南](#配置指南)
5. [API文档](#api文档)
6. [测试指南](#测试指南)
7. [部署指南](#部署指南)
8. [常见问题](#常见问题)
9. [文档索引](#文档索引)

---

## 快速开始

### 1. 配置环境变量 (5分钟)

在 `.env` 文件中添加支付配置：

```env
# 支付宝
ALIPAY_APP_ID=your_app_id
ALIPAY_MERCHANT_PRIVATE_KEY=your_private_key
ALIPAY_PUBLIC_KEY=your_public_key
ALIPAY_NOTIFY_URL=https://yourdomain.com/api/order/alipay-notify
ALIPAY_RETURN_URL=https://yourdomain.com/order

# 微信
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
```

### 2. 执行数据库迁移 (1分钟)

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

### 3. 测试支付流程 (10分钟)

- 打开订单列表
- 点击"支付"按钮
- 选择支付方式
- 完成支付

详见 [PAYMENT_QUICK_START.md](./PAYMENT_QUICK_START.md)

---

## 功能概述

### 支持的支付方式

| 支付方式 | 状态 | 说明 |
|---------|------|------|
| 支付宝 | ✅ 已实现 | 支持页面支付和二维码支付 |
| 微信支付 | ✅ 已实现 | 支持二维码支付 |
| 银行卡 | ❌ 已移除 | 不再支持 |

### 支持的支付类型

| 支付类型 | 说明 |
|---------|------|
| 正常支付 | 支付指定订单 |
| 补单支付 | 输入订单号后支付，无需校验订单是否存在 |

### 订单状态流转

```
创建订单 → 待支付 → 已支付 → 已退款
                  ↓
                已取消
```

---

## 系统架构

### 后端架构

```
OrderController (支付接口)
    ↓
OrderLogic (支付逻辑)
    ├── alipayPay() → generateAlipayUrl()
    ├── wechatPay() → generateWechatPayData()
    ├── generateAlipaySign() (RSA2签名)
    └── generateWechatSign() (MD5签名)
    
AlipayNotifyController (支付宝回调)
    ├── 验证签名
    ├── 验证金额
    └── 更新订单状态

WechatNotifyController (微信回调)
    ├── 验证签名
    ├── 验证金额
    └── 更新订单状态
```

### 前端架构

```
OrderList (订单列表)
    ├── PayDialog (支付对话框)
    │   ├── 支付类型选择
    │   ├── 支付方式选择
    │   └── 确认支付
    └── API调用
        ├── alipayPay()
        └── wechatPay()
```

### 数据流

```
用户支付 → 前端调用API → 后端生成支付链接 → 前端跳转支付页面
                                    ↓
                            用户完成支付
                                    ↓
                        支付网关回调后端
                                    ↓
                        后端验证签名和金额
                                    ↓
                        后端更新订单状态
                                    ↓
                        前端刷新订单列表
```

---

## 配置指南

### 支付宝配置

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

#### 配置回调
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

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

#### 沙箱测试
- 使用测试商户号和 API Key
- 网址：https://api.mch.weixin.qq.com

详见 [PAYMENT_GATEWAY_INTEGRATION.md](./PAYMENT_GATEWAY_INTEGRATION.md)

---

## API文档

### 支付接口

#### 支付宝支付
```
POST /order.order/alipay
Content-Type: application/json

{
  "id": 1,
  "order_no": "ORD20240101120000123456",
  "amount": 100.00,
  "payment_method": "alipay"
}

Response:
{
  "code": 0,
  "msg": "success",
  "data": {
    "pay_url": "https://openapi.alipay.com/gateway.do?..."
  }
}
```

#### 微信支付
```
POST /order.order/wechat
Content-Type: application/json

{
  "id": 1,
  "order_no": "ORD20240101120000123456",
  "amount": 100.00,
  "payment_method": "wechat"
}

Response:
{
  "code": 0,
  "msg": "success",
  "data": {
    "pay_url": "https://api.mch.weixin.qq.com/pay/unifiedorder",
    "pay_data": {...}
  }
}
```

#### 补单支付
```
POST /order.order/alipay (或 /order.order/wechat)
Content-Type: application/json

{
  "order_no": "ORD20240101120000123456",
  "payment_method": "alipay",
  "is_supplement": 1
}
```

详见 [PAYMENT_API_ENDPOINTS.md](./PAYMENT_API_ENDPOINTS.md)

---

## 测试指南

### 单元测试

```php
// 测试支付宝签名
$params = ['app_id' => '123', 'method' => 'pay'];
$sign = OrderLogic::generateAlipaySign($params, $privateKey);
// 验证签名是否正确

// 测试微信签名
$params = ['appid' => 'wx123', 'mch_id' => '456'];
$sign = OrderLogic::generateWechatSign($params, $apiKey);
// 验证签名是否正确
```

### 集成测试

1. **支付宝支付流程**
   - 创建订单
   - 调用支付宝支付接口
   - 验证返回支付URL
   - 模拟支付宝回调
   - 验证订单状态更新

2. **微信支付流程**
   - 创建订单
   - 调用微信支付接口
   - 验证返回支付数据
   - 模拟微信回调
   - 验证订单状态更新

3. **补单支付流程**
   - 调用支付接口，参数中 `is_supplement=1`
   - 验证不校验订单是否存在
   - 验证返回支付链接/数据

### 端到端测试

1. 打开订单列表
2. 创建新订单
3. 点击支付按钮
4. 选择支付方式
5. 完成支付
6. 验证订单状态更新

详见 [PAYMENT_DEPLOYMENT_CHECKLIST.md](./PAYMENT_DEPLOYMENT_CHECKLIST.md)

---

## 部署指南

### 开发环境
1. 配置 `.env` 文件
2. 执行数据库迁移
3. 在沙箱环境测试

### 测试环境
1. 配置测试环境 `.env` 文件
2. 执行数据库迁移
3. 完整测试所有功能

### 生产环境
1. 获取生产密钥
2. 配置生产环境 `.env` 文件
3. 执行数据库迁移
4. 在生产环境测试
5. 上线

详见 [PAYMENT_DEPLOYMENT_CHECKLIST.md](./PAYMENT_DEPLOYMENT_CHECKLIST.md)

---

## 常见问题

### Q: 支付后订单状态没有更新？
A: 检查以下几点：
1. 回调地址是否正确配置
2. 防火墙是否允许回调
3. 签名验证是否通过
4. 查看后端日志

### Q: 签名验证失败？
A: 检查以下几点：
1. 密钥是否正确
2. 参数排序是否正确
3. 签名算法是否匹配
4. 查看后端日志

### Q: 如何测试支付功能？
A: 使用支付宝和微信提供的沙箱环境进行测试。

### Q: 如何处理支付失败？
A: 前端会显示错误提示，用户可以重新尝试支付。

### Q: 如何处理重复支付？
A: 通过订单号的唯一性约束和支付状态检查来防止重复支付。

详见 [PAYMENT_GATEWAY_INTEGRATION.md](./PAYMENT_GATEWAY_INTEGRATION.md)

---

## 文档索引

| 文档 | 说明 |
|------|------|
| [PAYMENT_QUICK_START.md](./PAYMENT_QUICK_START.md) | 5分钟快速开始指南 |
| [PAYMENT_GATEWAY_INTEGRATION.md](./PAYMENT_GATEWAY_INTEGRATION.md) | 完整的集成指南 |
| [PAYMENT_IMPLEMENTATION_SUMMARY.md](./PAYMENT_IMPLEMENTATION_SUMMARY.md) | 实现总结 |
| [PAYMENT_API_ENDPOINTS.md](./PAYMENT_API_ENDPOINTS.md) | API端点文档 |
| [PAYMENT_MIGRATION.md](./PAYMENT_MIGRATION.md) | 数据库迁移指南 |
| [PAYMENT_DEPLOYMENT_CHECKLIST.md](./PAYMENT_DEPLOYMENT_CHECKLIST.md) | 部署检查清单 |
| [PAYMENT_CHANGES_SUMMARY.md](./PAYMENT_CHANGES_SUMMARY.md) | 变更总结 |

---

## 技术栈

- **后端**: PHP 7.4+, ThinkPHP 6.0+
- **前端**: Vue 3, Element Plus
- **数据库**: MySQL 5.7+
- **支付网关**: 支付宝, 微信支付

---

## 安全建议

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

---

## 支持

如有问题，请参考相关文档或联系技术支持。

---

## 更新日志

### v1.0.0 (2024-01-01)
- ✅ 支付宝支付集成
- ✅ 微信支付集成
- ✅ 异步回调处理
- ✅ 完整文档

---

## 许可证

本项目遵循项目许可证。

---

**最后更新**: 2024-01-01
**维护者**: 开发团队