cursor/plans/spin_响应补全字段_484d4102.plan.md

name, overview, todos, isProject

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

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

现状（你的判断是对的）

SpinResultEntity 当前只有：

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

executeManualSpin 事务内已算出 $drawResult->prizeType 与 $creditedQf（随机金额封顶后的实际入账），但组装响应时未写入 Entity：

        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 §3 文档同样未描述 prizeType / prizeAmount。

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

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 新增：

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

赋值规则（与落库 spin_record.prize_amount_qf 一致）：

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

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

2. Logic 填充

LuckyRewardLogic::executeManualSpin 返回处增加：

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

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

3. 文档

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

可选：同步 04 方案 示例 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