91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
---
|
||
name: 中间派奖余额可见化
|
||
overview: 在保持 Final Settlement 真账口径不变的前提下，让 is_end=0 中间派奖实时反映到三方读取的余额（接口返回和钱包查询）。
|
||
todos:
|
||
- id: pending-win-keys
|
||
content: 设计并接入 pending round/total 与 dedupe Redis key
|
||
status: pending
|
||
- id: win-is-end-branch
|
||
content: 实现 is_end=0 累计展示、is_end=1 合并结算与清理
|
||
status: pending
|
||
- id: wallet-query-overlay
|
||
content: 让 wallet 查询叠加 pending total 返回最新展示余额
|
||
status: pending
|
||
- id: dto-validator-update
|
||
content: 补齐 is_end DTO 与 win round_id 校验
|
||
status: pending
|
||
- id: regression-cases
|
||
content: 验证多次派奖余额可见、最终结算、幂等与失败重试场景
|
||
status: pending
|
||
isProject: false
|
||
---
|
||
|
||
# 中间派奖余额可见化（is_end）改造计划
|
||
|
||
## 目标
|
||
解决“多次派奖时三方读取余额不更新”的问题，同时保持 `win.md` 的核心原则：
|
||
- 真正入账、Lot 回流、转化/解锁只在 `is_end=1`（Final Settlement）执行
|
||
- `is_end=0` 仅做中间派奖累计与展示余额更新
|
||
|
||
## 核心思路
|
||
在 Redis 维护“待结算派奖池（Pending Win）”，并把它叠加到对外返回余额：
|
||
- DB 里的 `withdraw/deposit/bonus` 仍保持真实账
|
||
- 对外给三方的余额 = 真实账 + pendingWin
|
||
|
||
这样能保证：
|
||
- 三方实时看到余额变化
|
||
- 不破坏现有 `WinService` 的 Round Final Settlement 账务逻辑
|
||
|
||
## 具体改造
|
||
|
||
### 1) 新增 Pending Win 缓存层
|
||
修改 [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php)：新增 key
|
||
- `wallet:win:pending:round:{uid}:{currency}:{round_id}`（每局中间派奖累计）
|
||
- `wallet:win:pending:total:{uid}:{currency}`（用户币种维度累计，供快速读余额）
|
||
- `wallet:win:dedupe:{uid}:{currency}:{round_id}:{biz_id}`（中间派奖严格幂等）
|
||
|
||
### 2) win 分支行为
|
||
修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`：
|
||
- `is_end=0`：
|
||
- 命中 dedupe 直接返回
|
||
- 未命中则 `INCRBY pending:round` 与 `INCRBY pending:total`
|
||
- 返回余额时把 `pending:total` 叠加到 `withdraw`（仅对外展示）
|
||
- 不调用 `WinService::execute`、不写 `BIZ_TYPE_WIN`
|
||
- `is_end=1`：
|
||
- 读取 `pending:round`，`finalWin = fee + pendingRound`
|
||
- 用 `finalWin` 调用现有 [app/service/wallet/WinService.php](app/service/wallet/WinService.php)
|
||
- 成功后清理 `pending:round` 并从 `pending:total` 扣除对应值
|
||
- 返回余额按真实账（此时 pending 已回收）
|
||
|
||
### 3) 钱包查询返回也要可见化
|
||
修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `query()` 返回：
|
||
- 将 `pending:total` 叠加到返回字段 `w/withdraw`
|
||
- 这样第三方无论读 `win` 返回还是调用 `wallet` 查询，都看到“最新展示余额”
|
||
|
||
### 4) 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` 必传
|
||
|
||
## 一致性与幂等
|
||
- `is_end=0`：Redis dedupe（biz_id 级）防重复累计
|
||
- `is_end=1`：延续现有 `wallet_log(uid,biz_id,biz_type=win)` 幂等
|
||
- 若 Final 失败，不清 pending，便于重试恢复
|
||
|
||
## 风险说明（需明确）
|
||
- 该方案是“展示余额实时、真账延后”：若上游把展示余额当可立即可下注余额，可能出现下注时余额校验不一致。
|
||
- 若你需要“中间派奖立即可下注”，则要走另一套方案（中间账临时入库 + Final 对冲重分配），改动会显著更大。
|
||
|
||
## 改动文件
|
||
- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php)
|
||
- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php)
|
||
- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php)
|
||
- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php)
|
||
|
||
## 验收场景
|
||
- 多次 `is_end=0` 后，`win` 返回余额递增
|
||
- 多次 `is_end=0` 后，`wallet` 查询余额递增
|
||
- `is_end=1` 触发后，final 入账金额 = 中间累计 + 最后一笔
|
||
- 重放同一 `is_end=0` `biz_id` 不重复累计
|
||
- 重放同一 `is_end=1` `biz_id` 不重复结算 |