06 · 等级系统

0. 文档说明

项	内容
版本	V1.0

权益底座。07 俸禄档位、08 返水率、09 部分活动门槛、生日礼金额度都读用户等级。Global 租户实例 = 50 级(V1–V50),级数与门槛全由配置——引擎不关心具体级数。

口径(本位币单口径):一租户 = 一「本位币站」,站内全链路单币种(→ 00 架构总纲、02 货币与钱包系统)。等级是账号级身份,growthBase 只有一条、以本位币计价;门槛为本位币单表,账号一条成长进度、一个等级。记账单位 = 本位币 wallet.baseCurrency,驱动指标 = 累计充值,折算时点 = 充值单下单锁价(→ 03 §三.2bis 快照,复用充值边界既有能力)。

---

一、定位与职责

• 定义等级模型(级数/门槛/权益出口)与用户等级进度;
• 定义升级规则(只看累计充值,无打码要求)与保级/降级规则(与 07 联动);
• 对外提供等级查询、变更事件(LevelChanged)。

边界:各级俸禄金额归 07;各级返水率归 08;保级打码的进度推进归 10;本系统只裁决「用户现在是几级」。

---

二、核心概念与数据模型

2.1 等级定义 LevelDef(全配置)

字段	说明
level	级别序号(1..N,N 由配置决定;Global=50)
name / icon	展示名(V1…V50)、徽章
threshold	升级门槛 = 累计充值价值,单位恒 wallet.baseCurrency(本位币),只一张表(→ §3.1)
权益引用	俸禄(07)/ 返水率(08)/ 生日礼金 —— 数值存各自命名空间,此处仅出口

2.2 用户等级 UserLevel

字段	说明
userId / tenantId	归属
level	当前等级(账号唯一;站内单币种,单一本位币口径)
growthBase	本位币口径累计充值价值(账号一条;本位币充值原额累进,非本位币通道充值按该单下单锁价 lockedRate 折入本位币)
retentionFloor	降级锚点(本位币):上次降级时的 growthBase 快照;升级判定用增量 growthBase − retentionFloor(→ §3.3),防降级后旧余额自动弹回。从未降级=0
changeSeq	变更序号(LevelChanged 幂等键成分)

每笔折入都可审计:成长流水记录 orderId / 通道币种 / 通道金额 / lockedRate / 折入本位币值(§八 level_growth_log),口径与 03 订单快照一致(lockedRate 即 03 下单锁价,→ 03 §三.2bis)。

2.3 等级变更(事件)

LevelChanged { userId, fromLevel, toLevel, reason: UP / DOWN / ADJUST } —— 07(俸禄档位)、08(返水率)、16(通知)订阅。

---

三、业务规则

3.1 升级(即时,充值驱动,本位币单口径)

• 订阅 DepositSucceeded:
  • 通道币种 = 本位币 → growthBase += amount(原额,不折);
  • 通道币种 ≠ 本位币 → growthBase += amount × lockedRate(该笔订单下单时锁定的汇率 lockedRate,→ 03 §三.2bis 快照;非实时价、非商户系数)。例:CNY 站收 USDT 充值,按该充值单的 lockedRate 折入本位币成长值——这是充值边界锁价的合理用途,不是站内汇率;
• 等级 = growthBase 在唯一一张门槛表(本位币口径)中所达档位;账号只有一条进度、一个等级;存在降级锚点时(retentionFloor>0),判级改用增量口径 growthBase − retentionFloor,裁决取 max(当前级, 增量所达档位)(→ §3.3,防降级瞬间弹回、防旧余额跨多级回升);
• 达标即时升级(可跨多级,但降级后仅对「新增部分」计),发 LevelChanged(UP);升级无打码/投注要求;
• 晋级彩金的可领资格由 07 依据 LevelChanged 生成;
• 与 02 无换算铁律的关系:钱包余额永不换算、站内不出第二币种符号(02 不变);本折算发生在充值这一钱包边界事件上、且用的是该单已经发生过的锁价,growthBase 是运营统计口径而非资金,不构成站内汇率。

3.2 保级与降级(俸禄领取触发,与 07 联动)

• 未领取俸禄 → 无保级义务 → 不降级;
• 领取俸禄时,07 生成/累加保级义务:本保级周期内需完成「已领俸禄总额 × multiple(默认 10)」的打码量(10 按「租户+用户+周期」单条累加推进,→ 07 §2.3 / 10 §3.3);打码义务额恒以本位币计;
• 周期末(默认自然月,租户时区)检查:义务未达标 → 降 1 级(retention.demoteSteps,默认 1),发 LevelChanged(DOWN);达标或无义务 → 维持,不发事件(仅 UP/DOWN/ADJUST 三态产生 LevelChanged,无 KEEP);
• 降级只改判级等级、不回退 growthBase(累计充值是硬投入,不清零);降级同时落降级锚点 retentionFloor = 当前 growthBase 值(§3.3),后续升级判定以锚点为基准,防「降级瞬间被旧 growthBase 弹回」。

3.3 保级不回退(降级锚点 retentionFloor)

• 降级时记录 retentionFloor(= 降级那一刻的 growthBase);此后升级判定改用「增量口径」——有效成长 = growthBase − retentionFloor,等级 = 该增量在「门槛表相对当前级起点」所达档位,即必须在降级后新增充值达到「原门槛 − retentionFloor」的缺口才恢复原级(旧余额不自动弹回)。
• 单调不回退 + 无多级瞬跳:降级每次只降 demoteSteps(默认 1)级;恢复时按增量逐级达标即时升(可跨级,但只对「降级后新增部分」计),裁决取 max(当前级, 增量所达档位)——降级锚点只上调不下调,一次充值不因旧余额叠加而跨回多级。
• 晋级彩金每级终身一次(07 约束),降级-复升同一级不重复发放,关闭「降级-升级」套取。
• retentionFloor 随每次降级刷新为当次 growthBase;从未降级的用户 retentionFloor=0,升级口径 = 全量 growthBase(与首次入级一致)。

3.4 人工调整

后台可调整等级(工单+审计,reason=ADJUST),用于客诉补偿;调整同样触发权益档位联动。

---

四、★ 租户可配置项(level 命名空间)

"wallet": { "baseCurrency": "CNY" /* 本位币(01/02):站的唯一记账与展示币种,等级门槛与成长值口径 */ },
"level": {
  "maxLevel": 50,
  "startLevel": 1,
  "levels": [   // 数组整体替换(01 §4.2);门槛=本位币金额,只此一张表
    { "level": 18, "name": "V18", "threshold": "60000" },
    { "level": 19, "name": "V19", "threshold": "80000" }
    /* … 1..50 全量 */
  ],
  "retention": {
    "enabled": true,
    "wageringMultiple": 10,        // 保级打码 = 周期内已领俸禄总额 × 10(本位币)
    "period": "monthly",           // 保级周期(租户时区)
    "demoteSteps": 1               // 未达标降几级
  }
}

Schema 校验:levels 连续且 threshold 随级严格递增;门槛/成长值单位恒 wallet.baseCurrency(单币种站,天然唯一,无需配「口径展示模式」)。

---

五、与其他系统的关系 / 接口

接口	调用方	幂等键	说明
getLevel(userId)	07/08/09、展示层 /me	—	当前等级 + growthBase(本位币) + 距下一级进度% + 距下一级缺口金额(本位币)
adjustLevel(userId, toLevel, ticketId)	15 后台	工单号	人工调整
消费 DepositSucceeded	← 03	orderId	推进 growthBase、判升级(通道币种≠本位币按该单 lockedRate 折入)
消费「保级义务达标/未达标」	← 10(周期末结算)	义务ID	判降级
产 LevelChanged	→ 07/08/16	userId+changeSeq	档位联动

---

六、运营后台能力(→ 15)

侧	能力
平台控制台	等级模板(预设:8 级轻量版 / 50 级完整版…)
商户控制台	本站等级表编辑(级数/门槛/名称,单表·本位币口径,表头标注本位币);保级参数;用户等级查询与人工调整(工单);升降级流水查询(含非本位币充值折入明细 level_growth_log)

---

七、展示契约(→ 原型映射)

单币种站统一口径(本位币):等级/进度是身份视图,站内单币种,等级/进度/文案不换算、不跳变。

• 统一出「距 V19 还需充值 ¥62,000」金额文案(本位币,最强行动指引,无歧义);进度条 + 百分比同时可给(「V19 进度 48%」)。
• 禁止任何「数字不变只换符号」的重刷(→ 02 展示铁律);金额永远带本位币符号;进度展示统一走本位币金额文案单一路径。

UI 元素	数据	原型载体	系统契约
我的·VIP 条(头卡内)	当前级/进度%/缺口	.mh-vip:#me-vip-line(「距 V19 还需充值 ¥62,000」)	/me.vip.{level,progressPct,gapAmount};vipLineHTML() 单口径渲染(本位币)
VIP 俸禄页 hero 行	同上	#vip-sub 与 #me-vip-line 同源(vipLineHTML())	同上
VIP 等级表页	level.levels 50 级全表	VIP 俸禄页等级表(50 级)	全配置驱动;门槛单列,本位币口径,表头标注币种
等级徽章	name/icon	头部 V18 徽章	/me.vip.level

---

八、数据库设计(全表含 tenant_id;金额 DECIMAL(32,8))

表	关键字段	约束/索引
user_levels	tenant_id, user_id, level, growth_base(本位币口径累计), retention_floor(降级锚点·本位币,默认 0,→ §3.3), change_seq, updated_at	UK(tenant_id,user_id)
level_growth_log	id PK, tenant_id, user_id, order_id, channel_currency(通道币种), channel_amount, locked_rate(本位币充值=1), base_amount(折入本位币值), created_at	UK(tenant_id,order_id)幂等;IDX(tenant_id,user_id,created_at)
level_change_log	id PK, tenant_id, user_id, from_level, to_level, reason, ref(orderId/义务ID/工单号), created_at	IDX(tenant_id,user_id,created_at)

(成长表账号级单条——站内单币种,成长值一条本位币口径;非本位币通道充值的折算审计由 level_growth_log 承担。)

(保级义务实体在 10 的 wagering_obligations,source=RETENTION,币种恒本位币。)

---

九、扩展点

• 成长口径可插拔:V1 为充值制(growthBase 来源 = 充值单锁价);growthBase 来源可扩展为注单结算时价(流水制),属引擎能力扩展。
• 本位币变更:租户运营中途改 baseCurrency 需存量 growth_base 重算(按历史 level_growth_log 重放),属高危配置项——后台加二次确认 + 平台审批;首版锁定不可改。
• 降级缓冲:「宽限期/降级保护卡」类运营道具。

---

十、验收要点

• [ ] 充值成功即升级(可跨级),无任何打码前置;LevelChanged(UP) 仅发一次;
• [ ] 本位币充值原额累进 growth_base;非本位币通道充值按该单 lockedRate 折入且 level_growth_log 可对账(UK order_id 幂等,回调重放不重复累进);
• [ ] 站内单币种,等级/进度/徽章全程本位币,无换算、无第二币种符号、单一口径直出;
• [ ] 展示统一出「距 VN 还需充值 X」本位币金额文案(可并列进度条+百分比);全站无「数字不变只换符号」的重刷;
• [ ] 整月未领俸禄的用户月末不降级;领了俸禄且打码 < 10× 的用户月末降 1 级并有日志;
• [ ] 降级后落 retention_floor=当次 growth_base;降级用户任意小额充值不自动弹回原级,须新增充值补足「原门槛 − retention_floor」缺口才恢复;一次充值不因旧余额跨回多级(裁决取 max(当前级, 增量档位));LevelChanged 仅产生 UP/DOWN/ADJUST,保级维持不发事件(无 KEEP);
• [ ] 等级表改配置(如 50 级改 30 级)发布后,前端表格与权益档位同步变化;
• [ ] 人工调级必经工单,level_change_log.reason=ADJUST 且审计可查;
• [ ] VIP 文案统一充值口径,VIP 条/俸禄页 hero 为本位币缺口金额文案。