tyapi-frontend/docs/支付宝充值功能说明.md

# 支付宝充值功能说明

## 功能概述

本功能实现了完整的支付宝充值流程，从前端用户操作到后端支付处理，再到支付回调确认，形成了完整的闭环。

## 功能特性

### 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. 性能优化
- 支付订单缓存
- 异步处理优化
- 数据库查询优化
- 前端体验优化