295 lines
7.9 KiB
Markdown
295 lines
7.9 KiB
Markdown
|
# 支付宝充值功能说明
|
|||
|
|
|
|||
|
|
## 功能概述
|
|||
|
|
|
|||
|
|
本功能实现了完整的支付宝充值流程，从前端用户操作到后端支付处理，再到支付回调确认，形成了完整的闭环。
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
### 1. 前端功能
|
|||
|
|
- **钱包余额显示**：实时显示用户当前钱包余额和状态
|
|||
|
|
- **充值方式选择**：支持支付宝充值和对公转账两种方式
|
|||
|
|
- **支付宝充值表单**：用户输入充值金额，系统创建支付订单
|
|||
|
|
- **支付跳转**：自动跳转到支付宝支付页面
|
|||
|
|
- **支付结果页面**：
|
|||
|
|
- 支付成功页面：显示充值详情和操作按钮
|
|||
|
|
- 支付失败页面：显示失败原因和重试选项
|
|||
|
|
|
|||
|
|
### 2. 后端功能
|
|||
|
|
- **支付宝订单创建**：生成唯一订单号，创建支付宝支付订单
|
|||
|
|
- **异步回调处理**：处理支付宝支付成功通知，更新钱包余额
|
|||
|
|
- **同步回调处理**：处理用户支付完成后的页面跳转
|
|||
|
|
- **充值记录管理**：完整的充值记录创建、查询和管理
|
|||
|
|
- **事务保护**：确保充值过程的原子性和数据一致性
|
|||
|
|
|
|||
|
|
## 技术架构
|
|||
|
|
|
|||
|
|
### 前端架构
|
|||
|
|
```
|
|||
|
|
Wallet.vue (钱包页面)
|
|||
|
|
├── 余额显示
|
|||
|
|
├── 充值方式选择
|
|||
|
|
├── 支付宝充值表单
|
|||
|
|
└── 支付跳转逻辑
|
|||
|
|
|
|||
|
|
WalletSuccess.vue (支付成功页面)
|
|||
|
|
├── 成功状态显示
|
|||
|
|
├── 充值详情展示
|
|||
|
|
└── 操作按钮
|
|||
|
|
|
|||
|
|
WalletFail.vue (支付失败页面)
|
|||
|
|
├── 失败状态显示
|
|||
|
|
├── 失败原因说明
|
|||
|
|
└── 重试和客服选项
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 后端架构
|
|||
|
|
```
|
|||
|
|
FinanceHandler (HTTP处理器)
|
|||
|
|
├── CreateAlipayRecharge (创建充值订单)
|
|||
|
|
├── HandleAlipayCallback (异步回调处理)
|
|||
|
|
└── HandleAlipayReturn (同步回调处理)
|
|||
|
|
|
|||
|
|
FinanceApplicationService (应用服务)
|
|||
|
|
├── CreateAlipayRechargeOrder (业务流程编排)
|
|||
|
|
├── HandleAlipayCallback (回调处理)
|
|||
|
|
└── GetUserRechargeRecords (充值记录查询)
|
|||
|
|
|
|||
|
|
RechargeRecordService (充值记录服务)
|
|||
|
|
├── CreateAlipayRecharge (创建充值记录)
|
|||
|
|
├── CreateAlipayOrder (创建支付宝订单)
|
|||
|
|
└── HandleAlipayPaymentSuccess (支付成功处理)
|
|||
|
|
|
|||
|
|
AliPayService (支付宝服务)
|
|||
|
|
├── CreateAlipayOrder (创建支付订单)
|
|||
|
|
├── HandleAliPaymentNotification (回调验证)
|
|||
|
|
└── GenerateOutTradeNo (生成订单号)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API接口
|
|||
|
|
|
|||
|
|
### 1. 创建支付宝充值订单
|
|||
|
|
```
|
|||
|
|
POST /api/v1/finance/wallet/alipay-recharge
|
|||
|
|
Content-Type: application/json
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"amount": 100.00,
|
|||
|
|
"subject": "钱包充值 ¥100.00",
|
|||
|
|
"platform": "pc"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Response:
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "支付宝充值订单创建成功",
|
|||
|
|
"data": {
|
|||
|
|
"pay_url": "https://openapi.alipay.com/...",
|
|||
|
|
"out_trade_no": "202412011234567890",
|
|||
|
|
"amount": 100.00,
|
|||
|
|
"platform": "pc",
|
|||
|
|
"subject": "钱包充值 ¥100.00"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 支付宝异步回调
|
|||
|
|
```
|
|||
|
|
POST /api/v1/finance/alipay/callback
|
|||
|
|
Content-Type: application/x-www-form-urlencoded
|
|||
|
|
|
|||
|
|
支付宝回调参数...
|
|||
|
|
|
|||
|
|
Response: "success"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 支付宝同步回调
|
|||
|
|
```
|
|||
|
|
GET /api/v1/finance/alipay/return?out_trade_no=xxx&trade_no=xxx&trade_status=TRADE_SUCCESS&total_amount=100.00
|
|||
|
|
|
|||
|
|
Response: 302 Redirect to frontend success/fail page
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 获取用户充值记录
|
|||
|
|
```
|
|||
|
|
GET /api/v1/finance/wallet/recharge-records?page=1&page_size=10&recharge_type=alipay&status=success
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
|
|||
|
|
Response:
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "获取充值记录成功",
|
|||
|
|
"data": {
|
|||
|
|
"items": [...],
|
|||
|
|
"total": 50,
|
|||
|
|
"page": 1,
|
|||
|
|
"size": 10
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 支付流程
|
|||
|
|
|
|||
|
|
### 1. 用户充值流程
|
|||
|
|
1. 用户进入钱包页面，查看当前余额
|
|||
|
|
2. 选择"支付宝充值"方式
|
|||
|
|
3. 输入充值金额（最低1元）
|
|||
|
|
4. 点击"立即充值"按钮
|
|||
|
|
5. 前端调用后端创建充值订单接口
|
|||
|
|
6. 后端生成订单号，创建支付宝支付订单
|
|||
|
|
7. 返回支付链接给前端
|
|||
|
|
8. 前端自动跳转到支付宝支付页面
|
|||
|
|
9. 用户在支付宝完成支付
|
|||
|
|
10. 支付宝跳转回系统同步回调地址
|
|||
|
|
11. 后端处理同步回调，跳转到前端成功/失败页面
|
|||
|
|
12. 支付宝异步通知后端支付结果
|
|||
|
|
13. 后端处理异步回调，更新钱包余额和充值记录状态
|
|||
|
|
|
|||
|
|
### 2. 支付回调处理
|
|||
|
|
- **异步回调**：支付宝主动通知支付结果，用于更新订单状态和钱包余额
|
|||
|
|
- **同步回调**：用户支付完成后页面跳转，用于用户体验优化
|
|||
|
|
|
|||
|
|
## 数据库设计
|
|||
|
|
|
|||
|
|
### 1. 充值记录表 (recharge_records)
|
|||
|
|
```sql
|
|||
|
|
CREATE TABLE recharge_records (
|
|||
|
|
id VARCHAR(36) PRIMARY KEY,
|
|||
|
|
user_id VARCHAR(36) NOT NULL,
|
|||
|
|
amount DECIMAL(20,8) NOT NULL,
|
|||
|
|
recharge_type VARCHAR(20) NOT NULL,
|
|||
|
|
status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
|||
|
|
alipay_order_id VARCHAR(64) UNIQUE,
|
|||
|
|
transfer_order_id VARCHAR(64) UNIQUE,
|
|||
|
|
notes VARCHAR(500),
|
|||
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|||
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
|||
|
|
deleted_at TIMESTAMP NULL
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 支付宝订单表 (alipay_orders)
|
|||
|
|
```sql
|
|||
|
|
CREATE TABLE alipay_orders (
|
|||
|
|
id VARCHAR(36) PRIMARY KEY,
|
|||
|
|
recharge_id VARCHAR(36) NOT NULL UNIQUE,
|
|||
|
|
out_trade_no VARCHAR(64) NOT NULL UNIQUE,
|
|||
|
|
trade_no VARCHAR(64) UNIQUE,
|
|||
|
|
subject VARCHAR(200) NOT NULL,
|
|||
|
|
amount DECIMAL(20,8) NOT NULL,
|
|||
|
|
platform VARCHAR(20) NOT NULL,
|
|||
|
|
status VARCHAR(20) NOT NULL DEFAULT 'pending',
|
|||
|
|
buyer_id VARCHAR(64),
|
|||
|
|
seller_id VARCHAR(64),
|
|||
|
|
pay_amount DECIMAL(20,8),
|
|||
|
|
receipt_amount DECIMAL(20,8),
|
|||
|
|
notify_time TIMESTAMP NULL,
|
|||
|
|
return_time TIMESTAMP NULL,
|
|||
|
|
error_code VARCHAR(64),
|
|||
|
|
error_message TEXT,
|
|||
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|||
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 配置说明
|
|||
|
|
|
|||
|
|
### 1. 支付宝配置
|
|||
|
|
```yaml
|
|||
|
|
alipay:
|
|||
|
|
app_id: "2021004181633376"
|
|||
|
|
private_key: "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSj..."
|
|||
|
|
alipay_public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
|
|||
|
|
is_production: true
|
|||
|
|
notify_url: "https://console.tianyuanapi.com/api/v1/finance/alipay/callback"
|
|||
|
|
return_url: "https://console.tianyuanapi.com/api/v1/finance/alipay/return"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 环境配置
|
|||
|
|
- **开发环境**：使用沙箱环境，回调地址指向开发服务器
|
|||
|
|
- **生产环境**：使用正式环境，回调地址指向生产服务器
|
|||
|
|
|
|||
|
|
## 安全考虑
|
|||
|
|
|
|||
|
|
### 1. 支付安全
|
|||
|
|
- 使用支付宝官方SDK进行签名验证
|
|||
|
|
- 异步回调验证签名确保数据真实性
|
|||
|
|
- 订单号唯一性检查防止重复处理
|
|||
|
|
- 金额验证确保支付金额正确
|
|||
|
|
|
|||
|
|
### 2. 数据安全
|
|||
|
|
- 所有敏感操作使用事务保护
|
|||
|
|
- 充值记录状态变更的原子性
|
|||
|
|
- 钱包余额更新的并发控制
|
|||
|
|
- 完整的操作日志记录
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
### 1. 支付失败处理
|
|||
|
|
- 网络异常：提示用户重试
|
|||
|
|
- 余额不足：提示用户检查支付账户
|
|||
|
|
- 订单超时：自动取消订单，允许重新创建
|
|||
|
|
- 系统异常：记录错误日志，提供客服支持
|
|||
|
|
|
|||
|
|
### 2. 回调异常处理
|
|||
|
|
- 签名验证失败：记录异常，不处理回调
|
|||
|
|
- 重复回调：幂等性处理，避免重复更新
|
|||
|
|
- 数据不一致：记录异常，人工介入处理
|
|||
|
|
|
|||
|
|
## 监控和日志
|
|||
|
|
|
|||
|
|
### 1. 关键日志点
|
|||
|
|
- 充值订单创建
|
|||
|
|
- 支付宝回调接收
|
|||
|
|
- 支付成功处理
|
|||
|
|
- 钱包余额更新
|
|||
|
|
- 异常错误记录
|
|||
|
|
|
|||
|
|
### 2. 监控指标
|
|||
|
|
- 充值成功率
|
|||
|
|
- 支付响应时间
|
|||
|
|
- 回调处理延迟
|
|||
|
|
- 异常错误率
|
|||
|
|
|
|||
|
|
## 测试建议
|
|||
|
|
|
|||
|
|
### 1. 功能测试
|
|||
|
|
- 正常充值流程测试
|
|||
|
|
- 支付失败场景测试
|
|||
|
|
- 网络异常处理测试
|
|||
|
|
- 并发充值测试
|
|||
|
|
|
|||
|
|
### 2. 安全测试
|
|||
|
|
- 回调签名验证测试
|
|||
|
|
- 重复订单处理测试
|
|||
|
|
- 金额篡改防护测试
|
|||
|
|
- 并发安全测试
|
|||
|
|
|
|||
|
|
## 部署注意事项
|
|||
|
|
|
|||
|
|
### 1. 环境配置
|
|||
|
|
- 确保支付宝配置正确
|
|||
|
|
- 回调地址可访问性
|
|||
|
|
- 数据库连接稳定性
|
|||
|
|
- 日志存储空间充足
|
|||
|
|
|
|||
|
|
### 2. 监控告警
|
|||
|
|
- 支付成功率监控
|
|||
|
|
- 系统异常告警
|
|||
|
|
- 数据库性能监控
|
|||
|
|
- 网络连接监控
|
|||
|
|
|
|||
|
|
## 后续优化
|
|||
|
|
|
|||
|
|
### 1. 功能增强
|
|||
|
|
- 支持更多支付方式（微信支付、银行卡等）
|
|||
|
|
- 充值优惠活动
|
|||
|
|
- 自动充值功能
|
|||
|
|
- 充值提醒功能
|
|||
|
|
|
|||
|
|
### 2. 性能优化
|
|||
|
|
- 支付订单缓存
|
|||
|
|
- 异步处理优化
|
|||
|
|
- 数据库查询优化
|
|||
|
|
- 前端体验优化
|