# 红包雨接口

**red_packet_rain**

红包雨的 `list` / `detail` / `claim` 走通用活动接口（`kind=red_packet_rain`，详见 [活动接口](400_promotion.md)）。每个时间窗口内仅可领一次，单日总次数受 `daily_max_count` 约束；金额根据玩家充值档位区间随机。

---

## 活动列表摘要

`GET /promotion/list` 的 `red_packet_rain` 行在 `payload` 中下发以下摘要。到零后重新拉取活动列表。

字段 | 类型 | 说明
---|---|---
status / last_time | number | 含义与详情字段一致，展示本场结束或下轮开始倒计时
can_claim | boolean | 已登录、活动开启、当前在窗口、今日次数未满且本窗口未领取时为 `true`（**不含充值门槛**：没充值的玩家照样为 `true`，点领取时服务端返回「请充值后参与」）。免费奖金列表据此显示限时领取卡并计入角标；领取时服务端仍重新校验
window_start / window_end | string | 当前窗口的商户时间段，`HH:mm`；不在窗口时为空，供标题展示，例如 `10:00 - 10:59 红包雨`
window_end_at | string / null | 当前窗口结束的 RFC3339 时间（含时区）；不在窗口时为 `null`
next_start_at | string | 下一场开始的 RFC3339 时间（含时区），场内场外都下发；当天无后续窗口则指向次日首场开始。场内已领过时用它展示「距下一场开始」倒计时
server_now | string | 服务端当前 RFC3339 时间（含时区），供客户端校正倒计时

`can_claim=true` 时计 1 项进共用 `unclaimed_count` 角标，口径同 `can_claim`，且红点 / 计数实时判定、不走缓存。前端用同一口径：`can_claim=true`（游客在场内也视为可领）显示「领取」卡，点击直接调 `claim`，不预先提示充值；没资格的玩家点领取，服务端返回错误提示（未达充值门槛 / 无命中档位均为「请充值后参与」）。本场已领或今日次数用完时 `can_claim=false`，卡片退回「查看」入口。领取成功后刷新活动列表和余额，已领取或过期时撤下领取卡。

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

通用接口 `GET /promotion/red_packet_rain/detail` 的 `data` 字段：

字段 | 类型 | 说明
---|---|---
description | string | 活动说明
remark | string | 玩家端备注
status | number | `0` 当前不在窗口 / `1` 当前在窗口
last_time | number | `status=1` 时为距本窗口结束的剩余秒数；`status=0` 时为距下一窗口开始的剩余秒数（当天无后续窗口则指向次日首场开始）；无配置时为 `0`。客户端到零后重新获取状态
receive_time | number | 当日最近一次领取时间（unix 秒，无则 `0`）
bonus | number | 本窗口已领金额合计
claimed | boolean | 本窗口是否已有领取记录，包括金额为零的领取；不要用 `bonus > 0` 判断已领
window_start / window_end | string | 当前窗口时间段，含义同列表摘要
window_end_at | string / null | 当前窗口结束时间，含义同列表摘要
next_start_at | string | 下一场开始时间，含义同列表摘要
server_now | string | 服务端当前时间，含义同列表摘要
list | object | `{ "0": {start_time, end_time}, ... }` 配置的所有窗口
red_packet_is_icon | string | `0` / `1`
red_packet_icon | string | icon URL
eligible_type | number | 资格类型：`0` 今日累计充值 / `1` 历史累计充值
min_recharge_amount | number | 参与门槛
daily_max_count | number | 每日领取上限
bet_multiple | number | 打码倍数
claim_amount_tiers | list<ClaimAmountTier\> | 充值-金额档位

`ClaimAmountTier` 字段：

字段 | 类型 | 说明
---|---|---
recharge | number | 充值门槛
min | number | 区间下限
max | number | 区间上限

---

## 领取 {#claim}

通用接口 `POST /promotion/red_packet_rain/claim`。命中：当前在窗口内 + 资格充值达标 + 今日次数未满 + 本窗口未领过；本窗口已领时直接返回上次金额。

**输入:** `{}`

**输出:**

字段 | 类型 | 说明
---|---|---
amount | number | 本次入账金额（同一窗口重复请求返回首次金额）