ZYT/zyt
2
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

更新

Browse Source
This commit is contained in:
Your Name
2026-03-11 14:33:49 +08:00
parent 38ad60f4bb
commit 08dd9cd307
57 changed files with 9547 additions and 379 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin/PAYMENT_README.md
+402
View File
@@ -0,0 +1,402 @@
# 订单支付功能完整指南
## 📋 目录
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
**维护者**: 开发团队