first commit

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

@@ -0,0 +1,53 @@
+---
+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` 入口。