first commit

plans/phpunit_钱包链路测试_003ec505.plan.md

@@ -0,0 +1,84 @@
+---
+name: PHPUnit 钱包链路测试
+overview: 补齐本仓库的 PHPUnit 基建，并新增 register/bet/win 集成测试用例，默认在本地 php82 容器执行、连接真实依赖，以 HTTP 结果与余额变化作为核心断言。
+todos:
+  - id: setup-phpunit
+    content: 补齐 PHPUnit 基建（composer require-dev、phpunit.xml、tests/bootstrap.php）
+    status: completed
+  - id: implement-feature-test
+    content: 实现 register/bet/win 集成测试与幂等/异常断言
+    status: completed
+  - id: run-in-container
+    content: 在 php82 容器执行测试并根据结果修正
+    status: completed
+  - id: document-runbook
+    content: 补充测试执行说明与可选增强项
+    status: completed
+isProject: false
+---
+
+# PHPUnit Register/Bet/Win 测试落地计划
+
+## 默认口径（基于当前信息）
+- 测试框架：PHPUnit（当前仓库尚无 `phpunit.xml` 和 `tests/`）。
+- 执行环境：本地 `php82` 容器。
+- 依赖模式：默认连本地真实 MySQL/Redis（贴近联调）。
+- 断言范围：默认先做 API 返回与余额变化断言；DB 深断言作为第二阶段可选扩展。
+
+## 现状结论
+- 缺少 PHPUnit 基建：未发现 `phpunit*.xml` 与 `tests/` 目录。
+- `register/bet/win` 入口与逻辑已具备：
+  - 接口入口：[app/api/controller/WalletController.php](app/api/controller/WalletController.php)
+  - 业务编排：[app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php)
+  - 注册服务：[app/service/wallet/RegisterService.php](app/service/wallet/RegisterService.php)
+
+## 实施步骤
+1. **补测试基建**
+- 在 `require-dev` 增加 `phpunit/phpunit`。
+- 新增 `phpunit.xml`（定义 `tests/` 目录、bootstrap、环境变量覆盖）。
+- 新增 `tests/bootstrap.php`（加载自动加载与测试环境初始化）。
+
+2. **新增钱包链路集成测试**
+- 新建测试文件：[tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php)
+- 用例覆盖：
+  - `register` 成功（通过 `wallet/update` + `type=register`）
+  - `bet` 成功并校验扣款后余额变化
+  - `win is_end=0` 中间派奖仅影响待结算展示
+  - `win is_end=1` 最终结算落账
+  - `bet` 重复 `biz_id` 幂等
+  - `win` 重复 `biz_id` 幂等
+  - `bet/win` 缺 `round_id` 参数错误
+  - `win` 非法 `is_end` 参数错误
+
+3. **测试数据与可重复执行设计**
+- 每个测试生成独立 `uid/round_id/biz_id/trace_id`（时间戳+随机后缀），避免脏数据冲突。
+- 用例内封装统一请求方法（POST JSON）与响应断言助手，降低重复代码。
+- 优先按顺序单线程执行此特性测试，避免并发串扰。
+
+4. **执行与验证**
+- 在容器内执行：`docker compose exec -T php82 php vendor/bin/phpunit --filter WalletRegisterBetWinTest`
+- 验证输出：
+  - 所有用例通过
+  - 幂等场景无重复记账（通过返回余额不重复变化来断言）
+
+5. **第二阶段可选增强（不在首版强制）**
+- 增加 DB 断言（`wallet_log`、`wallet_fund_lot`、`wallet_bet_funding`）与 Redis pending key 清理断言。
+- 将该测试纳入 CI job（需环境可用性与测试隔离策略先达成一致）。
+
+## 目标结构图
+```mermaid
+flowchart TD
+    testBootstrap[phpunitBootstrap] --> featureTest[WalletRegisterBetWinTest]
+    featureTest --> registerStep[register_update]
+    registerStep --> betStep[bet]
+    betStep --> winMidStep[win_is_end_0]
+    winMidStep --> winFinalStep[win_is_end_1]
+    winFinalStep --> idemCheck[idempotencyChecks]
+    idemCheck --> negativeCheck[invalidParamsChecks]
+```
+
+## 受影响文件（计划新增/修改）
+- [composer.json](composer.json)
+- [phpunit.xml](phpunit.xml)
+- [tests/bootstrap.php](tests/bootstrap.php)
+- [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php)