first commit

plans/win返回余额叠加pending_151a7ce9.plan.md

@@ -0,0 +1,45 @@
+---
+name: win返回余额叠加pending
+overview: 仅在 win 派奖流程中，对返回给第三方的余额叠加本局 pending 派奖，解决连续派奖期间玩家看到余额不增长的问题；不改其他接口。
+todos:
+  - id: win-response-overlay
+    content: 仅在 win is_end=0 返回值叠加 pendingRoundAmount 到 w/withdraw
+    status: completed
+  - id: idempotent-display-check
+    content: 确认 dedupe 命中时返回余额不重复增长
+    status: completed
+  - id: final-settlement-regression
+    content: 确认 is_end=1 结算与 pending 清理行为不受影响
+    status: completed
+isProject: false
+---
+
+# win 派奖返回余额叠加 pending（仅 win 场景）
+
+## 目标
+在不改变真实账务入账时机（仍以 `is_end=1` Final Settlement 为准）的前提下，让第三方在连续派奖时拿到“可展示余额”：
+- `is_end=0`：返回余额包含本局 pending
+- 其他场景：不改
+
+## 当前问题定位
+在 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()` 中：
+- `is_end=0` 已做 pending 累计
+- 但返回值仍是 DB 真实余额（未叠加 pending），导致第三方展示不变
+
+## 最小改动方案
+仅修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`：
+1. 在 `is_end=0` 分支中，累计完成后读取 `pendingRoundAmount = getPendingWinByRound()`。
+2. 返回给第三方时，将 `withdraw`/`w` 做展示叠加：
+   - `w = wallet.withdraw_balance + pendingRoundAmount`
+   - `withdraw = wallet.withdraw_balance + pendingRoundAmount`
+3. `deposit` / `bonus` 保持真实值（不动）。
+4. `is_end=1` 维持现有逻辑：合并 pending 后走真实结算并清理 pending。
+
+## 兼容与风险
+- 仅影响 `type=win` 的返回体，不影响 DB、Lot、流水、下注规则。
+- 若第三方把 `w` 当“可立即下注余额”，会产生语义差异（展示值 > 真实可用）；但你当前业务前提是第三方只负责展示。
+
+## 验收点
+- 连续 `is_end=0`：返回 `w/withdraw` 逐次增长（包含 pending）
+- 重复 `biz_id` 的 `is_end=0`：返回值不重复增长
+- `is_end=1` 后：返回值与真实结算后余额一致，pending 被清理