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

name, overview, todos, isProject

name	overview	todos	isProject
精简 Spin 响应	调整 `POST /api/lucky-reward/spin` 的 `SpinResultEntity`：去掉 spinId/prizeType/prizeAmountQf/myAmountDisplay，新增 poolItemId；myAmountQf 改为大单位 float（3 位小数向下取整）。	id content status amount-format-3dp LuckyRewardAmountService 新增 formatAmountDisplay3 + 单测 completed id content status spin-result-entity 精简 SpinResultEntity 字段（poolItemId + myAmountQf float） completed id content status logic-return executeManualSpin 返回新结构 completed id content status docs-yapi 更新 lucky_reward_api.md §3 与 YApi spin 接口 completed	false

手动 Spin 响应精简方案

现状

• 路径：POST /api/lucky-reward/spin，无请求 Body（JWT 鉴权）
• 返回 SpinResultEntity 由 LuckyRewardLogic::executeManualSpin() 组装
• 抽奖结果 DrawResultEntity 已含 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

示例：

{
  "poolItemId": 3,
  "myAmountQf": 9.570,
  "spinAvailable": 0,
  "playerStatus": 1,
  "isDuplicate": false
}

实现步骤

1. 金额格式化（3 位小数）

在 LuckyRewardAmountService 新增专用方法，例如 formatAmountDisplay3(int $amountQf): float：

• 规则：floor($amountQf) / 1000，再 number_format(..., 3, '.', '') 转 float
• 与现有 2 位 formatAmountDisplay() 并存，避免影响 status/open-box/records 等接口

在 LuckyRewardAmountServiceTest 补充用例（如 9570 → 9.570、9576 → 9.576）。

2. 更新 Entity

修改 SpinResultEntity：

• 删除：spinId、prizeType、prizeAmountQf、myAmountDisplay
• 新增：poolItemId（int）
• 修改：myAmountQf 类型 int → float，PHPDoc 注明「大单位 3 位小数展示值」

3. 更新 Logic 组装

LuckyRewardLogic::executeManualSpin() 返回处改为：

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 §3 字段表与示例
• 同步 YApi 手动 Spin 接口（project 14，cat_115 内 spin 对应 ID，与 #553–561 同组）

5. 自检

• 跑 verify-slot-backend.sh + docker php -l
• 跑 LuckyRewardAmountServiceTest、现有 LuckyRewardDrawServiceTest（确认 poolItemId 链路未断）

数据流（变更后）

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