---
name: Spin 响应补全字段
overview: 当前 `POST /api/lucky-reward/spin` 仅返回 `poolItemId` 与抽奖后总 `myAmountQf`，未返回本次命中的 `prizeType` 与实际入账 `prizeAmount`，与 [04 方案](docs/requirements/lucky_rewards/04_slot_console_活动主流程方案.md) 及 PRD 中奖弹窗需求不符。需在 `SpinResultEntity` 补字段并在 Logic 填充。
todos:
  - id: extend-spin-result-entity
    content: SpinResultEntity 增加 prizeType、prizeAmount 及中文属性注释
    status: cancelled
  - id: fill-spin-logic-response
    content: executeManualSpin 返回时填充 drawResult.prizeType 与 formatAmountDisplay(creditedQf)
    status: cancelled
  - id: update-spin-api-docs
    content: 更新 lucky_reward_api.md（及 deploy 冒烟说明）响应字段与示例
    status: cancelled
  - id: add-spin-response-test
    content: 补充单元测覆盖 random/spin/cashout 三种 prizeType 与 prizeAmount 断言
    status: cancelled
isProject: false
---

# Spin 响应补全：中奖类型与中奖金额

## 现状（你的判断是对的）

[`SpinResultEntity`](slot_console/app/entity/luckyReward/SpinResultEntity.php) 当前只有：

| 字段 | 含义 |
|------|------|
| `poolItemId` | 命中的奖池格 ID（前端可对照 `records`/`status` 里的 `poolItems` 反查类型，但**不是直接返回类型**） |
| `myAmountQf` | 抽奖**之后**的 My Amount 总额（大单位 float） |
| `spinAvailable` / `playerStatus` / `isDuplicate` | 状态 |

[`executeManualSpin`](slot_console/app/api/logic/LuckyRewardLogic.php) 事务内已算出 `$drawResult->prizeType` 与 `$creditedQf`（随机金额封顶后的**实际入账**），但组装响应时**未写入 Entity**：

```275:281:slot_console/app/api/logic/LuckyRewardLogic.php
        return new SpinResultEntity([
            'poolItemId' => $drawResult->poolItemId,
            'myAmountQf' => LuckyRewardAmountService::formatAmountDisplay3((int) $activityPlayer->my_amount_qf),
            'spinAvailable' => (int) $activityPlayer->spin_available,
            'playerStatus' => (int) $activityPlayer->status,
            'isDuplicate' => false,
        ]);
```

[`lucky_reward_api.md`](slot_console/doc/lucky_reward_api.md) §3 文档同样未描述 `prizeType` / `prizeAmount`。

与设计文档冲突点：[04 方案 §5 第 7 步](docs/requirements/lucky_rewards/04_slot_console_活动主流程方案.md) 明确要求返回「**命中类型、金额**、刷新后的 my_amount/次数」；PRD §3.2 也要求按类型展示不同中奖弹窗，且随机金额弹窗展示金额须与**实际入账**一致（封顶后 `credited_qf`）。

```mermaid
sequenceDiagram
    participant Client
    participant SpinAPI as POST_spin
    participant Logic as LuckyRewardLogic
    participant Draw as DrawService

    Client->>SpinAPI: 手动 Spin
    SpinAPI->>Logic: executeManualSpin
    Logic->>Draw: draw
    Draw-->>Logic: prizeType + rawPrizeAmountQf
    Logic->>Logic: applySpinPrize -> creditedQf
    Note over Logic: 现况：prizeType/creditedQf 只写 DB 与日志
    Logic-->>Client: poolItemId + myAmountQf（缺本次中奖字段）
```

---

## 建议补全方案

### 1. 扩展 `SpinResultEntity`

在 [`SpinResultEntity.php`](slot_console/app/entity/luckyReward/SpinResultEntity.php) 新增：

- **`prizeType`**（`int`）：见 [`RewardPoolItemModel::PRIZE_TYPE_*`](slot_console/app/model/common/RewardPoolItemModel.php)
  - `1` 随机金额 / `2` 1x Spin / `3` Cash Out
- **`prizeAmount`**（`float`）：**本次 Spin 实际展示/入账金额**（大单位，与 `openBox.initAmount`、`records.items[].prizeAmount` 口径一致）

赋值规则（与落库 [`spin_record.prize_amount_qf`](slot_console/app/api/logic/LuckyRewardLogic.php) 一致）：

| prizeType | prizeAmount |
|-----------|-------------|
| 随机金额 (1) | `formatAmountDisplay($creditedQf)`（封顶后实际入账，非 raw 随机值） |
| 1x Spin (2) | `0` |
| Cash Out (3) | `0` |

保留现有 `poolItemId`（转盘停格动画）与 `myAmountQf`（更新后总额），不破坏兼容。

### 2. Logic 填充

[`LuckyRewardLogic::executeManualSpin`](slot_console/app/api/logic/LuckyRewardLogic.php) 返回处增加：

```php
'prizeType' => $drawResult->prizeType,
'prizeAmount' => LuckyRewardAmountService::formatAmountDisplay($creditedQf),
```

无需改 Controller（仍 `$spinResultEntity->activeData()`）。

### 3. 文档

更新 [`lucky_reward_api.md`](slot_console/doc/lucky_reward_api.md) §3 响应表与 JSON 示例；[`lucky_reward_deploy.md`](slot_console/doc/lucky_reward_deploy.md) 冒烟项可补一句「spin 响应含 prizeType/prizeAmount」。

可选：同步 [04 方案](docs/requirements/lucky_rewards/04_slot_console_活动主流程方案.md) 示例 JSON（若文档有旧字段名）。

### 4. 测试

- 新增或扩展 Logic 单元测（mock draw 结果）：断言 random 命中时 `prizeAmount == creditedQf` 展示值、`prizeType == 1`；Spin/CashOut 时 `prizeAmount == 0`。
- 若有 YApi #557 spin 接口文档，一并更新字段说明。

---

## 不在本次范围

- 不改抽奖算法、封顶逻辑、Redis 锁。
- 不改 `records` 列表结构（Record Tab 仍只有 `prizeAmount`，无 `prizeType`；若前端 Record 也要类型可另开需求）。
- `isDuplicate` 目前恒为 `false`（无 spin 幂等重放路径），本次不扩展。

---

## 前端使用建议（供联调）

- **停格**：`poolItemId`
- **弹窗类型**：`prizeType`
- **弹窗金额 / 飞金币**：`prizeAmount`（仅 type=1 时 >0）
- **进度条/My Amount 刷新**：`myAmountQf`