架构实战：电商直播系统中的推荐关系防环与分销佣金状态机设计

// 校验推荐关系是否合法（防环路检测与越级覆盖拦截）
func ValidateAndBindInviter(db *gorm.DB, currentUserID uint64, proposedInviterID uint64) error {
    if currentUserID == proposedInviterID {
        return errors.New("禁止自我绑定")
    }

    // 1. 检查是否已经绑定过上级
    var existRelation UserRelation
    if err := db.Where("user_id = ?", currentUserID).First(&existRelation).Error; err == nil {
        return errors.New("当前用户已存在推荐关系，禁止覆盖")
    }

    // 2. 向上溯源，进行防环检测 (Anti-Loop)
    checkID := proposedInviterID
    maxDepth := 10 // 限制最大溯源深度，防止异常死循环
    for i := 0; i < maxDepth; i++ {
        var parent UserRelation
        err := db.Where("user_id = ?", checkID).First(&parent).Error
        if err != nil {
            break // 溯源到顶级，无环路，安全
        }
        if parent.InviterID == currentUserID {
            return errors.New("检测到循环推荐关系，绑定失败")
        }
        checkID = parent.InviterID
    }

    // 3. 校验通过，执行绑定入库...
    return nil
}

// 佣金记录表结构：引入规则快照，确保历史订单不可变
type CommissionRecord struct {
    ID                  uint64         `gorm:"primaryKey"`
    OrderID             uint64         `gorm:"index"`
    BeneficiaryUserID   uint64         `gorm:"index"` // 受益人ID
    CommissionLevel     int            // 层级：1为直推，2为间推
    BaseAmount          decimal.Decimal // 参与分润的订单基数金额
    RateSnapshot        decimal.Decimal // 核心：下单当时的佣金比例快照 (如 0.05 代表 5%)
    ExpectedCommission  decimal.Decimal // 预计收益
    Status              int            // 状态：1冻结 2已结算 3已失效
    CreatedAt           time.Time
}

// 定时任务：将超过售后期的冻结佣金转为可用
func SettleFrozenCommissions(db *gorm.DB) error {
    // 获取当前时间减去售后期（如 7 天）的时间戳
    safeTime := time.Now().Add(-7 * 24 * time.Hour)

    return db.Transaction(func(tx *gorm.DB) error {
        // 查找所有关联订单已完成、且超过售后期的冻结佣金记录
        var records []CommissionRecord
        if err := tx.Joins("JOIN orders ON orders.id = commission_records.order_id").
            Where("commission_records.status = 1"). // 1: 冻结中
            Where("orders.status = 'COMPLETED'").
            Where("orders.completed_at <= ?", safeTime).
            Find(&records).Error; err != nil {
            return err
        }

        for _, record := range records {
            // 1. 将记录状态置为已结算
            tx.Model(&record).Update("status", 2) 
            // 2. 将金额真正累加到用户的可用钱包余额中
            tx.Exec("UPDATE wallets SET available_balance = available_balance + ? WHERE user_id = ?", record.ExpectedCommission, record.BeneficiaryUserID)
        }
        return nil
    })
}

// 处理订单退款时的佣金逆向冲正逻辑
func ReverseCommissionOnRefund(tx *gorm.DB, orderID uint64, refundAmount decimal.Decimal) error {
    var records []CommissionRecord
    if err := tx.Where("order_id = ? AND status IN (1,2)", orderID).Find(&records).Error; err != nil {
        return err
    }

    for _, record := range records {
        if record.Status == 1 {
            // 冻结状态：直接将该笔佣金置为失效(3)
            if err := tx.Model(&record).Update("status", 3).Error; err != nil {
                return err
            }
        } else if record.Status == 2 {
            // 已结算状态：生成负数红字冲正流水，并扣减可用余额
            reversalLog := CommissionLog{
                UserID: record.BeneficiaryUserID,
                Amount: record.ExpectedCommission.Neg(), // 取负值
                Reason: "订单退款，佣金红字冲正",
                RefID:  orderID,
            }
            tx.Create(&reversalLog)
            tx.Exec("UPDATE wallets SET available_balance = available_balance - ? WHERE user_id = ?", record.ExpectedCommission, record.BeneficiaryUserID)
        }
    }
    return nil
}

// 后端 API：聚合查询用户分销资产流水及其来源溯源
func GetCommissionLedgerTrace(db *gorm.DB, userID uint64) ([]LedgerTraceDTO, error) {
    var traceList []LedgerTraceDTO
    
    // 联合查询：流水表 + 佣金快照表 + 订单表
    err := db.Table("commission_logs cl").
        Select("cl.amount, cl.reason, cl.created_at, o.order_sn, cr.rate_snapshot, u.nickname as buyer_name").
        Joins("LEFT JOIN commission_records cr ON cl.ref_id = cr.id").
        Joins("LEFT JOIN orders o ON cr.order_id = o.id").
        Joins("LEFT JOIN users u ON o.buyer_id = u.id").
        Where("cl.user_id = ?", userID).
        Order("cl.created_at DESC").
        Scan(&traceList).Error

    return traceList, err
}