cursor/plans/wallet-bet-win-api-split_8d6f7dea.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
wallet-bet-win-api-split	评估并规划将 bet/win 从统一 update 入口中显式拆分为独立 API，同时保留兼容性与幂等语义。	id content status add-bet-win-controller-endpoints 新增 wallet/bet 与 wallet/win 控制器入口，保留 update 兼容 completed id content status split-validator-dto 拆分 bet/win DTO 与校验场景，减少 type 分支耦合 completed id content status proxy-update-for-compat 让 update 的 bet/win 分支复用新入口流程，确保行为完全一致 completed id content status docs-and-migration 补充 README/doc 迁移说明与灰度/下线节奏 completed	false

Bet/Win API 拆分评估与迁移计划

结论

• 对资金域来说，对外 API 语义上拆分 bet / win 会更好：可读性、接入防错、风控审计与权限隔离都会更清晰。
• 但不建议直接废弃 update；建议采用“新增独立接口 + update 兼容转发 + 渐进下线”的迁移路线，避免影响现有上游与历史幂等键。

现状依据

• 当前只有一个入口 app/api/controller/WalletController.php 的 update()，通过 type 分发。
• 分发逻辑在 app/api/logic/WalletLogic.php 的 ACTION_METHOD_MAP，bet/win 已是独立业务方法。
• 入参模型 app/api/dto/request/wallet/WalletUpdateRequestDTO.php 同时承载多类交易，round_id、is_end 仅对 bet/win 有意义。
• 校验器 app/validator/Wallet2Validator.php 也是“单场景 + 按 type 条件校验”，存在语义混杂。

目标形态

• 提供显式 API：wallet/bet、wallet/win（自动路由下对应 Controller 方法）。
• wallet/update 保留为兼容入口：内部仅做 DTO 转换与分发，不承载新能力。
• 资金与幂等规则保持不变：仍以 biz_id + type（必要时叠加 round_id）确保可追溯与幂等。

实施步骤

1. 在 app/api/controller/WalletController.php 新增 bet() 与 win() 方法，复用统一返回封装。
2. 拆分请求 DTO 与校验场景：
   • 新增 bet/win 专用 DTO（从 WalletUpdateRequestDTO 中抽取必要字段）。
   • 在 app/validator/Wallet2Validator.php 增加 SCENE_BET、SCENE_WIN，去掉“按 type 再二次判断”的耦合。
3. 在 Logic 层保持复用：
   • Controller 仍调用 app/api/logic/WalletLogic.php 现有 bet() / win() 实现，避免资金路径重写。
   • update() 对 bet/win 请求改为调用新入口共享流程（或内部代理），确保行为一致。
4. 文档与对接迁移：
   • 在 README.md 与 doc/wallet.md 补充“新接口 + 兼容期 + 下线节奏”。
   • 给上游约定迁移窗口，监控 update(type=bet|win) 调用量后再决定是否下线。

验证要点

• 幂等：重复 biz_id 命中行为与现状一致。
• Round：win 的 is_end=0/1 中间派奖与最终结算语义不变。
• 资金正确性：下注扣款顺序、派奖分配、流水字段不变。
• 可回滚：任一阶段可回退为仅使用 update 入口。