ok
This commit is contained in:
ray zhou
123
plans/spin_响应补全字段_484d4102.plan.md
Normal file
123
plans/spin_响应补全字段_484d4102.plan.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
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`
|
||||
Reference in New Issue
Block a user