---
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 不变