全栈攻城狮

Appearance

活动系统框架 ​

概述 ​

活动是运营的"发动机"：节日冲榜、限时折扣、转盘抽奖，都是同一个框架下的不同实例。活动系统的核心价值是配置化：运营不依赖发版即可上线/下线活动。难点集中在时间段管理（精确到秒的启停）、分组与排期（活动不能互相冲突）、条件与奖励（达成判定与发奖幂等）。本文设计完整的活动框架。

一、活动模板与配置化 ​

1.1 活动模板 ​

ActivityTemplate（模板定义，代码层）：
  每个模板 = 一种活动玩法（冲榜/累充/转盘/签到活动）
  模板提供：条件判定、进度存储、奖励发放的标准接口
  新活动 = 模板实例 + 配置数据，不改代码
常见模板：
  RANK_RUSH      冲榜赛（基于排行榜）
  RECHARGE_BONUS 累计充值返利
  LOGIN_REWARD   登录送（活动期）
  TURN_TABLE     转盘抽奖（复用抽卡系统）
  DAILY_QUEST    活动任务（复用任务系统）
  GROWTH_PLAN    成长计划（达成等级领奖）

1.2 活动配置 ​

ActivityConfig（配置表/Json）：
  activityId、templateId
  name、banner、description
  startTime、endTime（精确到秒）
  groupId（活动分组）
  conditions（参与条件：等级/充值/VIP）
  rewards（奖励配置：档位/条件 → 奖励）
  extend（模板扩展参数 Json）
配置下发：
  运营后台配置 → 配置中心 → 游戏服热加载
  活动启停不重启服务
  配置版本管理，可回滚

二、时间段管理 ​

2.1 活动生命周期 ​

活动状态机：
  UPCOMING（未开始）→ RUNNING（进行中）
  → ENDED（已结束）→ CLEANED（已清理）

状态判定：
  启动时加载活动配置
  定时任务/时间检查切换状态
  按服务器时间（统一时区）
// 活动状态实时判定（不依赖定时器精度）
boolean isRunning(ActivityConfig cfg) {
    long now = System.currentTimeMillis();
    return now >= cfg.getStartTime() && now < cfg.getEndTime();
}

2.2 启停控制 ​

动态开启：
  活动到点自动开启（无需人工）
  可提前开启/延长（运营手动操作）
  关闭前预告（倒计时展示）

关闭处理：
  到点关闭 → 停止参与入口
  进行中数据保留（结算/领取窗口）
  彻底清理（见活动数据清理）
边界问题：
  结算类活动：结束瞬间的排名以冻结榜为准
  领取窗口：结束后的 N 天仍可领（宽限期）
  防止"最后一秒"刷数据 → 提前锁榜

三、活动分组与排期 ​

3.1 分组 ​

分组维度：
  按玩法：充值组/对战组/社交组
  按面向：全服/新服/回归玩家
  按周期：常驻/限时/节假日

作用：
  同组互斥（同组活动不同时开，避免奖励叠爆）
  奖励预算管控（按组设预算）
  客户端按组展示入口

3.2 排期 ​

排期表：
  活动按时间轴排布（startTime/endTime）
  检查同组重叠（配置时校验）
  关键节点（节日/版本更新）集中投放

校验规则：
  同一模板不重叠（防刷）
  同组活动预算不超限
  奖励配置合法（价值不溢出）

四、活动条件与达成奖励 ​

4.1 参与条件 ​

条件类型：
  等级条件（≥N 级）
  充值条件（累计充值 ≥N）
  时间条件（活动期内登录/对局）
  复合条件（等级 + 活跃）

判定：
  参与入口处校验
  条件不满足 → 隐藏/置灰 + 引导

4.2 达成奖励 ​

达成判定：
  冲榜：排名区间（复用排行榜结算）
  累充：充值累计达到档位
  任务式：进度达到目标（复用任务系统）

发奖：
  复用邮件/货币/道具统一发放接口
  幂等（activityId + playerId + 档位去重）
  领取窗口：活动结束 + N 天
// 档位奖励幂等领取
@Transactional
public ClaimResult claimTier(long playerId, long activityId, int tier) {
    // 校验活动进行中/宽限期内
    // UPDATE activity_reward SET claimed=1
    //  WHERE activity_id=? AND player_id=? AND tier=? AND claimed=0
    // 影响行数=1 → 发奖
}

五、实现要点 ​

核心接口：
  loadConfig(activityId)                // 配置加载
  getStatus(activityId)                 // 活动状态
  participate(playerId, activityId)     // 参与入口校验
  claimReward(playerId, activityId, tier)
  settleActivity(activityId)            // 结束结算
工程注意：
  配置热更新（活动启停无需重启）
  活动状态按时间判定（定时器只做辅助）
  奖励发放统一走经济接口
  活动数据按 activityId 隔离
常见坑：
  时间边界竞态 → 统一服务器时间 + 宽限期
  活动重叠奖励叠爆 → 分组互斥 + 预算校验
  配置错误影响线上 → 版本管理 + 灰度
  结束未清理 → 数据清理任务兜底
与其他系统衔接：
  冲榜活动 → 排行榜系统
  累充活动 → 货币系统（充值回调）
  活动任务 → 任务系统
  奖励 → 邮件/道具系统