tyapi-server/docs/支付宝充值赠送功能说明.md

支付宝充值赠送功能说明

功能概述

本功能实现了支付宝充值的自动赠送机制，根据充值金额自动计算并赠送相应的金额到用户钱包。

赠送规则

当前配置的赠送规则如下：

充值金额	赠送金额	说明
1000元	50元	充值1000元及以上，赠送50元
5000元	300元	充值5000元及以上，赠送300元
10000元	800元	充值10000元及以上，赠送800元

注意：赠送规则按充值金额从高到低匹配，即充值金额满足多个条件时，按最高档次的赠送金额计算。

配置说明

1. 配置文件位置

• 主配置文件：config.yaml
• 环境配置文件：configs/env.*.yaml

2. 配置结构

wallet:
  default_credit_limit: 50.00
  # 支付宝充值赠送配置
  alipay_recharge_bonus:
    - recharge_amount: 1000.00  # 充值1000元
      bonus_amount: 50.00       # 赠送50元
    - recharge_amount: 5000.00  # 充值5000元
      bonus_amount: 300.00      # 赠送300元
    - recharge_amount: 10000.00 # 充值10000元
      bonus_amount: 800.00      # 赠送800元

3. 配置结构体

type WalletConfig struct {
    DefaultCreditLimit float64                    `mapstructure:"default_credit_limit"`
    AliPayRechargeBonus []AliPayRechargeBonusRule `mapstructure:"alipay_recharge_bonus"`
}

type AliPayRechargeBonusRule struct {
    RechargeAmount float64 `mapstructure:"recharge_amount"` // 充值金额
    BonusAmount    float64 `mapstructure:"bonus_amount"`    // 赠送金额
}

实现逻辑

1. 赠送金额计算

在 calculateAlipayRechargeBonus 函数中实现：

func calculateAlipayRechargeBonus(rechargeAmount decimal.Decimal, walletConfig *config.WalletConfig) decimal.Decimal {
    if walletConfig == nil || len(walletConfig.AliPayRechargeBonus) == 0 {
        return decimal.Zero
    }

    // 按充值金额从高到低排序，找到第一个匹配的赠送规则
    // 由于配置中规则是按充值金额从低到高排列的，我们需要反向遍历
    for i := len(walletConfig.AliPayRechargeBonus) - 1; i >= 0; i-- {
        rule := walletConfig.AliPayRechargeBonus[i]
        if rechargeAmount.GreaterThanOrEqual(decimal.NewFromFloat(rule.RechargeAmount)) {
            return decimal.NewFromFloat(rule.BonusAmount)
        }
    }

    return decimal.Zero
}

2. 充值成功处理

在 HandleAlipayPaymentSuccess 方法中实现：

1. 计算赠送金额：根据充值金额计算应赠送的金额
2. 创建赠送记录：如果有赠送金额，创建一条赠送类型的充值记录
3. 更新钱包余额：将充值金额和赠送金额的总和添加到用户钱包

// 计算充值赠送金额
bonusAmount := calculateAlipayRechargeBonus(amount, &s.cfg.Wallet)
totalAmount := amount.Add(bonusAmount)

// 如果有赠送金额，创建赠送充值记录
if bonusAmount.GreaterThan(decimal.Zero) {
    giftRechargeRecord := entities.NewGiftRechargeRecord(rechargeRecord.UserID, bonusAmount, "充值活动赠送")
    _, err = s.rechargeRecordRepo.Create(txCtx, *giftRechargeRecord)
    if err != nil {
        s.logger.Error("创建赠送充值记录失败", zap.Error(err))
        return err
    }
}

// 使用钱包聚合服务更新钱包余额（包含赠送金额）
err = s.walletService.Recharge(txCtx, rechargeRecord.UserID, totalAmount)

数据库记录

1. 充值记录表 (recharge_records)

每次支付宝充值成功会产生两条记录：

1. 支付宝充值记录：

   • recharge_type: "alipay"
   • amount: 实际充值金额
   • status: "success"

2. 赠送充值记录（如果有赠送）：

   • recharge_type: "gift"
   • amount: 赠送金额
   • notes: "充值活动赠送"
   • status: "success"

2. 钱包余额

钱包余额会更新为：原余额 + 充值金额 + 赠送金额

测试用例

1. 单元测试

运行测试命令：

go test ./internal/domains/finance/services -v

测试覆盖的场景：

• 充值500元，无赠送
• 充值1000元，赠送50元
• 充值2000元，赠送50元
• 充值5000元，赠送300元
• 充值8000元，赠送300元
• 充值10000元，赠送800元
• 充值15000元，赠送800元

2. 配置测试

运行配置测试：

go test ./internal/config -v

验证配置文件中的赠送规则是否正确加载。

日志记录

系统会记录详细的日志信息：

支付宝支付成功回调处理成功
- user_id: 用户ID
- recharge_amount: 充值金额
- bonus_amount: 赠送金额
- total_amount: 总金额（充值+赠送）
- out_trade_no: 支付宝订单号
- trade_no: 支付宝交易号
- recharge_id: 充值记录ID
- order_id: 支付宝订单ID

扩展说明

1. 添加新的赠送规则

在配置文件中添加新的规则：

wallet:
  alipay_recharge_bonus:
    - recharge_amount: 1000.00
      bonus_amount: 50.00
    - recharge_amount: 5000.00
      bonus_amount: 300.00
    - recharge_amount: 10000.00
      bonus_amount: 800.00
    - recharge_amount: 20000.00  # 新增规则
      bonus_amount: 2000.00      # 充值20000元赠送2000元

2. 修改赠送规则

直接修改配置文件中的 recharge_amount 和 bonus_amount 值即可。

3. 禁用赠送功能

将配置文件中的 alipay_recharge_bonus 设置为空数组：

wallet:
  alipay_recharge_bonus: []

注意事项

1. 事务保护：所有数据库操作都在事务中执行，确保数据一致性
2. 重复处理防护：系统会检查订单状态，避免重复处理
3. 精确计算：使用 decimal.Decimal 进行金额计算，避免浮点数精度问题
4. 日志记录：详细记录所有操作，便于问题排查
5. 配置热更新：修改配置后需要重启服务才能生效