VIP 接口
vip
VIP 活动的 list / detail / claim 走通用活动接口（kind=vip，详见 活动接口）。玩家累计有效投注达到对应档位即升级；升级礼金（upgrade）、周俸（weekly）、月俸（monthly）三类奖励均通过同一个 claim 入口按 body.kind 分发领取，或用 all 一键领取全部可领奖励。
活动详情字段
通用接口 GET /promotion/vip/detail 的 data 字段：
基础
| 字段 | 类型 | 说明 |
|---|---|---|
| description | string | 活动说明 |
| level | number | 当前 VIP 等级，未达任何档位为 0 |
| level_name | string | 当前等级名称，如 V1 |
| lifetime_valid_bet | number | 累计有效投注 |
| next_level_threshold | number | 下一档位的累计投注门槛，已满级为 0 |
| progress | number | 升级进度，区间 [0, 1] |
| bet_multiple | number | 打码倍数（全局） |
| tiers | list<Tier> | 全部档位配置 |
| vip_last_upgrade_at | string | 上次升级时间（RFC3339），从未升级为空串 |
| vip_last_demote_at | string | 上次降级时间（RFC3339），从未降级为空串 |
升级礼金
| 字段 | 类型 | 说明 |
|---|---|---|
| upgrade_pending_levels | list<number> | 已升级但未领礼金的等级列表 |
| upgrade_pending_amount | number | 待领升级礼金总额 |
| pending_amount | number | 当前所有可领金额合计（升级待领 + 本周可领周俸 + 本月可领月俸；不可领的项不计入） |
周俸（一个周期一次；本周已升级则本周封禁）
| 字段 | 类型 | 说明 |
|---|---|---|
| weekly_period_key | string | 当前周期键（如 2026W24） |
| weekly_amount | number | 本周可领金额（当前档位配置） |
| weekly_claimed | bool | 当前周期是否已领 |
| weekly_claimable | bool | 当前是否可领（综合考虑流水、充值、是否已领） |
| weekly_turnover | number | 本周累计有效投注 |
| weekly_turnover_required | number | 本周流水门槛，0 表示不校验 |
| weekly_recharge_within_days | number | 近 N 天必须有充值，0 表示不限 |
| weekly_recharge_ok | bool | 充值条件是否满足 |
| weekly_blocked | bool | 本周内升过级，本周不可领（下周起可领） |
月俸（一个周期一次；本月已升级则本月封禁）
| 字段 | 类型 | 说明 |
|---|---|---|
| monthly_period_key | string | 当前周期键（如 2026-06） |
| monthly_amount | number | 本月可领金额（当前档位配置） |
| monthly_claimed | bool | 当前周期是否已领 |
| monthly_claimable | bool | 当前是否可领 |
| monthly_turnover | number | 本月累计有效投注 |
| monthly_turnover_required | number | 本月流水门槛，0 表示不校验 |
| monthly_recharge_within_days | number | 近 N 天必须有充值，0 表示不限 |
| monthly_recharge_ok | bool | 充值条件是否满足 |
| monthly_blocked | bool | 本月内升过级，本月不可领（下月起可领） |
保级
| 字段 | 类型 | 说明 |
|---|---|---|
| keep_min_turnover | number | 当前档月末保级流水门槛，0 表示本级不参与降级 |
| demote_levels | number | 未达保级时一次降几级，0 表示不降 |
Tier 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| level | number | 等级编号（从 1 起） |
| name | string | 等级名称 |
| lifetime_valid_bet | number | 升入本级所需累计有效投注 |
| upgrade_reward | number | 升入本级一次性礼金，0 表示无 |
| weekly_reward | number | 周俸金额 |
| weekly_min_turnover | number | 周俸领取流水门槛 |
| weekly_recharge_within_days | number | 周俸领取要求近 N 天有充值 |
| monthly_reward | number | 月俸金额 |
| monthly_min_turnover | number | 月俸领取流水门槛 |
| monthly_recharge_within_days | number | 月俸领取要求近 N 天有充值 |
| keep_min_turnover | number | 月末保级流水门槛 |
| demote_levels | number | 未达保级时一次降几级 |
未登录或会员不存在时，动态字段为零值。
领取
通用接口 POST /promotion/vip/claim。同一入口按 body.kind 分发三类操作；空字符串触发等级校准刷新。
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kind | string | 是 | 领取类型：upgrade 一次性领取所有待领升级礼金 / weekly 领取本周周俸 / monthly 领取本月月俸 / all 一键领取全部可领奖励（不可领的项静默跳过）/ "" 仅触发等级校准刷新 |
输出（kind=upgrade）:
| 字段 | 类型 | 说明 |
|---|---|---|
| paid_levels | list<number> | 本次领取覆盖的等级列表 |
| total_amount | number | 本次入账总金额 |
输出（kind=weekly 或 kind=monthly）:
| 字段 | 类型 | 说明 |
|---|---|---|
| amount | number | 本次入账金额 |
| period_key | string | 领取的周期键 |
输出（kind=all）: 字段按实际领到的项目返回，没领到的项目对应字段不会出现；活动未开启时返回错误 活动未启用；三项都没领到时返回错误 当前无可领取的奖励。
| 字段 | 类型 | 说明 |
|---|---|---|
| paid_levels | list<number> | 升级礼金覆盖的等级列表（仅当本次领到升级礼金时返回） |
| upgrade_amount | number | 升级礼金入账金额（仅当本次领到升级礼金时返回） |
| weekly_amount | number | 周俸入账金额（仅当本次领到周俸时返回） |
| weekly_period_key | string | 周俸周期键（仅当本次领到周俸时返回） |
| monthly_amount | number | 月俸入账金额（仅当本次领到月俸时返回） |
| monthly_period_key | string | 月俸周期键（仅当本次领到月俸时返回） |
| total_amount | number | 本次入账总金额（升级 + 周俸 + 月俸） |
输出（kind=""）: 无（仅返回标准成功响应）
领取记录
分页查询当前登录会员的 VIP 领取流水（升级礼金 / 周俸 / 月俸 / 降级），按 created_at DESC, id DESC 排序。需登录，未登录返回错误 请先登录。
URL: GET /vip_claim/list
Query:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kind | string | 否 | 按领取类型过滤，枚举见下表；不传返回全部 |
| page | number | 否 | 页码，默认 1 |
| size | number | 否 | 每页条数 |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| list | list<VipClaim> | 领取记录列表 |
| total | number | 总数 |
VipClaim 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 记录 ID（Snowflake） |
| merchant_id | string | 商户 ID |
| member_id | string | 会员 ID |
| kind | string | 领取类型，枚举见下表 |
| period_key | string | 期键：周俸如 2026W26、月俸如 2026-06、升级礼金如 L3（对应升入等级）、降级为空 |
| from_level | number | 变更前等级（升级 / 降级时有意义；周俸 / 月俸为当前等级） |
| to_level | number | 变更后等级（升级 / 降级时有意义；周俸 / 月俸为当前等级） |
| amount | number | 入账金额（降级记录为 0） |
| bet_multiple | number | 入账时使用的打码倍数 |
| created_at | string | 产生时间 |
| updated_at | string | 更新时间 |
kind 枚举:
| 值 | 含义 |
|---|---|
upgrade |
升级礼金 |
weekly |
周俸 |
monthly |
月俸 |
demote |
降级（流水记录，无金额入账） |