403 lines
8.9 KiB
Markdown
403 lines
8.9 KiB
Markdown
# 订单支付功能完整指南
|
||
|
||
## 📋 目录
|
||
|
||
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
|
||
**维护者**: 开发团队
|