# 链模式测试设计与执行手册

v0.6 已完成发售和 RabbitMQ 的本地验证，命令与真实结果见[发售测试](sale-testing.md)。历史 Kafka/容器结果保持原环境；本轮二级市场 RabbitMQ 回归另存 evidence-sale-v0.6/trade，不覆盖旧记录。

本轮 Web3 前端类型与 44 单元通过；Go 链包因依赖不全未执行，原模拟包另有 Windows 回归失败，已经保留原始记录和定向复现。下方 v0.5 成绩为历史环境结果，不能视为本轮全套通过。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

验证目标：匹配不是成交、订单数量守恒、合约原子交换、域签名、持久任务恢复、未知广播保留、链上取消权威、中间件去重、深重组封闭接入。实际结果和原始证据见[v0.5报告](../reports/2026-10-12-v0.5.md)。历史模拟测试报告保持原样。

## 分层与用例映射

| 层级 | 可执行文件/入口 | 断言 |
| --- | --- | --- |
| 核心单元 | chaintrade/engine_test.go | pending非filled；四项数量/非负；回包值副本；重复PLACE/确认；失败取消；nonce冲突 |
| 签名单元 | TestEOASignatureDomain | EOA、跨链、正文篡改、整数预算 |
| 架构门槛 | TestCoreArchitecture | Engine无SQL/RPC/时钟/业务锁；run只Apply |
| SQLite恢复 | worker_test.go | 并发受理重放；投影失败后重建；域/seq/签名/命令/schema损坏拒绝 |
| HTTP组件 | http_test.go | Origin、dataset、JSON尾随/未知字段、重复签单RPC前确认、真实JSON响应 |
| 任务集成 | TestTaskPersistenceAndOutbox | 同ID重复不覆盖SIGNED raw交易 |
| 真实三中间件 | TestRealMiddleware | outbox生产/消费、持久任务、缓存水位防倒退、50/s限流、Redis故障拒绝、第二owner拒绝、锁连接断开拒绝发送 |
| 合约真实EVM | contracts/tests/settlement.test.mjs | 两币守恒、maker价、partial、overfill/重复/域/relayer、cancel、allowance归零原子回滚 |
| 后端本地链 | scripts/web3_check.mjs | 双单链确认、重试、签名篡改、链上取消、重启不转账、链revert、SIGKILL后raw/hash/nonce复用、浅/深重组 |
| 浏览器真实联调 | WEB3_CHECK_BROWSER=1 | Chromium注入EIP1193测试钱包；connect、approve、签名、成交、取消、丢响应后刷新原签单恢复 |
| 容器 | WEB3_CHECK_CONTAINER=1 | 非root/只读镜像执行上述后端链闭环，真实命名卷重启 |
| 性能 | BenchmarkCorePendingPair | 固定历史窗口，纯两次Apply，结果不代表HTTP或链TPS |

浏览器使用测试钱包adapter，通过真实Anvil签名与发送，未使用真实浏览器钱包扩展，不证明MetaMask各版本兼容性。浏览器链外进程未计入Go覆盖率；完整集成通过不意味着Go覆盖率100%。原模拟浏览器8场景通过独立e2e_check回归。

## 执行

先按[开发手册](../03-development/web3-development.md)安装依赖，安装Playwright Chromium：`npm --prefix frontend exec playwright install chromium`。首次环境需系统浏览器依赖。项目根目录：

```bash
bash scripts/test.sh web3
bash scripts/verify.sh
python3 scripts/e2e_check.py
```

真实三中间件先启动开发compose；使用新PG数据库，避免已有绑定域被覆盖：

```bash
export WEB3_DB_PASSWORD='local-web3-password'
docker compose -f deploy/web3-compose.yaml up -d redis postgres rabbitmq
docker compose -f deploy/web3-compose.yaml exec postgres createdb -U exchange web3check-new
WEB3_TEST_POSTGRES_DSN='postgres://exchange:local-web3-password@127.0.0.1:15432/exchange?sslmode=disable' \
WEB3_TEST_REDIS_URL='redis://127.0.0.1:16379' WEB3_TEST_RABBITMQ_URL='127.0.0.1:5672' \
go test -race -count=1 -run TestRealMiddleware -v ./chaintrade
WEB3_CHECK_MIDDLEWARE=1 \
WEB3_CHECK_POSTGRES_DSN='postgres://exchange:local-web3-password@127.0.0.1:15432/web3check-new?sslmode=disable' \
node scripts/web3_check.mjs
```

不设真实环境的TestRealMiddleware明确skip。测试账户需有创建表/会话锁权限；断连接测试需允许终止自己连接。本例开发fixture用户是PG初始化管理员，不能把生产账号提权照搬。

容器测试仅Linux host网络：先 `bash scripts/build-web3-image.sh`，再 `WEB3_CHECK_CONTAINER=1 node scripts/web3_check.mjs`；命名卷保留，脚本不删用户卷。脚本默认SQLite任务，可另传中间件模式与新库组合。

## 证据与清理

脚本独立临时数据/随机回环端口，只停止自身Anvil/Go进程；命令输出由调用者保存到新报告目录。当前脚本默认写 evidence-v0.5；设置 WEB3_CHECK_EVIDENCE_DIR 指定独立目录，不能倒填旧报告。合约编译产物/node_modules/bin忽略，不当源码手改。

深重组故意触发ERROR停止，属于预期通过条件，不是成功交易日志。Anvil刚启动时ethers可能提示网络探测重试，随后ready成功可区分启动提示与测试失败。SIGKILL只验证进程崩溃，不代表断电/磁盘控制器保证；自动挖块确认不代表公网链容量。

完成后 `docker compose -f deploy/web3-compose.yaml stop` 保留卷/任务；不能 `down -v`。失败保存日志与最早断言、配置域/版本（去掉密钥）、任务hash、块hash，不靠删除数据库通过测试。

## 尚未执行与后续设计

公共测试网/主网、云部署、长时拥塞与Gas替换、硬件断电、恶意RPC多源一致性、EIP1271、fee/rebase代币、安全审计、自动HA未验证；本地全量已确认事件补拉/重启/锚点校验已实现并验证，但公共链历史RPC限额和大链从创世扫描未验证。当前缓存优化有功能正确性用例，尚无Redis vs SQLite读压提升实测；不能宣称固定百分比优化。单writer纯核心数字不能换算为链最终成交吞吐。

## v0.5 新用例与预期结果

| 测试 | 证明 |
| --- | --- |
| TestHistoryBoundaries | 111条分页、固定插入上界、钱包/类型/数据集游标隔离 |
| TestTaskMigrationAndCAS | 旧表迁移保持raw/nonce，冲突和终态回退拒绝，未知时间为0 |
| TestIndexerAtomicRestartReorganization | 仅已确认块、重启去重、未确认尾部变化允许、已确认块变化拒绝 |
| TestIndexTransactionFailure | 事件 INSERT 失败时游标不推进，解除故障后原块可重试 |
| TestReconciliationDetectsCorruption | 全量独立重放、投影守恒差异、handoff lag、无副作用 |
| TestHistoryContractAndDiagnostics | 新四类分页/详情真实OpenAPI校验、无raw、回环check/metrics |

真实 Anvil 脚本额外检查分页、wallet、任务时间/版本、已确认 MATCHED/CANCELLED、重启保留索引、/check differences=0与lag=0、histogram；浏览器打开成交历史/任务详情。取消事件是独立索引调度，必须等事件可查询，不能因成交已追平就断言取消已索引。本轮最早等待断言失败保留在 initial-event-wait-failure.txt，不删证据。

```bash
# 所有命令在项目根执行；每次重跑换独立输出目录。
WEB3_CHECK_EVIDENCE_DIR=docs/reports/evidence-v0.5 WEB3_CHECK_BROWSER=1 \
node scripts/web3_check.mjs
EXCHANGE_TEST_OUTPUT_DIR=docs/reports/evidence-v0.5 bash scripts/test.sh coverage
```

历史分页首次上界保证插入顺序，trades 确认状态改变后需刷新首页；不把它当作跨页一致快照。测试对账报告的 lag 可短暂非零，应检查持续阈值；稳定差异不能用无限重试掩盖。云、原生Windows和告警实际通知没有本轮执行，规则校验与采集是否执行以报告为准。

最终补充 TestFinalizedReconciliation（正确终态零差异，缺失事件/终态冲突检测）、TestIndexDiskRestart（真实关闭重开仍保留游标与事件）、TestReadSnapshotDoesNotBlockWriter（读事务持有旧水位，新命令可完成且只读池拒写）。

对账还离线验签任务原交易：raw编码、sender、chain/to/value、hash/nonce与calldata都按当前域核对；不需relayer私钥、不调用发送RPC。终态对账测试额外损坏raw，必须报TASK_RAW_INVALID，检查不会尝试修复或广播。

告警配置校验：项目根执行 `docker run --rm --entrypoint /bin/promtool -v "$PWD/deploy:/etc/prometheus:ro" quay.io/prometheus/prometheus:v3.2.1 test rules /etc/prometheus/web3-alerts-test.yml`，预期 SUCCESS；配置另用 `check config /etc/prometheus/web3-prometheus.yml`。指标输出包含 HELP/TYPE，使用 `docker run --rm -i --entrypoint /bin/promtool quay.io/prometheus/prometheus:v3.2.1 check metrics < 保存的metrics.txt` 检查实际格式。规则评估测试不向外发送消息。
