---
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)