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

name, overview, todos, isProject

name	overview	todos	isProject
toBalance 清零分析	产品要求 To Balance 后客户端仍展示领取金额。推荐**保留 my_amount_qf 清零**（进度已兑现），在 status 接口对已提取用户用 cashout_record 回填 myAmountDisplay；并禁止已提取用户继续 Spin 污染状态。	id content status build-state-withdrawn-display buildStateEntity：playerStatus=已提取时，myAmountDisplay 取自 lucky_reward_cashout_record.amount_qf（大单位） completed id content status block-spin-after-withdrawn executeManualSpin：status=已提取时拒绝 Spin（防 status/my_amount 被改回可提取） completed id content status keep-zero-my-amount toBalance 事务内保留 my_amount_qf=0 + status=已提取（不改删除清零逻辑） completed id content status sync-docs-yapi 更新 lucky_reward_api.md、04 需求 §7、YApi completed	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 读 amount_qf，经 formatAmountDisplay() 返回

改动点：LuckyRewardLogic::buildStateEntity()（约 788–806 行）

// 伪代码
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 一致，语义正确。

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 会改 my_amount_qf / 把 status 改回可提取(2)
• 与需求文档 §7「my_amount 本笔归零」不一致

若走此方案，必须同步加 Spin 拦截，否则状态机会脏。

---

必须配套：已提取用户禁止 Spin

无论是否清零，executeManualSpin() 当前不校验 STATUS_WITHDRAWN。提取后若 spin_available > 0（邀请 Spin 等），仍可能：

• 增加 my_amount_qf
• 把 status 从 3 改回 2

建议在 Spin 入口增加：

if ((int)$activityPlayer->status === LuckyRewardPlayerModel::STATUS_WITHDRAWN) {
    throw new BusinessException('Already withdrawn this cycle');
}

资金安全仍由 cashout_record 幂等保证；此拦截主要为状态一致 + 展示正确。

---

客户端约定（无需新字段）

沿用现有 LuckyRewardStateEntity：

• playerStatus === 3（已提取）→ 隐藏 To Balance / 展示「已领取」态
• myAmountDisplay → 仍展示进度条/金额数字（提取后由服务端回填为领取金额）
• toBalance 当场成功仍可用响应 amountDisplay；之后以 status 为准

不新增 withdrawnAmountDisplay 字段，除非客户端希望区分「当前可提进度」与「历史已提」——当前产品只需展示领取金额，复用 myAmountDisplay 即可。

---

需求文档调整

04_slot_console_活动主流程方案.md §7 第 6 步建议改为：

成功：写 cashout_record；player.status=已提取、my_amount_qf 归零（进度清空）；status 接口对已提取用户 myAmountDisplay 取 cashout_record.amount_qf 展示。

---

实施范围（待你确认后执行）

文件	改动
LuckyRewardLogic.php	buildStateEntity 已提取回填；executeManualSpin 拦截已提取
集成测	新增/扩展：toBalance 后 status 的 myAmountDisplay 等于提取额
lucky_reward_api.md + YApi #554/#561	status 字段说明：已提取时 myAmountDisplay 含义
需求 §7	与实现对齐

不改动：toBalance 内 my_amount_qf = 0（保留）。

---

原分析问题答复（更新结论）

问题	更新结论
必须清零吗？	库内建议继续清零；展示不清零，改由 status 回填
不清零唯一目的「展示金额」？	否；用 cashout_record 回填更干净
重复打款？	仍靠 cashout_record，与是否清零无关