推荐返利 · 技术实现

玩家设定 →

「玩家设定 →」

1. 代码位置

层	类	职责
Controller	controller/ReferralController（/api/referral）	邀请码/绑定/收益/里程碑领取
Service	service/ReferralService	邀请码生成与绑定、佣金 10% 结算
Service	service/ReferralMilestoneService	里程碑奖励（月卡 200 / VIP5 500 / 冠名 1000 元宝）
domain	domain/ReferralRules	规则：COMMISSION_RATE_PERCENT=10、NAMING_UNLOCK_REQUIRED_COUNT=10（直推 10 人解锁冠名）、MONTHLY_CARD_REWARD=200、VIP5_REWARD=500、NAMING_REWARD=1000、VIP5_REQUIRED_LEVEL=5
domain	domain/ReferralRewardType、domain/ReferralRewardStatus	奖励类型与状态

2. 数据表

表	关键列	说明
player_referral	player_id、referral_code、inviter_id、bound_at	邀请关系（V36 初版 / V58 v2 重构）
referral_commission_log	player_id、amount、source、create_time	佣金流水（V58）
referral_milestone_reward	player_id、reward_type、status、claimed_at	里程碑奖励状态（V58）
vip_experience_change	player_id、delta、source、create_time	VIP 经验变动流水（V58，充值/奖励入账）

3. 配置与常量

• 返利规则：

  名称	数值	说明
  commissionRatePercentCOMMISSION_RATE_PERCENT	10	—
  namingUnlockRequiredCountNAMING_UNLOCK_REQUIRED_COUNT	10	—
  monthlyCardRewardMONTHLY_CARD_REWARD	200	—
  vip5RewardVIP5_REWARD	500	—
  namingRewardNAMING_REWARD	1_000	—
  vip5RequiredLevelVIP5_REQUIRED_LEVEL	5	—

  来源：emberfall-server/src/main/java/com/emberfall/domain/ReferralRules.java · commit 5916da43b88f343400acfdb20c97a5cc7927fdbd
• yml 键：referral.v2.enabled（默认 true，V58 v2 开关）

4. 数据流简述

注册后 POST /api/referral/bind 绑定邀请码写 player_referral。被邀请人充值元宝时，ReferralService 按 10% 佣金入账邀请人（referral_commission_log，经 vip_experience_change 同步 VIP 经验）。直推人数达 10 解锁冠名购买资格；里程碑奖励（月卡 200 / VIP5 500 / 冠名 1000 元宝）经 POST /api/referral/milestone/claim 领取写 referral_milestone_reward。

5. 已知差异

无（V58 referral v2 为现行实现）

6. 相关代码

• 冠名权（ReferralRules.NAMING_UNLOCK_REQUIRED_COUNT → NamingView）
• VIP 系统（VipExperienceService：经验入账）
• 商城（元宝 9202 发放）