---
name: Lucky Reward 奖池迁移
overview: 采用全平台统一的 reward_pool / reward_pool_item，以 pool_code = lucky_reward 承载大转盘手动 Spin 奖项；外层仅 prize_type 表达类型，lucky_reward 业务参数（含 unlockInviteCount）一律进 config；逐步替换 lucky_reward_prize_config。
todos:
  - id: ddl-seed
    content: s_common 建 reward_pool / reward_pool_item（含 prize_type 外层字段），seed pool_code=lucky_reward，编写从 lucky_reward_prize_config 的迁移脚本
    status: completed
  - id: console-draw
    content: slot_console：RewardPoolItemModel + ConfigService/DrawService/LuckyRewardLogic 改读 lucky_reward 奖池，Draw 读 prize_type 列
    status: completed
  - id: admin-crud
    content: slot_admin：替换 LuckyRewardPrizeConfig CRUD 为 lucky_reward 奖池项管理，更新菜单权限
    status: completed
  - id: test-docs-cleanup
    content: 单测/集成测、需求文档更新、删除旧 Model 与 lucky_reward_prize_config 表
    status: completed
isProject: false
---

# Lucky Reward 奖池方案评估与迁移计划

## 结论：`pool_code = lucky_reward` 可行，推荐做

**方向正确**：把「可复用奖池」与「活动专用抽奖/入账」拆开，比继续扩 [`lucky_reward_prize_config`](docs/requirements/lucky_rewards/02_管理后台方案.md) 更适合后续其它活动复用同一套表结构。

**与你已确认的前提对齐**：

- 全平台 **一个** 奖池：`pool_code = 'lucky_reward'`
- **替换** 现有 [`lucky_reward_prize_config`](slot_console/app/model/common/LuckyRewardPrizeConfigModel.php)（非并存长期双写）
- **外层仅 `prize_type` 表达奖项类型**；lucky_reward 业务参数（含开放条件）**一律进 `config`**，避免个别字段外置导致表结构膨胀

```mermaid
flowchart LR
  subgraph admin [slot_admin]
    PoolCRUD[RewardPoolItem CRUD]
  end
  subgraph db [s_common]
    RP[reward_pool pool_code=lucky_reward]
    RPI["reward_pool_item prize_type + config"]
  end
  subgraph console [slot_console]
    Draw[LuckyRewardDrawService]
    Spin[LuckyRewardLogic.executeManualSpin]
  end
  PoolCRUD --> RPI
  RP --> RPI
  RPI --> Draw
  Draw --> Spin
```

---

## 核心设计：`prize_type` 外层 + 业务参数全进 `config`

**字段分层原则**：

| 层级 | 字段 | 说明 |
| --- | --- | --- |
| 表通用列 | `pool_id`、`pool_code`、`item_code`、`item_name`、`prize_type`、`weight`、`display_text`、`icon_url`、`status`、`sort` | 奖池项元数据，各 pool 共用 |
| `config` JSON | lucky_reward 及后续各 pool 的**业务参数** | 含开放条件、金额区间等；**禁止**再拆个别业务字段到表列 |
| 禁止 | 表列 `unlock_invite_count` 等 lucky_reward 专用字段 | 与「通用奖池表 + pool 级 config 约定」冲突 |

### 1. 表字段调整（相对你初版 DDL）

原 DDL 中的 `reward_type` **改为 `prize_type`**（TINYINT，奖项命中语义）。不同 `pool_code` 可约定不同枚举；`lucky_reward` 池定义如下：

| prize_type | 含义 | 抽奖 | 入账行为（与现网一致） |
| --- | --- | --- | --- |
| 1 | 随机金额 | 参与权重 | My Amount 增加（封顶至 target） |
| 2 | 1x Spin | 参与权重 | spin_available +1 |
| 3 | Cash Out | 参与权重 | playerStatus → 可提取 |
| 4 | Jackpot 展示 | **不参与**（weight=0 或 Draw 过滤） | 无入账，仅转盘 UI 展示 |

常量命名沿用现有 [`LuckyRewardPrizeConfigModel::PRIZE_TYPE_*`](slot_console/app/model/common/LuckyRewardPrizeConfigModel.php)，迁移到 `RewardPoolItemModel`（或共用常量类），保证 [`lucky_reward_spin_record.prize_type`](docs/requirements/lucky_rewards/02_管理后台方案.md) 与 [`DrawResultEntity::prizeType`](slot_console/app/entity/luckyReward/DrawResultEntity.php) **数值不变**。

### 2. `lucky_reward` 池 `config` 结构（SSOT）

**禁止** config 内写 `prizeType`（类型只看外层列）。按 `prize_type` 校验必填/可选字段（admin Validate + 文档）：

**各类型共有可选字段**（参与抽奖的类型 1/2/3 常用）：

| config 字段 | 说明 |
| --- | --- |
| `unlockInviteCount` | 开放命中所需有效邀请人数，默认 0（无需） |

**各类型专有字段**：

| prize_type | 专有 config 字段 | 说明 |
| --- | --- | --- |
| 1 随机金额 | `amountMinQf`, `amountMaxQf` | 千分位区间，min ≤ max |
| 2 1x Spin | — | 可无专有字段 |
| 3 Cash Out | — | 可无专有字段；开放条件用 `unlockInviteCount` |
| 4 Jackpot | `displayAmountQf` | 展示用金额（千分位） |

示例：

```json
// prize_type = 1，需 3 个有效邀请后才开放
{ "unlockInviteCount": 3, "amountMinQf": 100, "amountMaxQf": 500 }

// prize_type = 3，Cash Out 需 5 个邀请
{ "unlockInviteCount": 5 }

// prize_type = 4
{ "displayAmountQf": 6666000 }
```

### 3. 外层列（不进 config）

仅保留奖池项**通用**列，不含 lucky_reward 业务参数：

| 字段 | 说明 |
| --- | --- |
| `weight` | 抽取权重 |
| `display_text` / `icon_url` / `sort` | 前端展示与排序 |

`reward_pool_item` 建议 DDL 片段（相对初版变更点）：

```sql
`prize_type` TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '奖项类型，lucky_reward池见 PRIZE_TYPE_* 常量',
`config` JSON NOT NULL COMMENT 'pool 业务参数，lucky_reward见文档 SSOT',
-- 删除 reward_type；不新增 unlock_invite_count 等 pool 专用列
```

### 4. 全平台单池

所有 source 共用 `pool_code = lucky_reward` 一套转盘格子和权重；[`LuckyRewardConfigService::listEnabledPrizeConfigs($configId)`](slot_console/app/service/luckyReward/LuckyRewardConfigService.php) 改为按 `pool_code` 加载，**不再依赖** `lucky_reward_config.id`。

活动 per-source 配置（开关、周期、分层开宝箱、目标金额）不变。

### 5. DDL 其它细节

| 项 | 建议 |
| --- | --- |
| 主键 | 确认 ID 策略：若无雪花发号，补 AUTO_INCREMENT |
| 时间字段 | Model 层映射 `created_at`/`updated_at` |
| 库 | **s_common** |
| 索引 | item 表增加 `KEY idx_pool_code_status (pool_code, status)`、`KEY idx_prize_type (prize_type)` |

### 6. 常量约定

```php
/** Lucky Rewards 大转盘手动 Spin 奖池编码 */
public const POOL_CODE_LUCKY_REWARD = 'lucky_reward';
```

`prize_type` 常量（中文注释必填）与现网 1/2/3/4 对齐。

---

## 迁移与实现步骤

### Phase 1 — 表结构与数据迁移

1. 在 `s_common` 执行 `reward_pool`、`reward_pool_item` DDL（`prize_type` + `config`，无 `reward_type`、无 `unlock_invite_count` 列）
2. Seed：`pool_code = lucky_reward`，`pool_name = Lucky Rewards Wheel`，`status = 1`
3. 迁移 `lucky_reward_prize_config` → `reward_pool_item`：
   - `prize_type` ← 旧 `prize_type`（直迁）
   - `weight`、`sort`、`status` 直迁
   - `config`：写入 `unlockInviteCount`（← 旧 `unlock_invite_count`）+ 类型专有字段（amountMinQf/MaxQf 或 displayAmountQf）
   - `item_code`：建议 `lr_prize_{old_id}`
4. 验证通过后 drop 旧表（或先 rename `_bak`）

### Phase 2 — slot_console 读新池抽奖

| 文件 | 变更 |
| --- | --- |
| 新建 `RewardPoolModel` / `RewardPoolItemModel` | `listEnabledByPoolCode()` |
| [`LuckyRewardConfigService`](slot_console/app/service/luckyReward/LuckyRewardConfigService.php) | `listLuckyRewardPoolItems()`，固定 `POOL_CODE_LUCKY_REWARD` |
| [`LuckyRewardDrawService`](slot_console/app/service/luckyReward/LuckyRewardDrawService.php) | 读列 `prize_type`；过滤读 `config.unlockInviteCount`（缺省 0）；随机金额读 `config.amountMinQf/MaxQf`；Jackpot(4) 仍排除 |
| [`DrawResultEntity`](slot_console/app/entity/luckyReward/DrawResultEntity.php) | 增加 `poolItemId`；`prizeType` 来自 item 的 `prize_type` 列 |
| [`LuckyRewardLogic::executeManualSpin`](slot_console/app/api/logic/LuckyRewardLogic.php) | 切换数据源；spin_record.prize_type 仍写 Draw 结果 |

**行为不变**：随机封顶、+1 Spin、Cash Out 改状态、spin_record 写入。

### Phase 3 — slot_admin 后台替换 CRUD

| 现状 | 目标 |
| --- | --- |
| [`LuckyRewardPrizeConfigController`](backend/slot_admin/app/game/controller/LuckyRewardPrizeConfigController.php) 等 | Lucky Reward 奖池项管理（scoped `pool_code=lucky_reward`） |
| Validate | 校验外层 `prize_type`、按类型校验 config（含 `unlockInviteCount`、金额区间）、权重 |
| [`menu-lucky-rewards.sql`](backend/slot_admin/db/menu-lucky-rewards.sql) | 路由指向新 Controller |

表单：美元展示 → 写入 config 内 `_qf`；`unlockInviteCount` 表单项写入 config；`prize_type` 下拉与现网四类一致。

### Phase 4 — 文档、测试、清理

- 更新 [`02_管理后台方案.md`](docs/requirements/lucky_rewards/02_管理后台方案.md)：`reward_pool_item.prize_type` 枚举 + config 结构 SSOT
- 更新 [`LuckyRewardDrawServiceTest`](slot_console/tests/Unit/LuckyRewardDrawServiceTest.php) fixture：pool item 含 `prize_type` 列 + 精简 config
- 删除 `LuckyRewardPrizeConfigModel` 及旧表引用

---

## 风险与规避

| 风险 | 规避 |
| --- | --- |
| 运营迁移窗口改旧表 | 迁移前冻结编辑；脚本完成后立即切读新表 |
| Jackpot 无 C 端拉取 | 后台仍配 prize_type=4；后续如需动态转盘再补接口 |
| 其它 pool_code 的 prize_type 语义冲突 | 按 pool 文档约定枚举；通用表结构复用，语义由 pool_code + 文档定义 |
| config 误写 prizeType | Validate 拒绝；迁移脚本不写入 prizeType |
| 业务字段外置导致表膨胀 | 约定：除 `prize_type` 外 lucky_reward 参数一律 config；其它 pool 同理 |

---

## 总体评价

- **赞成** `pool_code = lucky_reward` 作为大转盘唯一奖池编码。
- **采纳**：类型语义 **外层 `prize_type`**；**`unlockInviteCount` 等业务参数进 config**，与通用奖池表设计一致。
- 其它活动复用 `reward_pool_item` 时，同一 `prize_type` 数值在不同 pool 可代表不同含义，需在各自 pool 文档中定义（lucky_reward 池先用 1/2/3/4 四态）。

确认本计划后，按 Phase 1→4 落地。