120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
---
|
||
name: 精简 Spin 响应
|
||
overview: 调整 `POST /api/lucky-reward/spin` 的 `SpinResultEntity`：去掉 spinId/prizeType/prizeAmountQf/myAmountDisplay，新增 poolItemId；myAmountQf 改为大单位 float（3 位小数向下取整）。
|
||
todos:
|
||
- id: amount-format-3dp
|
||
content: LuckyRewardAmountService 新增 formatAmountDisplay3 + 单测
|
||
status: completed
|
||
- id: spin-result-entity
|
||
content: 精简 SpinResultEntity 字段（poolItemId + myAmountQf float）
|
||
status: completed
|
||
- id: logic-return
|
||
content: executeManualSpin 返回新结构
|
||
status: completed
|
||
- id: docs-yapi
|
||
content: 更新 lucky_reward_api.md §3 与 YApi spin 接口
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 手动 Spin 响应精简方案
|
||
|
||
## 现状
|
||
|
||
- 路径：`POST /api/lucky-reward/spin`，**无请求 Body**（JWT 鉴权）
|
||
- 返回 [`SpinResultEntity`](slot_console/app/entity/luckyReward/SpinResultEntity.php) 由 [`LuckyRewardLogic::executeManualSpin()`](slot_console/app/api/logic/LuckyRewardLogic.php) 组装
|
||
- 抽奖结果 [`DrawResultEntity`](slot_console/app/entity/luckyReward/DrawResultEntity.php) 已含 `poolItemId`（与活动详情 `poolItems[].id` 同源，即 `reward_pool_item.id`）
|
||
|
||
## 目标响应 `data`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| poolItemId | int | 命中的奖池项 ID（客户端对照 `poolItems` 定位格子/本地图） |
|
||
| myAmountQf | float | 抽奖后 My Amount，**大单位、3 位小数、向下取整**（字段名沿用，语义变更） |
|
||
| spinAvailable | int | 剩余 Spin 次数 |
|
||
| playerStatus | int | 玩家状态 |
|
||
| isDuplicate | bool | 幂等重复（当前手动 Spin 仍固定 `false`） |
|
||
|
||
**删除：** `spinId`、`prizeType`、`prizeAmountQf`、`myAmountDisplay`
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"poolItemId": 3,
|
||
"myAmountQf": 9.570,
|
||
"spinAvailable": 0,
|
||
"playerStatus": 1,
|
||
"isDuplicate": false
|
||
}
|
||
```
|
||
|
||
## 实现步骤
|
||
|
||
### 1. 金额格式化（3 位小数）
|
||
|
||
在 [`LuckyRewardAmountService`](slot_console/app/service/luckyReward/LuckyRewardAmountService.php) 新增专用方法，例如 `formatAmountDisplay3(int $amountQf): float`：
|
||
|
||
- 规则：`floor($amountQf) / 1000`，再 `number_format(..., 3, '.', '')` 转 float
|
||
- 与现有 2 位 `formatAmountDisplay()` 并存，避免影响 status/open-box/records 等接口
|
||
|
||
在 [`LuckyRewardAmountServiceTest`](slot_console/tests/Unit/LuckyRewardAmountServiceTest.php) 补充用例（如 `9570 → 9.570`、`9576 → 9.576`）。
|
||
|
||
### 2. 更新 Entity
|
||
|
||
修改 [`SpinResultEntity`](slot_console/app/entity/luckyReward/SpinResultEntity.php)：
|
||
|
||
- 删除：`spinId`、`prizeType`、`prizeAmountQf`、`myAmountDisplay`
|
||
- 新增：`poolItemId`（int）
|
||
- 修改：`myAmountQf` 类型 `int → float`，PHPDoc 注明「大单位 3 位小数展示值」
|
||
|
||
### 3. 更新 Logic 组装
|
||
|
||
[`LuckyRewardLogic::executeManualSpin()`](slot_console/app/api/logic/LuckyRewardLogic.php) 返回处改为：
|
||
|
||
```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,
|
||
]);
|
||
```
|
||
|
||
- 服务端仍生成 `manualSpinId` 写库/日志，**仅不再返回给客户端**
|
||
- `prize_type`、`prize_amount_qf` 仍写入 `lucky_reward_spin_record`，Record Tab 不受影响
|
||
|
||
### 4. 文档与 YApi
|
||
|
||
- 更新 [`slot_console/doc/lucky_reward_api.md`](slot_console/doc/lucky_reward_api.md) §3 字段表与示例
|
||
- 同步 YApi 手动 Spin 接口（project 14，cat_115 内 spin 对应 ID，与 #553–561 同组）
|
||
|
||
### 5. 自检
|
||
|
||
- 跑 `verify-slot-backend.sh` + docker `php -l`
|
||
- 跑 `LuckyRewardAmountServiceTest`、现有 `LuckyRewardDrawServiceTest`（确认 `poolItemId` 链路未断）
|
||
|
||
## 数据流（变更后）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client
|
||
participant SpinAPI as POST_spin
|
||
participant Logic as LuckyRewardLogic
|
||
participant Draw as DrawService
|
||
participant DB as spin_record
|
||
|
||
Client->>SpinAPI: JWT, no body
|
||
SpinAPI->>Logic: executeManualSpin
|
||
Logic->>Draw: draw(poolItems)
|
||
Draw-->>Logic: poolItemId, prizeType
|
||
Logic->>DB: spin_id, prize_type, prize_amount_qf
|
||
Logic-->>Client: poolItemId, myAmountQf(3dp), spinAvailable, playerStatus
|
||
```
|
||
|
||
## 影响范围
|
||
|
||
- **Breaking change**：依赖旧 Spin 响应字段的前端需改为用 `poolItemId` 对照 `poolItems` 展示命中格；My Amount 读 `myAmountQf`（float 3 位）
|
||
- **无改动**：请求体仍为空；Controller/Validator 无需改；后台奖池项 CRUD 不变
|