# 幸运礼物重构第一步：配置契约与单位

本文档定义幸运礼物重构第一步。第一步只解决配置、单位、规则版本和后台发布校验，不实现新抽奖算法。当前处于开发阶段，不兼容旧代码，不保留旧的 `target_rtp_ppm=95`、旧 `tiers.weight=0` 自动权重模型，也不继续把 `lucky_gift_rules.gift_id` 当作奖池 ID 使用。

## 目标

| 目标 | 说明 |
| --- | --- |
| 消灭单位歧义 | 后台展示百分比和倍数，服务端持久化 ppm |
| 明确规则 owner | `activity-service` 拥有幸运礼物规则、奖档、RTP 参数和版本 |
| 按阶段配置体验 | `novice/normal/advanced` 各自拥有独立奖档概率 |
| 发布前校验 | 配置无法满足成本或体验边界时拒绝发布 |
| 为第二步抽奖引擎铺路 | 输出可直接被 v2 抽奖引擎读取的规则快照 |

## 删除旧模型

| 旧模型 | 新处理 |
| --- | --- |
| 后台直接提交 `target_rtp_ppm=95` | 改为后台提交 `target_rtp_percent=95`，服务端转换为 `950000` |
| 后台提交倍数 `0.3` 后直接存 `0.3` | 服务端保存 `multiplier_ppm=300000` |
| `lucky_gift_rules.gift_id` 表示奖池 | 新表使用显式 `pool_id` |
| 单一 `multiplier_ppms` 生成三个阶段相同奖档 | 三个阶段分别配置奖档和权重 |
| `tiers.weight=0`，运行时自动权重 | 后台必须配置基础概率，抽奖引擎只做控制调整 |

## 新配置字段

### 规则主表

建议新建 `lucky_gift_rule_versions`。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `app_code` | string | App 编码 |
| `pool_id` | string | 幸运礼物奖池 ID |
| `rule_version` | int64 | 规则版本，每次发布递增 |
| `enabled` | bool | 是否启用 |
| `target_rtp_ppm` | int64 | 基础返奖目标，`95% = 950000` |
| `pool_rate_ppm` | int64 | 每笔扣费进入基础奖池比例 |
| `settlement_window_wager` | int64 | RTP 结算窗口流水，单位金币 |
| `control_band_ppm` | int64 | 正常波动带，`10000 = ±1%` |
| `gift_price_reference` | int64 | 配置参考礼物价格 |
| `effective_from_ms` | int64 | 生效时间，UTC epoch ms |
| `created_by_admin_id` | int64 | 发布人 |
| `created_at_ms` | int64 | 创建时间 |

### 阶段奖档表

建议新建 `lucky_gift_stage_tiers`。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `app_code` | string | App 编码 |
| `pool_id` | string | 奖池 ID |
| `rule_version` | int64 | 规则版本 |
| `stage` | string | `novice/normal/advanced` |
| `tier_id` | string | 奖档 ID |
| `multiplier_ppm` | int64 | 倍率，`1x = 1000000` |
| `base_weight_ppm` | int64 | 正常模式基础概率 |
| `reward_source` | string | `base_rtp/activity_subsidy/presentation_only` |
| `high_water_only` | bool | 是否高水位才开放 |
| `broadcast_level` | string | `none/room/region/global` |
| `enabled` | bool | 是否启用 |

## 后台输入格式

后台对运营展示和提交应使用易懂单位：

```json
{
  "pool_id": "lucky_100",
  "enabled": true,
  "target_rtp_percent": 95,
  "pool_rate_percent": 96,
  "settlement_window_wager": 1000000,
  "control_band_percent": 1,
  "gift_price_reference": 100,
  "stages": [
    {
      "stage": "novice",
      "tiers": [
        {"tier_id": "novice_none", "multiplier": 0, "probability_percent": 30},
        {"tier_id": "novice_0_3x", "multiplier": 0.3, "probability_percent": 22},
        {"tier_id": "novice_0_5x", "multiplier": 0.5, "probability_percent": 18}
      ]
    }
  ]
}
```

服务端保存前转换：

```text
target_rtp_percent=95       -> target_rtp_ppm=950000
pool_rate_percent=96        -> pool_rate_ppm=960000
control_band_percent=1      -> control_band_ppm=10000
multiplier=0.3              -> multiplier_ppm=300000
probability_percent=22      -> base_weight_ppm=220000
```

## 发布校验

| 校验项 | 规则 | 失败处理 |
| --- | --- | --- |
| RTP 单位 | `100000 <= target_rtp_ppm <= 990000` | 拒绝发布 |
| 入池比例 | `pool_rate_ppm >= target_rtp_ppm` 且 `pool_rate_ppm <= 1000000` | 拒绝发布 |
| 波动带 | `0 < control_band_ppm <= 50000` | 拒绝发布 |
| 参考价格 | `gift_price_reference > 0` | 拒绝发布 |
| 阶段完整 | 必须有 `novice/normal/advanced` 三个阶段 | 拒绝发布 |
| 阶段概率 | 每个阶段 `sum(base_weight_ppm) == 1000000` | 拒绝发布 |
| 倍率合法 | `multiplier_ppm >= 0` | 拒绝发布 |
| 基础奖档 | 每个阶段至少有一个 `base_rtp` 奖档 | 拒绝发布 |
| 未中奖档 | 每个阶段必须显式配置 `0x`，除非标记为“每抽必返” | 拒绝发布或强确认 |
| 高倍档 | `high_water_only=true` 或有明确单次上限 | 拒绝发布 |

## API 调整

后台接口只暴露业务单位：

| 接口 | 行为 |
| --- | --- |
| `GET /api/v1/admin/activity/lucky-gifts/config?pool_id=...` | 返回百分比、倍数和阶段奖档 |
| `PUT /api/v1/admin/activity/lucky-gifts/config?pool_id=...` | 发布新版本，服务端转换 ppm 并校验 |
| `GET /api/v1/admin/activity/lucky-gifts/configs` | 列出所有奖池和当前版本 |

内部 gRPC 可以继续使用 ppm，但字段名必须明确：

| 字段 | 说明 |
| --- | --- |
| `target_rtp_ppm` | 内部字段，后台 HTTP 不直接要求运营填写 |
| `pool_rate_ppm` | 内部字段 |
| `multiplier_ppm` | 内部字段 |
| `base_weight_ppm` | 内部字段 |

## 实施任务

1. 新增 v2 proto：规则、阶段、奖档、发布请求、读取响应。
2. 新增 MySQL v2 表。
3. 改后台 lucky gift handler，只接收百分比和倍数。
4. 在 `activity-service` 增加配置转换和发布校验。
5. 删除或旁路旧 `multiplier_ppms -> tiers(weight=0)` 归一化模型。
6. 增加配置单元测试和 schema 初始化。

## 验收标准

| 验收项 | 标准 |
| --- | --- |
| 单位转换 | 后台提交 `target_rtp_percent=95` 后，DB 保存 `target_rtp_ppm=950000` |
| 倍率转换 | 后台提交 `multiplier=0.3` 后，DB 保存 `multiplier_ppm=300000` |
| 概率转换 | 后台提交 `probability_percent=22` 后，DB 保存 `base_weight_ppm=220000` |
| 错误 RTP | 后台提交等价 `target_rtp_ppm=95` 的配置必须被拒绝 |
| 阶段概率 | 任一阶段概率和不是 100% 时必须被拒绝 |
| 旧字段隔离 | 新规则表不再使用 `gift_id` 表示 `pool_id` |
| 版本不可变 | 发布新配置只新增 `rule_version`，不覆盖历史版本 |
| 测试 | `go test ./services/activity-service/internal/service/luckygift ./services/activity-service/internal/storage/mysql ./server/admin/internal/modules/luckygift` 通过 |

第一步完成后，系统只具备“正确配置和发布规则”的能力，不要求新抽奖引擎上线。