first commit

plans/测试报告可追踪输出_4fd907ad.plan.md

@@ -0,0 +1,82 @@
+---
+name: 测试报告可追踪输出
+overview: 在现有 WalletRegisterBetWinTest 上增加“可追踪测试报告”：每次执行输出并落盘 uid/round_id/biz_id/余额快照，失败时可直接按用户复现。
+todos:
+  - id: add-reporter-support
+    content: 新增 WalletTestRunContext 与 WalletTestReporter（JSON+Markdown 落盘）
+    status: completed
+  - id: wire-test-class
+    content: 改造 WalletRegisterBetWinTest：记录 uid/round/biz_id，tearDown 输出摘要
+    status: completed
+  - id: config-and-doc
+    content: phpunit.xml 增加 WALLET_TEST_UID/REPORT_DIR；更新 doc 执行说明
+    status: completed
+  - id: verify-run
+    content: 容器执行 phpunit 并确认控制台+报告文件含 uid
+    status: completed
+isProject: false
+---
+
+# 钱包集成测试可追踪报告方案
+
+## 问题
+当前 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 每个用例都会 `makeUid()` 生成随机用户，PHPUnit 默认只显示 `OK (3 tests, 37 assertions)`，**看不到本次用了哪个 `uid`、`round_id`、`biz_id`**，联调排障和 DB 核对都不方便。
+
+## 目标
+- 跑完测试后，**控制台**能看到每个用例的测试用户与关键业务 ID。
+- **落盘一份报告**（JSON + 可读 Markdown），便于复制 `uid` 去查库或手工 curl 复现。
+- 可选：通过环境变量固定 `uid`，便于反复验证同一用户。
+
+## 实现方案
+
+### 1. 新增测试上下文与报告器
+新增 [tests/Support/WalletTestRunContext.php](tests/Support/WalletTestRunContext.php)：
+- 字段：`testName`, `uid`, `currency`, `roundId`, `bizIds`（register/bet/win_mid/win_final）, `traceId`, `steps[]`（每步 API、code、余额快照）, `status`, `errorMsg`。
+
+新增 [tests/Support/WalletTestReporter.php](tests/Support/WalletTestReporter.php)：
+- `startRun()` / `recordStep()` / `finishTest()` / `writeReport()`
+- 报告目录：`runtime/test-reports/`（文件名含时间戳，如 `wallet-register-bet-win-20260515-160530.json` 与同名 `.md`）
+- Markdown 表格示例列：用例名 | uid | round_id | biz_id 列表 | 结果 | 最终余额(deposit/withdraw/b)
+
+### 2. 改造现有 Feature 测试
+在 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 中：
+- `setUp()`：初始化 reporter；若存在 `WALLET_TEST_UID` 则使用该固定 uid（否则继续随机）。
+- 每个 `test*` 开始：创建 `WalletTestRunContext` 并记录 uid/round_id/biz_id。
+- `postJson()` / `wallet()`：成功后把 `code`、关键 `data`、查询余额写入 `steps`。
+- `tearDown()`：标记 pass/fail，调用 `writeReport()`；**向 STDOUT 打印一行摘要**（PHPUnit 控制台可见），例如：
+  - `[WalletTest] testRegisterBetWinFlow uid=90012345 round=r_... bet=bet_... => PASS`
+
+失败时 assertion message 附带 context 摘要，便于一眼定位用户。
+
+### 3. 配置与文档
+- [phpunit.xml](phpunit.xml) 增加可选 env：
+  - `WALLET_TEST_UID`（空=随机）
+  - `WALLET_TEST_REPORT_DIR`（默认 `runtime/test-reports`）
+  - `WALLET_TEST_VERBOSE`（`1` 时打印每步明细）
+- 更新 [doc/register-bet-win-test.md](doc/register-bet-win-test.md) §7：
+  - 报告路径说明
+  - 固定 uid 复现示例：`WALLET_TEST_UID=90012345 docker compose exec ... phpunit ...`
+
+### 4. 执行验证
+容器内执行：
+```bash
+docker compose exec -T -w /app/www/ray/slot-wallet php82 php vendor/bin/phpunit --filter WalletRegisterBetWinTest
+```
+验收：
+- 控制台出现每个用例的 `uid` 摘要行
+- `runtime/test-reports/` 生成 `.json` + `.md`
+- 测试仍全部通过（3 tests）
+
+## 报告结构示意
+```mermaid
+flowchart LR
+    testCase[WalletRegisterBetWinTest] --> context[WalletTestRunContext]
+    context --> reporter[WalletTestReporter]
+    reporter --> stdout[ConsoleSummary]
+    reporter --> jsonFile[runtime/test-reports/*.json]
+    reporter --> mdFile[runtime/test-reports/*.md]
+```
+
+## 不在本阶段做的（可选后续）
+- HTML 可视化报告、CI artifact 上传
+- DB 直连断言（wallet_log / wallet_fund_lot）