跳到主要内容

PRD-013 排行榜系统

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

1. 背景与目标​

排行榜用于展示玩家/帮会实力并驱动竞争。当前存在并列名次跳动、跨服榜单延迟、赛季结算重复发奖等问题。本 PRD 统一榜单类型、计分、刷新、并列与结算。

2. 核心规则​

2.1 榜单类型​

榜单维度范围刷新
等级榜等级、经验本服实时
战力榜综合战力本服/跨服5 分钟
财富榜金币+元宝折算本服每小时
帮会榜帮会战力/资金本服每小时
竞技榜天梯积分跨服赛季
副本榜通关时间本服实时

2.2 计分与排序​

  • 主键排序 + 次键（时间/角色 ID）保证稳定。
  • 并列时按达到时间早者优先。
  • 榜单只展示前 100 名，自己的排名单独返回。
  • 角色改名/转职后榜单同步更新。

2.3 赛季​

  • 赛季周期 30/90 天，可配置。
  • 赛季结束冻结榜单，按名次发奖，邮件发放。
  • 新赛季重置积分，保留历史最高排名。

3. 服务端设计​

3.1 数据结构​

struct RankEntry {
    uint64_t role_id;
    uint64_t score;
    uint64_t tie_breaker; // 达到时间戳
    uint32_t rank;
};

struct RankBoard {
    uint32_t board_id;
    uint32_t season_id;
    std::vector<RankEntry> top;
    uint64_t update_time;
};

3.2 协议​

方向协议说明
C→SCS_RankQuery查询榜单
S→CSC_RankList前 100 + 自己排名
S→CSC_RankUpdate榜单变化推送
S→CSC_RankSeason赛季信息/结算

3.3 刷新策略​

  • 实时榜在数据变化时更新内存 Top N，异步落库。
  • 定时榜由定时任务全量重算，避免频繁写库。
  • 跨服榜由 MiniServer 汇总各服 Top N 后合并。
  • 榜单更新加版本号，客户端丢弃旧版本。

3.4 赛季结算​

  • 结算前 10 分钟停止变更，冻结榜单。
  • 按 role_id 发奖，幂等键 season_id + role_id。
  • 发奖失败进入补偿队列，邮件补发。
  • 结算后清理旧赛季缓存，保留归档。

4. 客户端设计​

  • 榜单页签切换，显示前 100、自己排名、刷新时间。
  • 自己不在前 100 时固定底部显示。
  • 名次前三使用特殊边框/头像框。
  • 赛季页显示剩余时间、奖励预览、历史最高。
  • 点击玩家可查看信息/加好友/私聊。

5. 配置​

Rank.xml：board_id、score_type、refresh_interval、season_days、reward_group、max_entries。

6. 边界与异常​

场景处理
分数相同按达到时间早者优先
角色删除下次刷新移除
跨服延迟显示“数据同步中”，不显示错误排名
赛季结算时在线邮件发奖，不强制下线
重复结算幂等，按 season_id 校验
榜单被刷异常分数告警，人工下榜

7. 验收标准​

  • 各榜单排序、并列、自己排名正确。
  • 定时/实时刷新符合配置。
  • 跨服榜单合并无重复/遗漏。
  • 赛季结算发奖幂等，无重复/漏发。
  • 客户端名次与服务端一致。