多模板游戏活动框架

// Condition：能否参与 / 单次行为是否计入
type Condition interface {
    // 校验玩家是否满足准入条件（等级、渠道、白名单……）
    Check(ctx *ActCtx, uid uint64) bool
}

// Progress：把一次业务事件转成进度增量并累积
type Progress interface {
    // 收到业务事件（登录/充值/击杀）时被调用，返回累积后的最新进度
    Accumulate(ctx *ActCtx, uid uint64, ev *Event) (cur int64, err error)
    // 查询当前进度（用于展示与领奖判定）
    Query(ctx *ActCtx, uid uint64) (cur int64, err error)
}

// Reward：按进度/档位计算并发放奖励
type Reward interface {
    // 校验某个奖励档位是否可领（达标 && 未领过）
    CanClaim(ctx *ActCtx, uid uint64, tier int32) (bool, error)
    // 幂等发放：内部走通用发奖能力，重复调用效果一致
    Grant(ctx *ActCtx, uid uint64, tier int32) (*GrantResult, error)
}

// 模板：注册进框架的玩法定义，全局仅一份
type Template struct {
    Name      string                       // "sign_in" / "cumulative_pay" / "exchange"
    NewCond   func(cfg *ActConfig) Condition
    NewProg   func(cfg *ActConfig) Progress
    NewReward func(cfg *ActConfig) Reward
}

// 实例：一份可热刷的活动配置（来自配置中心 / 配表）
type ActConfig struct {
    ActID    uint64         // 活动实例唯一 ID
    Template string         // 引用哪个模板
    Start    int64          // 开始时间（unix）
    End      int64          // 结束时间
    Enabled  bool           // 紧急开关，可热关
    Params   map[string]any // 玩法参数：档位表、准入条件、渠道白名单……
    Tiers    []RewardTier   // 奖励档位：{需要进度, 奖励包}
}

func (m *Manager) OnConfigReload(cfgs []*ActConfig) {
    next := make(map[uint64]*ActInstance, len(cfgs))
    for _, cfg := range cfgs {
        tpl, ok := m.templates[cfg.Template]
        if !ok {
            log.Errorf("act %d 引用了未注册模板 %s，跳过", cfg.ActID, cfg.Template)
            continue // 坏配置隔离：不让一份错配拖垮整个框架
        }
        inst := &ActInstance{
            cfg:    cfg,
            cond:   tpl.NewCond(cfg),
            prog:   tpl.NewProg(cfg),
            reward: tpl.NewReward(cfg),
        }
        next[cfg.ActID] = inst
    }
    m.instances.Store(next) // 原子替换，读侧无锁
}

// 通用发奖：以 (actID, uid, tier) 为幂等键，去重键 + 唯一索引 + 事务三重保证只发一次
func (g *CommonGranter) Grant(ctx *ActCtx, uid uint64, tier int32) (*GrantResult, error) {
    key := fmt.Sprintf("act:grant:%d:%d:%d", ctx.ActID, uid, tier)

    // 1) 防重复领取：SETNX 抢去重令牌，抢不到说明已发过，回放上次结果
    if !g.store.SetNXWithTTL(key, "1", ctx.grantTTL) {
        return g.loadGrantRecord(ctx.ActID, uid, tier) // 幂等：回放
    }

    // 2) 事务内写发奖流水 + 调发货，任一失败整体回滚
    res, err := g.store.Tx(func(tx Tx) (*GrantResult, error) {
        if exist, _ := tx.GetGrantRecord(ctx.ActID, uid, tier); exist != nil {
            return exist, nil // 双重保险：唯一索引兜住并发窗口
        }
        r, err := g.deposit.Send(ctx, uid, ctx.Tiers[tier].Pack) // 原子发货
        if err != nil {
            return nil, err
        }
        tx.SaveGrantRecord(ctx.ActID, uid, tier, r)
        return r, nil
    })
    if err != nil {
        g.store.Del(key) // 失败释放去重键，允许重试
        return nil, err
    }
    return res, nil
}

// 各玩法在 init 时把自己注册进框架，主流程零改动
func init() {
    RegisterTemplate(&Template{
        Name:      "invite_rebate", // 全新玩法：邀请返利
        NewCond:   func(c *ActConfig) Condition { return &channelCond{c} },
        NewProg:   func(c *ActConfig) Progress { return &inviteProg{c} }, // 只写"邀请计数"
        NewReward: func(c *ActConfig) Reward { return NewCommonReward(c) }, // 复用通用发奖
    })
}