ok

plans/精简_spin_响应_210342c6.plan.md

@@ -0,0 +1,119 @@
+---
+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 不变