team/tyapi-frontend

Fork 0

Files

liangzai e57d497751 first commit

2025-11-24 16:06:44 +08:00

7.9 KiB

Raw Blame History

支付宝充值功能说明

功能概述

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

功能特性

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. 支付回调处理

异步回调：支付宝主动通知支付结果，用于更新订单状态和钱包余额
同步回调：用户支付完成后页面跳转，用于用户体验优化

数据库设计

1. 充值记录表 (recharge_records)

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)

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. 支付宝配置

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. 性能优化

支付订单缓存
异步处理优化
数据库查询优化
前端体验优化

7.9 KiB Raw Blame History Unescape Escape

支付宝充值功能说明

功能概述

功能特性

1. 前端功能

2. 后端功能

技术架构

前端架构

后端架构

API接口

1. 创建支付宝充值订单

2. 支付宝异步回调

3. 支付宝同步回调

4. 获取用户充值记录

支付流程

1. 用户充值流程

2. 支付回调处理

数据库设计

1. 充值记录表 (recharge_records)

2. 支付宝订单表 (alipay_orders)

配置说明

1. 支付宝配置

2. 环境配置

安全考虑

1. 支付安全

2. 数据安全

错误处理

1. 支付失败处理

2. 回调异常处理

监控和日志

1. 关键日志点

2. 监控指标

测试建议

1. 功能测试

2. 安全测试

部署注意事项

1. 环境配置

2. 监控告警

后续优化

1. 功能增强

2. 性能优化

7.9 KiB

Raw Blame History