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

name, overview, todos, isProject

name	overview	todos	isProject
is_end结算回退方案	取消“中间派奖实时余额可见化”调整，回退到严格 Final Settlement 方案：is_end=0 仅累计，is_end=1 才入账与状态收敛。	id content status dto-validator-is-end 增加 is_end 字段及 win round_id 强校验 completed id content status pending-dedupe-keys 新增 pending 与 dedupe Redis key 并接入 is_end=0 累计 completed id content status win-final-merge is_end=1 合并 pending 后调用现有 WinService 结算并清理缓存 completed id content status regression-check 回归验证多次派奖累计、最终结算与幂等行为 completed	false

is_end 结算回退方案（不做中间余额更新）

变更决策

取消这部分：

• 多次派奖期间（is_end=0）对第三方返回余额进行实时更新
• 对 wallet 查询叠加 pending 金额

保留并执行：

• is_end=0：仅做中间派奖累计，不改钱包余额、不做 Lot 收敛
• is_end=1：合并累计派奖后一次 Final Settlement（调用现有 win 主流程）

实现边界

• 严格遵循 doc/win.md 的“Final Settlement 才做真实入账”原则
• 不引入展示层余额叠加逻辑，避免展示余额与真实可下注余额不一致

具体改造

1. DTO / 校验

• app/api/dto/request/wallet/WalletUpdateRequestDTO.php 增加 is_end（默认 1）
• app/validator/Wallet2Validator.php
  • 增加 is_end 仅允许 0/1
  • win 场景强制 round_id 必传

2. Redis 累计与幂等（仅中间派奖）

• 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
  • is_end=0：只累计并返回当前真实钱包余额
  • is_end=1：读取 pending 并与本次 fee 合并后走现有 WinService::execute，成功后清理 pending

验收

• 多条 is_end=0 不触发真实入账
• 一条 is_end=1 触发一次最终结算，金额=中间累计+末笔
• 中间派奖重复 biz_id 不重复累计
• Final 失败时 pending 不丢失，可重试