first commit

plans/is_end结算回退方案_180cfb46.plan.md

@@ -0,0 +1,57 @@
+---
+name: is_end结算回退方案
+overview: 取消“中间派奖实时余额可见化”调整，回退到严格 Final Settlement 方案：is_end=0 仅累计，is_end=1 才入账与状态收敛。
+todos:
+  - id: dto-validator-is-end
+    content: 增加 is_end 字段及 win round_id 强校验
+    status: completed
+  - id: pending-dedupe-keys
+    content: 新增 pending 与 dedupe Redis key 并接入 is_end=0 累计
+    status: completed
+  - id: win-final-merge
+    content: is_end=1 合并 pending 后调用现有 WinService 结算并清理缓存
+    status: completed
+  - id: regression-check
+    content: 回归验证多次派奖累计、最终结算与幂等行为
+    status: completed
+isProject: false
+---
+
+# is_end 结算回退方案（不做中间余额更新）
+
+## 变更决策
+取消这部分：
+- 多次派奖期间（`is_end=0`）对第三方返回余额进行实时更新
+- 对 `wallet` 查询叠加 pending 金额
+
+保留并执行：
+- `is_end=0`：仅做中间派奖累计，不改钱包余额、不做 Lot 收敛
+- `is_end=1`：合并累计派奖后一次 Final Settlement（调用现有 win 主流程）
+
+## 实现边界
+- 严格遵循 [doc/win.md](doc/win.md) 的“Final Settlement 才做真实入账”原则
+- 不引入展示层余额叠加逻辑，避免展示余额与真实可下注余额不一致
+
+## 具体改造
+1. DTO / 校验
+- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 增加 `is_end`（默认 `1`）
+- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php)
+  - 增加 `is_end` 仅允许 `0/1`
+  - `win` 场景强制 `round_id` 必传
+
+2. Redis 累计与幂等（仅中间派奖）
+- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php) 增加 key：
+  - `wallet:win:pending:{uid}:{currency}:{round_id}`
+  - `wallet:win:dedupe:{uid}:{currency}:{round_id}:{biz_id}`
+- `is_end=0` 命中 dedupe 则忽略，未命中则累计 pending
+
+3. win 结算分支
+- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php)
+  - `is_end=0`：只累计并返回当前真实钱包余额
+  - `is_end=1`：读取 pending 并与本次 `fee` 合并后走现有 `WinService::execute`，成功后清理 pending
+
+## 验收
+- 多条 `is_end=0` 不触发真实入账
+- 一条 `is_end=1` 触发一次最终结算，金额=中间累计+末笔
+- 中间派奖重复 `biz_id` 不重复累计
+- Final 失败时 pending 不丢失，可重试