# Lucky Gift Product Design

本文档定义语音房幸运礼物的产品规则。幸运礼物使用金币赠送，奖励也返还金币

## Positioning

| Object | Meaning                                        |
| ------ | ---------------------------------------------- |
| 用户   | 用金币赠送幸运礼物，获得房间表现和概率金币奖励 |
| 主播   | 正常获得礼物贡献和房间热度，不参与控制开奖结果 |
| 房间   | 获得飘屏、热度、本地榜、互动气氛               |
| 平台   | 用奖池和风控控制整体返还率，不控制单个用户输赢 |

核心原则：

| Rule         | Decision                                           |
| ------------ | -------------------------------------------------- |
| 先扣费再抽奖 | 只有金币扣费成功后才进入幸运礼物抽奖               |
| 先过滤再随机 | 先根据奖池水位和风控阈值过滤奖档，再执行随机       |
| 抽后不改结果 | 随机结果生成后必须落日志，不允许后台强改           |
| 整体控阈值   | 控制平台、房间、礼物、用户维度的风险敞口           |
| 规则可解释   | 前台展示基础概率、奖励范围、低水位规则和上限       |
| 结果可审计   | 每次抽奖保存规则版本、奖池快照、随机材料和发奖状态 |

## User Experience

用户在礼物面板选择幸运礼物，支付金币后出现三类结果：

| Result       | User Feedback                                      |
| ------------ | -------------------------------------------------- |
| 未命中奖励   | 礼物正常送出，房间展示普通幸运礼物消息             |
| 命中小额奖励 | 礼物正常送出，返还金币到账，房间展示轻量提示       |
| 命中大奖励   | 礼物正常送出，返还金币到账，房间展示飘屏或强化特效 |

金币奖励必须以实际到账为准。若账务补偿中，客户端展示“奖励处理中”，不能提前展示“已到账”。

## Three Pool Model

### Platform Pool

平台总奖池控制全站幸运礼物的整体返还率。

| Field                         | Meaning                  |
| ----------------------------- | ------------------------ |
| `platform_pool_balance`       | 当前全站可用幸运奖励金币 |
| `platform_reserve_floor`      | 平台最低安全水位         |
| `platform_target_payout_rate` | 平台目标返还率           |
| `platform_daily_payout_limit` | 平台每日最大奖励支出     |

平台奖池低于安全水位时，大额奖档不可参与随机；被过滤奖档的概率质量进入未中奖奖档，不重新分配给其他奖档。

### Room Pool

房间奖池控制单房间爆奖能力。热门房可以积累更高水位，冷房不能打穿平台预算。

| Field                      | Meaning                  |
| -------------------------- | ------------------------ |
| `room_pool_balance`        | 房间当前可用幸运奖励金币 |
| `room_reserve_floor`       | 房间最低安全水位         |
| `room_hourly_payout_limit` | 房间小时最大奖励支出     |
| `room_daily_payout_limit`  | 房间每日最大奖励支出     |

房间奖池只影响本房间，不允许直接挪用其他房间水位。需要运营活动加成时，必须通过平台奖池或活动预算显式补贴。

### Gift Pool

礼物奖池控制不同幸运礼物的成本结构。

| Field                     | Meaning                      |
| ------------------------- | ---------------------------- |
| `gift_pool_balance`       | 某个幸运礼物当前可用奖励金币 |
| `gift_reserve_floor`      | 礼物最低安全水位             |
| `gift_target_payout_rate` | 礼物目标返还率               |
| `gift_max_single_payout`  | 礼物单次最高奖励             |

低价礼物适合高频小奖，高价礼物适合低频大奖。不同礼物必须使用独立概率表和独立水位，不要共用一个不可解释的全局概率。

## Risk Layer

风控层不在抽奖后篡改结果，只在抽奖前决定是否允许参与、是否降低可用奖档、是否进入人工观察。

| Threshold                         | Product Meaning          |
| --------------------------------- | ------------------------ |
| `max_single_payout`               | 单次最大奖励金币         |
| `max_user_daily_payout`           | 单用户每日最大奖励金币   |
| `max_device_daily_payout`         | 单设备每日最大奖励金币   |
| `max_room_hourly_payout`          | 单房间每小时最大奖励金币 |
| `max_anchor_daily_related_payout` | 单主播关联奖励风险上限   |
| `max_activity_period_payout`      | 活动周期最大奖励金币     |
| `max_user_hit_count_window`       | 单用户窗口期最大命中次数 |

触发阈值后的产品动作：

| Action     | When                                       |
| ---------- | ------------------------------------------ |
| 拒绝参与   | 用户、设备、房间或活动已达到硬上限         |
| 低水位模式 | 奖池不足以支付完整奖档                     |
| 仅小奖模式 | 大奖风险超出当前窗口预算                   |
| 人工观察   | 主播、用户、设备、支付来源存在明显关联异常 |
| 活动暂停   | 平台总返还率或投诉风险超过运营阈值         |

## Reward Configuration

每个幸运礼物最小配置：

| Field                       | Meaning                    |
| --------------------------- | -------------------------- |
| `gift_id`                   | 幸运礼物 ID                |
| `gift_price`                | 单个礼物金币价格           |
| `pool_rate`                 | 每笔礼物进入幸运奖池的比例 |
| `target_payout_rate`        | 长期目标返还率             |
| `reserve_floor`             | 最低安全水位               |
| `max_single_payout`         | 单次最高奖励金币           |
| `max_user_daily_payout`     | 单用户每日最高奖励金币     |
| `max_room_hourly_payout`    | 单房间小时最高奖励金币     |
| `probability_table_version` | 概率表版本                 |
| `enabled_reward_tiers`      | 当前启用奖档               |

示例概率表只表达结构，不作为正式运营参数：

| Tier        |            Reward | Base Probability | Availability                  |
| ----------- | ----------------: | ---------------: | ----------------------------- |
| `none`      |               `0` |       `88.7000%` | always                        |
| `small_1x`  |  `gift_price * 1` |       `10.0000%` | pool safe                     |
| `medium_5x` |  `gift_price * 5` |        `1.0000%` | pool safe and user limit safe |
| `large_50x` | `gift_price * 50` |        `0.3000%` | high water only               |

奖池低水位时，如果 `large_50x` 不可用，它的 `0.3000%` 必须进入 `none`，不能转给 `small_1x` 或 `medium_5x`。

## Draw Flow

标准流程：

```text
读取规则版本
读取平台、房间、礼物奖池水位
读取用户、设备、房间、主播、活动风控计数
过滤不可支付或不可触发奖档
生成候选奖档
执行随机
写入抽奖结果日志
发放金币奖励
广播房间表现
```

不可接受流程：

```text
先随机
发现超预算
后台改成未中奖
```

## Room Presentation

幸运礼物产生两类房间表现：

| Event          | Owner                                                |
| -------------- | ---------------------------------------------------- |
| 礼物送出消息   | `room-service`                                       |
| 房间热度变化   | `room-service`                                       |
| 房间本地礼物榜 | `room-service`                                       |
| 幸运奖励结果   | `activity-service` 决策，`room-service` 转成房间表现 |
| 房间消息投递   | 腾讯云 IM                                            |

`activity-service` 不直接持有 Room Cell，不修改麦位、禁言、在线态和房间榜。它只返回幸运礼物决策结果，并通过事件让房间系统表现出来。

## Compliance Baseline

产品默认遵守以下红线：

| Red Line             | Decision                             |
| -------------------- | ------------------------------------ |
| 不允许空奖池承诺大奖 | 当前奖池无法支付时，大奖档必须不可用 |
| 不删除抽奖记录       | 抽奖、奖池、发奖记录按审计周期保存   |

## Metrics

上线后必须监控这些指标：

| Metric                  | Reason               |
| ----------------------- | -------------------- |
| `lucky_gift_gmv`        | 幸运礼物金币消耗     |
| `lucky_reward_payout`   | 金币奖励支出         |
| `actual_payout_rate`    | 实际返还率           |
| `pool_balance_by_scope` | 平台、房间、礼物水位 |
| `hit_rate_by_tier`      | 各奖档命中率         |
| `reward_credit_latency` | 金币到账延迟         |
| `risk_reject_count`     | 风控拒绝次数         |
| `pending_reward_count`  | 待补偿发奖数量       |
| `complaint_rate`        | 用户争议风险         |

## V1 Scope

首版只做：

| Included           | Excluded               |
| ------------------ | ---------------------- |
| 三层奖池           | 主备热同步             |
| 固定概率表版本     | 个性化概率             |
| 抽前风控阈值       | 抽后改结果             |
| 金币奖励           | 现金、实物、提现       |
| 房间飘屏和系统消息 | 跨房 PK 大奖池         |
| 抽奖日志和补偿     | 后台人工指定某用户中奖 |