active

plans/is_end派奖结算改造_14ce4dc5.plan.md

@@ -1,78 +0,0 @@
----
-name: is_end派奖结算改造
-overview: 基于现有 BetFunding/WinService 实现，新增 is_end 分支：中间派奖仅累计不入账，结束派奖统一按 Round Final Settlement 入账；并对中间派奖增加 biz_id 严格幂等。
-todos:
-  - id: dto-validator-is-end
-    content: 扩展 DTO 与校验器，支持 is_end 并强制 win 场景 round_id 校验
-    status: pending
-  - id: redis-win-keys
-    content: 新增 pending/dedupe Redis key 生成方法与 TTL 约定
-    status: pending
-  - id: logic-win-branching
-    content: 在 WalletLogic::win 中实现 is_end=0 累计与 is_end=1 最终结算分支
-    status: pending
-  - id: idempotency-regression
-    content: 补充关键回归场景说明并验证与现有幂等不冲突
-    status: pending
-isProject: false
----
-
-# is_end 驱动的派奖结算改造计划
-
-## 目标
-让 `win` 接口支持第三方 `is_end` 语义：
-- `is_end=0`：仅记录/累计本局派奖，不做钱包入账、不做 Lot 终态收敛
-- `is_end=1`：将本次派奖 + 已累计派奖合并后，执行一次 Final Settlement（现有 `WinService::execute`）
-
-## 现状结论（基于代码）
-- 入口路由在 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `type=win -> win()`。
-- Final Settlement 主流程在 [app/service/wallet/WinService.php](app/service/wallet/WinService.php)。
-- 当前 `win` 默认即 Final Settlement，不区分中间派奖事件。
-- 下注资金事实表在 [app/model/multi/WalletBetFundingModel.php](app/model/multi/WalletBetFundingModel.php)。
-
-## 实现方案（按你选择）
-### 1) 入参扩展与校验
-- 在 [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 增加字段：`is_end`（默认 `1`，仅允许 `0|1`）。
-- 在 [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php)：
-  - 增加 `is_end` 校验规则（整数且取值 `0/1`）。
-  - 将 `win` 也纳入 `round_id` 必传校验（当前仅 bet 必传）。
-
-### 2) Redis Key 设计
-- 在 [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}`：中间派奖幂等标记
-- 过期策略建议：`pending` 48h，`dedupe` 72h（与重放窗口对齐）。
-
-### 3) win 主流程分支
-- 修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`：
-  - `is_end=0`：
-    - 命中 dedupe key 则直接返回当前钱包（幂等）
-    - 未命中则将 `fee` 累加到 pending key，写 dedupe key，返回当前钱包（不写 `BIZ_TYPE_WIN` 流水）
-  - `is_end=1`：
-    - 读取 pending 累计并与本次 `fee` 合并为 `finalWinAmount`
-    - 用 `finalWinAmount` 调用现有 `WinService::execute`
-    - 事务提交后清理 pending key（失败不清）
-
-### 4) 幂等与一致性
-- `is_end=1` 继续沿用现有 `wallet_log(uid,biz_id,biz_type=win)` 幂等。
-- `is_end=0` 使用 Redis dedupe key 防重，避免重复累计。
-- 若 `is_end=1` 无待分配 funding，保持当前行为（报错），便于暴露上游时序问题。
-
-### 5) 兼容与回归
-- 默认 `is_end=1`，兼容未传该字段的旧调用。
-- 回归场景：
-  - 单次结算（只发 `is_end=1`）
-  - 多次派奖（多条 `is_end=0` + 一条 `is_end=1`）
-  - `is_end=0` 重放同 biz_id 不重复累计
-  - `is_end=1` 重放同 biz_id 不重复入账
-  - `is_end=1` 失败后 pending 不丢失
-
-## 关键改动文件
-- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php)
-- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php)
-- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php)
-- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php)
-
-## 风险与边界
-- 该方案不新增 `wallet_game_round` / `wallet_game_round_event` 持久化表；中间派奖仅 Redis 暂存，审计粒度弱于 DB 事件流。
-- 若某局长期无 `is_end=1`，pending 依赖 TTL 过期清理。后续可升级为 DB 事件表方案。