zyt/admin/PAYMENT_README.md

订单支付功能完整指南

📋 目录

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

---

快速开始

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

在 .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分钟)

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

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

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

详见 PAYMENT_QUICK_START.md

---

功能概述

支持的支付方式

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

支持的支付类型

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

订单状态流转

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

---

系统架构

后端架构

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

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

前端架构

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

数据流

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

---

配置指南

支付宝配置

获取密钥

1. 登录 支付宝开放平台
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. 登录 微信商户平台
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

---

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

---

测试指南

单元测试

// 测试支付宝签名
$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

---

部署指南

开发环境

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

测试环境

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

生产环境

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

详见 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_QUICK_START.md	5分钟快速开始指南
PAYMENT_GATEWAY_INTEGRATION.md	完整的集成指南
PAYMENT_IMPLEMENTATION_SUMMARY.md	实现总结
PAYMENT_API_ENDPOINTS.md	API端点文档
PAYMENT_MIGRATION.md	数据库迁移指南
PAYMENT_DEPLOYMENT_CHECKLIST.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 维护者: 开发团队