# 捞回活动

---

`kind=win_back`。限时宝箱由召回批次向触达组发放，对照组不发。原独立配置模版的定时、手动圈人发箱已下线，未完成任务不再续发；已发宝箱仍按原快照正常领取和充值加倍。玩家登录、冷启动或回到平台前台时只查询已有宝箱，不触发资格筛选或发箱。宝箱可直接领取赠送奖金；领取后，玩家须在存款页主动选择捞回活动，并在有效期内创建达到门槛的充值订单，才可获得一次加倍奖金。

充值本金仍按普通充值流程到账。捞回加倍奖金 = 本箱赠送奖金 × 到账结算时随机确定的倍数，向下取两位小数；充值金额只用于判断门槛，不作为奖金计算基数。例：2.06 × 2.12 = 4.3672，实发加倍奖金 4.36，已领取的赠送奖金不扣回。加倍奖金使用宝箱快照中的加倍打码倍数。选择捞回来源的充值不与其他充值活动叠加；普通充值或其他活动来源的充值不消耗捞回资格。

活动详情与领取使用通用接口，见[活动详情](400_promotion.md#detail)和[领取活动奖励](400_promotion.md#claim)。

新保存的彩金档位要求赠送奖金下限不低于 1，上限不低于下限；赠送金额保留最多两位小数。该限制不追溯修改已发宝箱及已结算记录。

宝箱按发放时冻结的 `boost_enabled` 决定是否有充值宝箱。关闭时只允许免费领取，领取后状态为 `claimed_free` 并结束该箱，不显示充值引导、翻倍倒计时或存款活动选项；开启时沿用原领取后充值翻倍流程。旧宝箱缺少该配置时视为开启，之后的配置修改不影响已发宝箱。

尾段递增赠送金额持续增加，不按关闭阈值封顶。当尾段赠送金额达到或超过配置的关闭金额时，仅将该箱 `boost_enabled` 设为 `false`，仍可免费领取全部赠送金额，但不再充值随机翻倍；普通档位不受尾段阈值影响。已发宝箱金额和开关快照不重算。

---

## 宝箱查询（旧回归接口兼容） {#reentry}

仅保留给旧客户端查询已有宝箱，不评估资格、不发箱。新客户端使用[活动详情](#detail)。登录响应不再返回 `win_back_reentry_id`。

**URL:** `POST` /promotion/win_back/reentry

**输入:**

字段 | 类型 | 必填 | 说明
---|---|---|---
event_id | string | 是 | 旧客户端事件 ID，最长 64 字符；仅原样返回，不再参与发箱

**输出:**

字段 | 类型 | 说明
---|---|---
data.event_id | string | 原样返回的旧客户端事件 ID
data.detail | object | 已有宝箱详情，字段见[活动详情](#detail)
data.status | string | 固定为 `query_only`
data.issued | bool | 固定为 `false`，本接口不发箱

召回批次发箱仍须命中彩金档位，并在事务内检查未结束宝箱及保留资格的充值订单，存在任一互斥项时不发新箱。同一召回批次每位会员最多获发一箱，宝箱有效期从实际成功发放时刻起算。

发箱时按会员当前状态检查：仅启用且提现规则为“按规则”或“自动通过”的会员可获发新箱；未启用、提现规则为“不允许”或“自动没收”的会员跳过，并在召回批次中记录原因。未知提现规则同样跳过。已发宝箱不撤回，重复执行仍识别为已发。

---

## 活动详情 {#detail}

登录后返回当前有效宝箱、最近一次加倍结果及存款页参与资格。游客可请求，但不会返回玩家宝箱。

**URL:** `GET` /promotion/win_back/detail

**输出:**

字段 | 类型 | 说明
---|---|---
data.can_join | bool | 当前是否可在存款页选择捞回活动。仅充值宝箱开启、已领取、未过期且没有其他未结束捞回充值订单时为 `true`
data.boost_enabled | bool | 当前有效宝箱是否开启充值宝箱；无有效宝箱时为 `false`
data.server_now | string | 服务端当前时间，UTC RFC3339Nano
data.server_day | string | 商户时区下的当前日期，`YYYY-MM-DD`
data.box | object | 当前未过期宝箱；无有效宝箱时不返回
data.boost_result | object | 最近一次已翻倍宝箱的结果；没有结果时不返回
data.amount_tiers | list<object\> | 开启充值宝箱且已领取时的存款页门槛投影；关闭或无已领取宝箱时不返回
data.bonus_type | string | 已领取宝箱下发 `fixed`；档位奖金为赠送奖金乘最低倍数的下界展示，实际按随机倍数结算
data.max_bonus | number | 开启充值宝箱且已领取时固定为 `0`，表示不另设加倍封顶；实际奖金受本箱已固定的赠送金额与倍数上限约束
data.min_tier_threshold | string | 当前宝箱的最低充值门槛
data.multiplier_min | string | 当前宝箱的随机倍数下限
data.multiplier_max | string | 当前宝箱的随机倍数上限

`data.box` / `data.boost_result` 对象字段：

字段 | 类型 | 说明
---|---|---
id | string | 宝箱 ID
status | string | `pending` 待领取、`claimed` 已领取且可充值翻倍、`claimed_free` 仅免费宝箱已领取（终态）、`boosted` 已翻倍；过期终态为 `expired`（未领取过期）或 `boost_expired`（翻倍资格过期）
boost_enabled | bool | 本箱是否开启充值宝箱，待领取时也返回；关闭时前台必须隐藏全部充值翻倍入口及文案
expire_at | string | 宝箱失效时间
server_now | string | 服务端当前时间，UTC RFC3339Nano
gift_amount | string | 领取态及已翻倍结果中的赠送奖金
claim_bet_multiple | int | 赠送奖金的普通打码倍数
boost_min_amount | string | 捞回充值的最低面额门槛
multiplier_min | string | 随机倍数下限
multiplier_max | string | 随机倍数上限
boost_bet_multiple | int | 加倍奖金的打码倍数
boost_amount | string | 仅已翻倍结果返回的加倍奖金金额
boost_recharge_amount | string | 仅已翻倍结果返回的充值面额
actual_multiplier | string | 仅已翻倍结果返回的实际随机倍数
boost_basis | string | 仅已翻倍结果返回；`gift` 表示按赠送奖金计算，历史充值金额口径记录为空
boosted_at | string | 仅已翻倍结果返回的结算时间

`data.amount_tiers` 单项字段：

字段 | 类型 | 说明
---|---|---
min_amount | string | 捞回充值门槛
bonus | string | 赠送奖金 × 倍数下限，向下取两位；仅为奖金下界展示
bonus_percent | number | 固定为 `0`，不按充值金额计算比例奖金
bet_multiple | int | 加倍奖金的打码倍数

未领取宝箱的 `box` 不包含赠送奖金金额；玩家领取成功后才返回赠送奖金，仅开启充值宝箱才返回翻倍规则。存款页必须同时依据 `can_join` 和 `boost_enabled` 决定是否允许选择活动，不要仅凭 `box` 存在判断。`claimed_free` 仅在领取响应中展示成功结果，不作为后续有效宝箱或活动入口返回。

---

## 领取宝箱 {#claim}

需要登录。使用通用活动领取接口。

**URL:** `POST` /promotion/win_back/claim

**输入:**

字段 | 类型 | 必填 | 说明
---|---|---|---
box_id | string | 否 | 指定要领取的宝箱；省略时领取当前可领取宝箱

**输出:**

字段 | 类型 | 说明
---|---|---
data.box | object | 领取后的宝箱信息，字段见[活动详情](#detail)；开启充值宝箱时状态为 `claimed`，否则为 `claimed_free`，仅包含免费赠送奖金与普通打码规则

领取请求具有幂等保护，同一宝箱最多领取一次。宝箱已领取或已失效时返回业务错误；领取成功后赠送奖金入账，并按普通打码倍数生成奖励任务。

---

## 使用捞回活动充值 {#recharge}

存款页先请求[活动详情](#detail)，只有 `data.can_join=true` 时才可提供捞回活动选项。玩家主动选择后，使用[创建充值订单](200_finance.md#recharge_create)并传入 `source=win_back`。

建单校验包括：

- 玩家有仍有效且已领取的宝箱。
- 宝箱快照中的 `boost_enabled=true`；关闭时即使直接提交充值接口也不能参加。
- 充值面额达到宝箱的 `boost_min_amount`。
- 玩家没有其他未结束的捞回活动充值订单。
- 宝箱失效时间晚于本次订单创建时间；恰好等于失效时间视为无资格。

任一条件不满足时，创建订单返回业务错误，不会静默降级为普通充值。单个宝箱同一时刻最多绑定一笔未结束的捞回充值订单。

订单创建时绑定具体宝箱及奖励规则快照。有效期内创建的订单即使在宝箱到期后才成功到账，仍按绑定宝箱结算；不会改绑玩家之后获得的其他宝箱。订单最终失败时，宝箱尚未到期可重新建单，但旧有效期不延长。

订单成功到账后，本金按充值面额入账；若订单仍具备加倍资格，则服务端在到账结算时随机确定倍数，并以 `本箱赠送奖金 × 实际随机倍数` 向下取两位小数发放加倍奖金。同一宝箱最多结算一次。选择其他充值来源不会获得捞回加倍，也不会消耗宝箱资格。已按旧口径结算的记录不自动重算或调整账本。

充值订单最终关闭后才收到迟到的成功回调时，只按充值系统规则处理本金；不发放该订单的捞回加倍奖金，不恢复已结束的宝箱，也不将订单改绑到新宝箱。

---

## 状态及跨期订单 {#lifecycle}

状态 | 含义
---|---
`pending` | 已发放、待领取
`claimed` | 已领取，处于翻倍资格期；若有有效期内创建的未结束订单，资格可保留到该订单结束
`boosted` | 绑定订单成功到账并已结算加倍奖金
`expired` | 未领取宝箱到期
`boost_expired` | 已领取宝箱到期，且没有仍保留翻倍资格的未结束订单

宝箱到期后不允许新建捞回充值订单。若已存在有效期内创建的未结束订单，则订单最终成功到账并结算，或最终关闭且不再有待处理订单后，才能确定宝箱翻倍资格的终态。充值本金成功入账但加倍处理暂时失败时，不能释放宝箱资格；加倍结算须可重试且不可重复入账。

过期状态与执行记录统计采用按需终结：玩家回归评估、查看活动详情或处理绑定充值订单时检查并更新过期状态。因此后台“已过期”累计数可能晚于实际失效时点更新；资格判断始终同时检查状态、失效时间和保留订单，不以累计数代替资格状态。

---

## 存款活动来源

`source=win_back` 是[创建充值订单](200_finance.md#recharge_create)的可选活动来源，仅在玩家主动选择捞回活动时传入。它与充值套餐赠送及其他充值活动互斥。活动资格和门槛以服务端建单校验为准；不得把不合格请求改成普通充值。