388 lines
8.2 KiB
Markdown
388 lines
8.2 KiB
Markdown
# 支付与订单闭环实现指南
|
||
|
||
## 📦 已完成的前端实现
|
||
|
||
### 1. 支付 API 模块 (`app/api/payment/index.ts`)
|
||
|
||
提供统一的支付接口封装：
|
||
|
||
```typescript
|
||
import {
|
||
createWechatJsapiPay, // 微信 JSAPI 支付
|
||
createWechatH5Pay, // 微信 H5 支付
|
||
createWechatNativePay, // 微信 Native 扫码支付
|
||
createAlipayPay, // 支付宝网页支付
|
||
queryPayStatus, // 查询支付状态
|
||
detectPayEnvironment, // 检测支付环境
|
||
isWechatBrowser, // 检测微信浏览器
|
||
isAlipayBrowser // 检测支付宝浏览器
|
||
} from '@/api/payment'
|
||
```
|
||
|
||
### 2. 支付组件 (`app/components/payment/PaymentModal.vue`)
|
||
|
||
开箱即用的支付弹窗组件，支持：
|
||
- **微信 JSAPI** - 微信内置浏览器调起微信支付
|
||
- **微信 H5** - 非微信浏览器跳转微信H5支付页面
|
||
- **微信 Native** - 扫码支付，显示二维码
|
||
- **支付宝 WAP** - 跳转支付宝支付页面
|
||
- **余额支付** - 平台余额直接扣款
|
||
|
||
使用方式：
|
||
|
||
```vue
|
||
<template>
|
||
<PaymentModal
|
||
v-model:visible="payModalVisible"
|
||
:order-no="order.orderNo"
|
||
:order-id="order.orderId"
|
||
:pay-price="order.payPrice"
|
||
:available-methods="{ wechat: true, alipay: true, balance: false }"
|
||
@success="onPaySuccess"
|
||
/>
|
||
</template>
|
||
|
||
<script setup>
|
||
import PaymentModal from '@/components/payment/PaymentModal.vue'
|
||
|
||
const payModalVisible = ref(false)
|
||
|
||
function openPay(order) {
|
||
payModalVisible.value = true
|
||
}
|
||
|
||
function onPaySuccess(result) {
|
||
console.log('支付成功', result)
|
||
// 刷新订单列表等操作
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 3. 订单页面集成 (`app/pages/orders.vue`)
|
||
|
||
已完善 `goPay()`、`applyRefund()`、`cancelOrder()` 功能：
|
||
- 点击"去支付"打开支付弹窗
|
||
- 点击"申请退款"弹出确认框
|
||
- 点击"取消订单"弹出确认框
|
||
|
||
---
|
||
|
||
## 🔧 后端需要实现的接口
|
||
|
||
### 1. 微信 JSAPI 支付
|
||
|
||
```
|
||
POST /api/system/wx-jsapi-pay/unified-order
|
||
```
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"orderNo": "订单号",
|
||
"openId": "用户 OpenId",
|
||
"subject": "商品描述",
|
||
"body": "商品详情",
|
||
"totalAmount": 100, // 金额（分）
|
||
"returnUrl": "支付完成跳转URL"
|
||
}
|
||
```
|
||
|
||
**返回参数：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"prepayId": "预支付交易会话标识",
|
||
"codeUrl": "公众号 AppId",
|
||
"mwebUrl": "H5支付链接"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 微信 H5 支付
|
||
|
||
```
|
||
POST /api/system/wx-h5-pay/unified-order
|
||
```
|
||
|
||
**请求参数：** 同 JSAPI
|
||
**返回参数：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"mwebUrl": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 微信 Native 支付
|
||
|
||
```
|
||
POST /api/system/wx-native-pay/unified-order
|
||
```
|
||
|
||
**返回参数：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"codeUrl": "weixin://wxpay/bizpayurl?..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 支付宝网页支付
|
||
|
||
```
|
||
POST /api/system/alipay/unified-order
|
||
```
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"orderNo": "订单号",
|
||
"subject": "商品标题",
|
||
"body": "商品描述",
|
||
"totalAmount": 100, // 金额（元）
|
||
"returnUrl": "支付完成跳转URL"
|
||
}
|
||
```
|
||
|
||
**返回参数：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"paymentUrl": "https://openapi.alipay.com/gateway.do?..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 查询支付状态
|
||
|
||
```
|
||
GET /api/system/payment/query-status?orderNo=xxx
|
||
```
|
||
|
||
**返回参数：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"paid": true,
|
||
"payStatus": 1,
|
||
"orderStatus": 1,
|
||
"payTime": "2024-01-01 12:00:00",
|
||
"transactionId": "微信/支付宝交易号"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 取消订单
|
||
|
||
```
|
||
POST /api/system/order/cancel
|
||
```
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"orderId": 123
|
||
}
|
||
```
|
||
|
||
### 7. 申请退款
|
||
|
||
```
|
||
POST /api/system/order/refund
|
||
```
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"orderId": 123,
|
||
"reason": "退款原因"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 微信支付配置
|
||
|
||
### 1. 微信商户平台配置
|
||
|
||
登录 [微信商户平台](https://pay.weixin.qq.com)，获取以下信息：
|
||
|
||
| 配置项 | 说明 |
|
||
|--------|------|
|
||
| AppID | 公众号应用ID |
|
||
| MchID | 商户号 |
|
||
| API Key | APIv2 密钥 |
|
||
| APIv3 Key | APIv3 密钥 |
|
||
| 证书 | 商户证书（用于退款等敏感操作） |
|
||
| AppSecret | 公众号应用密钥 |
|
||
|
||
### 2. 后端配置示例
|
||
|
||
```yaml
|
||
# application.yml
|
||
wechat:
|
||
pay:
|
||
app-id: wx1234567890abcdef
|
||
mch-id: 1234567890
|
||
api-key: xxxxxxxx
|
||
api-v3-key: xxxxxxxx
|
||
notify-url: https://your-domain.com/api/payment/notify
|
||
refund-url: https://your-domain.com/api/payment/refund-notify
|
||
cert-path: /path/to/apiclient_cert.p12
|
||
```
|
||
|
||
### 3. JSAPI 支付配置
|
||
|
||
需要在微信公众平台配置：
|
||
- **JS接口安全域名** - 发起支付的页面域名
|
||
- **网页授权域名** - 用于获取 OpenId
|
||
|
||
---
|
||
|
||
## 🔐 支付宝配置
|
||
|
||
### 1. 支付宝开放平台配置
|
||
|
||
登录 [支付宝开放平台](https://open.alipay.com)，创建应用并获取：
|
||
|
||
| 配置项 | 说明 |
|
||
|--------|------|
|
||
| AppID | 应用ID |
|
||
| PrivateKey | 应用私钥 |
|
||
| AlipayPublicKey | 支付宝公钥 |
|
||
|
||
### 2. 后端配置示例
|
||
|
||
```yaml
|
||
# application.yml
|
||
alipay:
|
||
app-id: 2021000000000000
|
||
private-key: xxxxxxxx
|
||
alipay-public-key: xxxxxxxx
|
||
notify-url: https://your-domain.com/api/payment/alipay-notify
|
||
return-url: https://your-domain.com/api/payment/alipay-return
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 支付流程
|
||
|
||
### 微信 JSAPI 支付流程
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ 用户下单 │
|
||
└──────┬──────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ 后端创建订单 │
|
||
└──────┬──────┘
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ 前端调用 createWechatJsapiPay │
|
||
│ (传入 openId、订单信息) │
|
||
└──────┬────────────────────────────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ 后端统一下单 │
|
||
│ 返回 prepayId │
|
||
└──────┬──────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ 前端调起 │
|
||
│ WeixinJSBridge │
|
||
└──────┬──────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ 用户输入密码 │
|
||
│ 完成支付 │
|
||
└──────┬──────┘
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ 微信回调后端 + 前端轮询 queryPayStatus │
|
||
└──────┬────────────────────────────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ 显示支付成功 │
|
||
└─────────────┘
|
||
```
|
||
|
||
### 支付结果通知
|
||
|
||
后端需要实现支付结果回调：
|
||
|
||
```
|
||
POST /api/system/payment/notify (微信)
|
||
POST /api/system/payment/alipay-notify (支付宝)
|
||
```
|
||
|
||
收到回调后：
|
||
1. 验证签名
|
||
2. 更新订单状态
|
||
3. 返回 success 给支付方
|
||
|
||
---
|
||
|
||
## 🎯 快速开始
|
||
|
||
### 1. 完成后端接口
|
||
|
||
按照"后端需要实现的接口"章节实现各个支付接口。
|
||
|
||
### 2. 配置密钥
|
||
|
||
在微信商户平台和支付宝开放平台完成配置，获取必要的密钥。
|
||
|
||
### 3. 更新 API 路径
|
||
|
||
如果后端接口路径与设计不同，更新 `app/api/payment/index.ts` 中的接口路径。
|
||
|
||
### 4. 测试支付
|
||
|
||
1. 启动前端：`pnpm dev`
|
||
2. 登录后进入订单页面
|
||
3. 点击"去支付"测试支付流程
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 1. 金额单位
|
||
|
||
- **前端传给后端**：元（保留2位小数）或 分（整数）
|
||
- **微信/支付宝**：通常使用**分**
|
||
- 建议前端统一传元，后端转为分
|
||
|
||
### 2. 订单号
|
||
|
||
- 建议使用业务方生成的唯一订单号
|
||
- 避免重复支付
|
||
- 建议格式：`PAY + 时间戳 + 随机数`
|
||
|
||
### 3. 回调通知
|
||
|
||
- 必须实现支付结果回调
|
||
- 回调地址需要公网可访问
|
||
- 注意防止重复处理
|
||
|
||
### 4. 安全建议
|
||
|
||
- 所有支付相关接口需要登录验证
|
||
- 金额计算在后端完成
|
||
- 签名验证在前端不做，后端完成
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [微信支付开发文档](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)
|
||
- [支付宝支付文档](https://opendocs.alipay.com/open/270)
|
||
- [JSSDK 使用说明](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)
|