跳到主要内容

PRD-012 签到与在线奖励

文档编号：PRD-012
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
关联模块：SessionServer/Activity.cpp、RecordServer、tbl/SignIn.xml

1. 背景与目标​

签到与在线奖励用于提升日活和留存。当前存在跨天重复领取、补签扣费不返还、在线计时被客户端伪造等问题。本 PRD 统一每日签到、累计签到、补签与在线时长奖励。

2. 核心规则​

2.1 每日签到​

  • 每日 0 点重置，按自然日计算（服务器时区）。
  • 签到获得固定奖励，连续签到额外加成。
  • 断签后连续天数重置，累计天数保留。
  • 每月 1 日重置月度签到面板。

2.2 累计签到​

  • 累计 7/14/21/28 天领取阶段奖励。
  • 累计天数只增不减，补签计入累计。
  • 阶段奖励每周期只能领取一次。

2.3 补签​

  • 当月漏签可补，消耗补签道具/元宝。
  • 补签只能补当月，不能补未来。
  • 补签后连续天数按时间顺序重算。

2.4 在线奖励​

  • 每日累计在线 15/30/60/120 分钟领取奖励。
  • 在线计时以服务端心跳为准，客户端只显示。
  • 跨天在线时长清零，未领取奖励不保留。

3. 服务端设计​

3.1 数据结构​

struct SignInState {
    uint32_t year, month;
    uint32_t signed_days;      // 位图或列表
    uint32_t continuous_days;
    uint32_t total_days;
    uint32_t last_sign_day;
};

struct OnlineReward {
    uint32_t role_id;
    uint32_t online_seconds;
    uint32_t claimed_mask;
    uint32_t last_heartbeat;
};

3.2 协议​

方向协议说明
C→SCS_SignIn每日签到
C→SCS_SignMakeup补签
C→SCS_SignInfo签到面板
C→SCS_OnlineReward领取在线奖励
S→CSC_SignInfo签到状态
S→CSC_SignResult签到/补签结果
S→CSC_OnlineProgress在线时长进度

3.3 跨天与防重​

  • 以服务端 day_key（YYYYMMDD）判断，不信任客户端日期。
  • 签到按 role_id + day_key 唯一索引，重复请求幂等。
  • 补签事务：扣道具 + 标记签到 + 重算连续天数。
  • 在线时长每 60 秒落库一次，掉线保留当日已累计。

4. 客户端设计​

  • 签到日历：本月天数、已签/未签/可补签状态。
  • 连续签到进度条与阶段奖励预览。
  • 补签弹窗显示消耗与可补日期。
  • 在线奖励悬浮入口显示当前时长/下一档。
  • 领取成功后播放奖励飞入动画。

5. 配置​

SignIn.xml：day、reward_group、continuous_bonus、total_reward、makeup_cost。
OnlineReward.xml：minutes、reward_group。

6. 边界与异常​

场景处理
跨天 0 点在线在线时长清零，签到面板刷新
重复签到幂等，返回已签到
补签已签日期拒绝
补签道具不足拒绝，不标记
服务器时区变更以配置时区为准，记录告警
客户端改本地时间无效，全部用服务端时间

7. 验收标准​

  • 每日签到/累计/补签/在线奖励正确。
  • 跨天、跨月重置与连续天数计算正确。
  • 重复请求、改本地时间无法重复领取。
  • 补签扣费与标记事务一致。
  • 客户端日历/进度与服务端一致。