# VIP 接口

**vip**

VIP 活动的 `list` / `detail` / `claim` 走通用活动接口（`kind=vip`，详见 [活动接口](400_promotion.md)）。玩家累计有效投注达到对应档位即升级；升级礼金（`upgrade`）、周俸（`weekly`）、月俸（`monthly`）三类奖励均通过同一个 `claim` 入口按 `body.kind` 分发领取，或用 `all` 一键领取全部可领奖励。

---

## 活动详情字段 {#detail}

通用接口 `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 | 未达保级时一次降几级

未登录或会员不存在时，动态字段为零值。

---

## 领取 {#claim}

通用接口 `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=""`）:** 无（仅返回标准成功响应）

---

## 领取记录 {#claim_list}

分页查询当前登录会员的 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` | 降级（流水记录，无金额入账）