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

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

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

## 现状依据
- 当前只有一个入口 [`app/api/controller/WalletController.php`](app/api/controller/WalletController.php) 的 `update()`，通过 `type` 分发。
- 分发逻辑在 [`app/api/logic/WalletLogic.php`](app/api/logic/WalletLogic.php) 的 `ACTION_METHOD_MAP`，`bet/win` 已是独立业务方法。
- 入参模型 [`app/api/dto/request/wallet/WalletUpdateRequestDTO.php`](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 同时承载多类交易，`round_id`、`is_end` 仅对 bet/win 有意义。
- 校验器 [`app/validator/Wallet2Validator.php`](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`](app/api/controller/WalletController.php) 新增 `bet()` 与 `win()` 方法，复用统一返回封装。
2. 拆分请求 DTO 与校验场景：
   - 新增 bet/win 专用 DTO（从 `WalletUpdateRequestDTO` 中抽取必要字段）。
   - 在 [`app/validator/Wallet2Validator.php`](app/validator/Wallet2Validator.php) 增加 `SCENE_BET`、`SCENE_WIN`，去掉“按 type 再二次判断”的耦合。
3. 在 Logic 层保持复用：
   - Controller 仍调用 [`app/api/logic/WalletLogic.php`](app/api/logic/WalletLogic.php) 现有 `bet()` / `win()` 实现，避免资金路径重写。
   - `update()` 对 bet/win 请求改为调用新入口共享流程（或内部代理），确保行为一致。
4. 文档与对接迁移：
   - 在 [`README.md`](README.md) 与 [`doc/wallet.md`](doc/wallet.md) 补充“新接口 + 兼容期 + 下线节奏”。
   - 给上游约定迁移窗口，监控 `update(type=bet|win)` 调用量后再决定是否下线。

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