07 · VIP 俸禄系统

0. 文档说明

项	内容
版本	V1.0

「王者俸禄」形态:头部 + 4 张俸禄卡 + 等级额度表。档位读 06 等级;领取入账走 02;保级打码由 10 推进。
一租户 = 一「本位币站」,站内单币种(→ 00 架构总纲)。俸禄额、领取到账、晋级彩金、保级义务口径恒为本位币 wallet.baseCurrency;站内只有一个钱包,就是本位币钱包(= 站币钱包),领取的即是本位币俸禄。

一、定位与职责

定义 4 类俸禄:日俸禄 / 周俸禄 / 月俸禄(周期制)+ 晋级彩金(每级一次);
定义各俸禄的周期、领取窗口、过期规则与领取状态机;
定义保级义务的生成(领取才产生,10× 已领总额);
定义 50 级额度配置(单表,本位币口径,→ 06)与展示契约(4 卡 + 等级表 + 规则页)。

边界:等级裁决与降级归 06;打码进度归 10;红点聚合归 /me。

二、核心概念与数据模型

2.1 俸禄周期实例 SalaryCycle(用户 × 类型 × 期号)

字段	说明
`userId` / `tenantId` / `cycleType`	`DAILY / WEEKLY / MONTHLY`
`cycleNo`	期号(如 `2026-07-13` / `2026-W29` / `2026-07`,租户时区切期)
`amount` / `currency`	本期额度 = 领取时点等级在本位币单表中的配置额;`currency` 恒 = `wallet.baseCurrency`(→ §3.2)
`state`	见状态机

 等级达标且本期未领                领取(claim)
 ● ──► AVAILABLE(可领取) ──────────► CLAIMED(已领取·倒计时下期)
            │                            (REWARD_CREDIT / BONUS_GRANT + 保级义务)
            │本期结束未领
            ▼
        EXPIRED(过期作废·倒计时下期)          [等级不足整卡 LOCKED,不产生实例]

2.2 晋级彩金 UpgradeBonus

LevelChanged(UP) 触发生成可领资格:每级终身一次(UK 约束,防降级-升级套取);领取窗口 upgradeWindowDays(默认 30 天)过期作废;额度恒本位币。

2.3 保级义务(生成方,累加语义)

领取任一俸禄成功后:本保级周期(06 retention.period)的义务额 required += 领取额 × retention.wageringMultiple(默认 10);落到 10 的 wagering_obligations(source=RETENTION, ref=保级周期键),币种恒本位币。

单条累加:同一保级周期(如 ref=2026-07)内多次领取俸禄,不新建义务,而是对该周期唯一一条 RETENTION 义务 required 累加——通过 10 的 upsert 接口 addObligationRequired(source, ref, deltaRequired) 实现(存在即累加、不存在即建),UK(tenant_id,source,ref) 保证周期内单条、required 可增量更新(→ 10 §3.3、10 §五)。
例:某周期先领日俸禄 128 → required=1,280;再领周俸禄 288 → required=1,280+2,880=4,160(同一条累加,非两条)。
不领取 = 不产生义务 = 不降级。

三、业务规则

3.1 领取

前置:vipSalary.enabled、等级 ≥ 该俸禄起始级、本期未领、风控 PASS(14);
入账:按 rewardTarget 走 REWARD_CREDIT(默认,直入可用)或 BONUS_GRANT(带打码解锁);幂等键 = claimId(用户+类型+期号派生);
发 RewardClaimed(source=VIP_SALARY);红点即时更新(/me.badges.salary);
累加保级义务(§2.3):调 10 addObligationRequired(RETENTION, 周期键, 领取额×multiple)——同周期已存在即 required 累加,首次即建;领取事务与义务累加同事务提交。

3.2 额度取值

额度 = 领取时点的等级在本位币单表中的配置额(期中升级按新等级领);
发放入本位币钱包(站内单币种,本位币钱包即站的唯一钱包;等级与俸禄同属身份体系,口径统一 = wallet.baseCurrency);
同一期只能领一次;单币种站领的就是本位币俸禄,入本位币钱包,口径唯一无套利空间。

3.3 周期与过期

按租户时区切期;本期未领过期作废不补发;过期后卡片显示下期倒计时。

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

jsonc

"vipSalary": {
  "enabled": true,
  "cycles": { "daily": true, "weekly": true, "monthly": true, "upgrade": true },
  "rewardTarget": "available",          // available | bonus(bonus 时附打码倍数)
  "bonusWageringMultiple": 1,
  "upgradeWindowDays": 30,
  "minLevel": { "daily": 3, "weekly": 5, "monthly": 8, "upgrade": 1 },   // 各卡起领等级
  "levels": [   // 1..50 全量;金额=本位币单表(单位 wallet.baseCurrency,→ 06;站内单币种,不分列)
    { "level": 18, "daily": "128", "weekly": "288", "monthly": "1288", "upgrade": "268" }
    /* … */
  ]
}

保级参数在 level.retention(06),本系统读取执行。Schema 校验:levels 覆盖 1..level.maxLevel;金额随级不降;金额单位恒为 wallet.baseCurrency(校验其存在)。

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

接口	调用方	幂等键	说明
`getSalaryPanel(userId)`	展示层	—	4 卡状态 + 本期额度(本位币)+ 各自倒计时 + 等级表(本位币单表)
`claim(userId, cycleType, cycleNo)`	展示层	`claimId`	领取(§3.1 全链路)
消费 `LevelChanged`	← 06	changeSeq	UP:生成晋级彩金资格、刷新档位;DOWN:仅刷新档位
产 `RewardClaimed`	→ 02/13/14/16	claimId	入账与留痕(本位币)
累加保级义务 `addObligationRequired(RETENTION, 周期键, delta)`	→ 10	source+ref(周期键)	同周期 `required` 累加 upsert(不新建),本位币(→ 10 §3.3)

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

侧	能力
平台控制台	俸禄模板(与等级模板配套)
商户控制台	各级各卡额度编辑(单表·本位币口径,表头标注 `wallet.baseCurrency`)、起领等级、周期开关、`rewardTarget`;发放统计(成本口径→17);异常领取查询(配合 14)

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

UI 元素	数据	原型载体	系统契约
俸禄页头部	当前等级/权益概要	王者俸禄式 header	`/me.vip` + 面板接口
4 张俸禄卡	类型/本期额度/状态/倒计时	日/周/月俸禄+晋级彩金卡,按钮态(可领=绿/已领+倒计时=灰/等级不足=锁)	`getSalaryPanel`;额度恒本位币(站内单币种,身份视图);状态机四态直映按钮
等级额度表	`vipSalary.levels`(本位币单列)	50 级表格(V18 高亮)	全配置驱动;当前级行高亮;金额单列本位币,表头标注币种
规则页	升级/保级/过期规则	`#sub-vip-rules`(升级=充值、保级=10×已领打码、未领不降级、过期作废)	规则文案与 `retention` 配置联动渲染(倍数取配置值)
奖励 tab 红点	任一卡 AVAILABLE	领取后红点即时变	`/me.badges.salary` = AVAILABLE 卡数

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

表	关键字段	约束/索引
`salary_claims`	`claim_id` PK, `tenant_id`, `user_id`, `cycle_type`, `cycle_no`, `level_at_claim`, `currency`(恒本位币), `amount`, `state`(CLAIMED/EXPIRED 落账留痕), `created_at`	UK(`tenant_id`,`user_id`,`cycle_type`,`cycle_no`);IDX(`tenant_id`,`created_at`)
`upgrade_bonus_claims`	`id` PK, `tenant_id`, `user_id`, `level`, `currency`(恒本位币), `amount`, `state`(AVAILABLE/CLAIMED/EXPIRED), `expire_at`, `claimed_at`	UK(`tenant_id`,`user_id`,`level`)

(currency 列保留仅为逐笔金额自带出生币种、便于跨站对账;单站内其值恒等于该站 baseCurrency。AVAILABLE 态的日/周/月卡不落表——由「等级 + 期号 + 无领取记录」推导,避免海量空实例;晋级彩金因有窗口期落表。)

九、扩展点

补领道具:过期不补发;「补领卡」道具作为 09 活动发放的权益项扩展。
发薪日模式:「到点自动发放」形态与本系统「领取才保级」模型不兼容(自动发放无领取动作触发保级义务),V1 不做。
周期边界:周俸禄的周起始日(周一/周日)与月末短周期处理,按租户时区与 ISO 周,规则页写明。

十、验收要点

[ ] 同一期重复领取被 UK 拦截,只入账一次;
[ ] 期中升级后领取额 = 新等级配置额;同期只能领一次;
[ ] 领取后:账变、RewardClaimed、保级义务(required += 领取额×10)三者同时成立且金额一致(均本位币);
[ ] 同一保级周期内多次领取俸禄 → RETENTION 义务单条累加(不新建、UK 不冲突),周期末判级基数 = 累加后 required(非首次领取额);
[ ] 整期未领 → EXPIRED,无补发,无保级义务;
[ ] 晋级彩金每级终身一次:降级再升同一级不重复生成;窗口过期作废;
[ ] 4 卡状态/倒计时/红点随领取即时刷新;等级不足显示锁定态;
[ ] 全部额度改配置即生效,前端无写死金额;额度与到账恒本位币,单钱包单口径直出。

07 · VIP 俸禄系统 ​

0. 文档说明 ​

一、定位与职责 ​

二、核心概念与数据模型 ​

2.1 俸禄周期实例 SalaryCycle(用户 × 类型 × 期号) ​

2.2 晋级彩金 UpgradeBonus ​

2.3 保级义务(生成方,累加语义) ​

三、业务规则 ​

3.1 领取 ​

3.2 额度取值 ​

3.3 周期与过期 ​

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

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

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

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

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

九、扩展点 ​

十、验收要点 ​