ok

plans/tobalance_清零分析_8a4b21aa.plan.md

@@ -0,0 +1,136 @@
+---
+name: toBalance 清零分析
+overview: 产品要求 To Balance 后客户端仍展示领取金额。推荐**保留 my_amount_qf 清零**（进度已兑现），在 status 接口对已提取用户用 cashout_record 回填 myAmountDisplay；并禁止已提取用户继续 Spin 污染状态。
+todos:
+  - id: build-state-withdrawn-display
+    content: buildStateEntity：playerStatus=已提取时，myAmountDisplay 取自 lucky_reward_cashout_record.amount_qf（大单位）
+    status: completed
+  - id: block-spin-after-withdrawn
+    content: executeManualSpin：status=已提取时拒绝 Spin（防 status/my_amount 被改回可提取）
+    status: completed
+  - id: keep-zero-my-amount
+    content: toBalance 事务内保留 my_amount_qf=0 + status=已提取（不改删除清零逻辑）
+    status: completed
+  - id: sync-docs-yapi
+    content: 更新 lucky_reward_api.md、04 需求 §7、YApi
+    status: completed
+isProject: false
+---
+
+# To Balance 后展示领取金额 — 方案（迭代）
+
+## 产品诉求（新增）
+
+客户端 To Balance **成功之后**，仍要在活动页展示**领取时的金额**（含刷新 status、再次进入活动，不能只靠 toBalance 响应本地缓存）。
+
+当前问题：`toBalance` 把 `my_amount_qf = 0` 后，`POST /api/lucky-reward/status` 的 `myAmountDisplay` 变为 `0.00`，客户端无法继续展示 $10.00 等已领取金额。
+
+---
+
+## 推荐方案：库内清零 + status 展示回填（推荐）
+
+**不改为「不清零 my_amount_qf」**，而是区分「活动进度」与「展示金额」：
+
+| 层 | 行为 |
+| --- | --- |
+| DB `my_amount_qf` | **继续清零** — 表示本轮可 Spin 累积的进度已兑现，避免尾差/Spin 叠加 |
+| DB `status` | **已提取(3)** — 客户端据此隐藏 To Balance 按钮 |
+| status 响应 `myAmountDisplay` | **已提取时**从 [`LuckyRewardCashoutRecordModel::findSuccessByUidAndCycle`](slot_console/app/model/common/LuckyRewardCashoutRecordModel.php) 读 `amount_qf`，经 `formatAmountDisplay()` 返回 |
+
+改动点：[`LuckyRewardLogic::buildStateEntity()`](slot_console/app/api/logic/LuckyRewardLogic.php)（约 788–806 行）
+
+```php
+// 伪代码
+if ($hasOpenedBox && (int)$activityPlayer->status === STATUS_WITHDRAWN) {
+    $cashout = LuckyRewardCashoutRecordModel::findSuccessByUidAndCycle($uid, $cycleId);
+    $myAmountQf = $cashout !== null ? (int)$cashout->amount_qf : 0;
+} else {
+    $myAmountQf = $hasOpenedBox ? (int)$activityPlayer->my_amount_qf : 0;
+}
+```
+
+展示值为**实际入账金额**（`floor(my_amount/10)*10` 后的值），与 toBalance 响应 `amountDisplay` 一致，语义正确。
+
+```mermaid
+flowchart TD
+  toBalance[toBalance 成功] --> zero["my_amount_qf=0\nstatus=已提取"]
+  zero --> cashoutRow[cashout_record 保留 amount_qf]
+  cashoutRow --> statusPoll[客户端调 status]
+  statusPoll --> display["myAmountDisplay=提取金额\nplayerStatus=3"]
+```
+
+---
+
+## 备选方案：取消清零（不推荐单独使用）
+
+删除 `my_amount_qf = 0` 一行，status 直接读库内 `my_amount_qf` 即可展示。
+
+**缺点**（见原分析）：
+
+- 尾差残留（转入 floor 后库内仍 > 转入额）
+- 提取后若还有 Spin，[`executeManualSpin`](slot_console/app/api/logic/LuckyRewardLogic.php) 会改 `my_amount_qf` / 把 `status` 改回可提取(2)
+- 与需求文档 §7「my_amount 本笔归零」不一致
+
+若走此方案，**必须**同步加 Spin 拦截，否则状态机会脏。
+
+---
+
+## 必须配套：已提取用户禁止 Spin
+
+无论是否清零，[`executeManualSpin()`](slot_console/app/api/logic/LuckyRewardLogic.php) 当前**不校验** `STATUS_WITHDRAWN`。提取后若 `spin_available > 0`（邀请 Spin 等），仍可能：
+
+- 增加 `my_amount_qf`
+- 把 `status` 从 3 改回 2
+
+建议在 Spin 入口增加：
+
+```php
+if ((int)$activityPlayer->status === LuckyRewardPlayerModel::STATUS_WITHDRAWN) {
+    throw new BusinessException('Already withdrawn this cycle');
+}
+```
+
+资金安全仍由 `cashout_record` 幂等保证；此拦截主要为**状态一致 + 展示正确**。
+
+---
+
+## 客户端约定（无需新字段）
+
+沿用现有 [`LuckyRewardStateEntity`](slot_console/app/entity/luckyReward/LuckyRewardStateEntity.php)：
+
+- `playerStatus === 3`（已提取）→ 隐藏 To Balance / 展示「已领取」态
+- `myAmountDisplay` → 仍展示进度条/金额数字（提取后由服务端回填为领取金额）
+- toBalance 当场成功仍可用响应 `amountDisplay`；之后以 status 为准
+
+**不新增** `withdrawnAmountDisplay` 字段，除非客户端希望区分「当前可提进度」与「历史已提」——当前产品只需展示领取金额，复用 `myAmountDisplay` 即可。
+
+---
+
+## 需求文档调整
+
+[`04_slot_console_活动主流程方案.md`](docs/requirements/lucky_rewards/04_slot_console_活动主流程方案.md) §7 第 6 步建议改为：
+
+> 成功：写 cashout_record；`player.status=已提取`、**`my_amount_qf` 归零（进度清空）**；**status 接口对已提取用户 `myAmountDisplay` 取 cashout_record.amount_qf 展示**。
+
+---
+
+## 实施范围（待你确认后执行）
+
+| 文件 | 改动 |
+| --- | --- |
+| [`LuckyRewardLogic.php`](slot_console/app/api/logic/LuckyRewardLogic.php) | `buildStateEntity` 已提取回填；`executeManualSpin` 拦截已提取 |
+| 集成测 | 新增/扩展：toBalance 后 status 的 `myAmountDisplay` 等于提取额 |
+| [`lucky_reward_api.md`](slot_console/doc/lucky_reward_api.md) + YApi #554/#561 | status 字段说明：已提取时 myAmountDisplay 含义 |
+| 需求 §7 | 与实现对齐 |
+
+**不改动**：`toBalance` 内 `my_amount_qf = 0`（保留）。
+
+---
+
+## 原分析问题答复（更新结论）
+
+| 问题 | 更新结论 |
+| --- | --- |
+| 必须清零吗？ | **库内建议继续清零**；展示不清零，改由 status 回填 |
+| 不清零唯一目的「展示金额」？ | **否**；用 cashout_record 回填更干净 |
+| 重复打款？ | 仍靠 cashout_record，与是否清零无关 |