---
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 被清理