# 测试设计

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

> v0.4新增独立链测试：[完整链测试设计与用例映射](web3-testing.md)，[真实执行报告](../reports/2026-10-12-v0.4.md)。本页原用例继续验证模拟模式；新增真实EVM/三中间件/钱包adapter/硬杀/重组/容器，不把旧测试数或性能继承为链成绩。


状态：当前架构测试设计与执行映射，更新：2026-10-11。运行方式见[测试手册](testing-guide.md)，逐项场景见[用例目录](test-cases.md)，本轮新增测试与结果见[测试完善报告](../reports/2026-10-11-test-hardening.md)。v0.3 历史性能/容器证据见[报告](../reports/2026-10-11-v0.3.md)，真实断电/硬件故障/云环境仍需外部环境。

新增注释要求：测试函数解释触发条件与断言证明点，明确种子/fuzz、进程被杀/真实断电及场景通过/全矩阵通过的区别。新增版本拒绝资源释放测试，核心每条命令后核对最优价缓存与树极值。

新增认证测试：USER 无法提权/访问管理、会话注销与停用、CSRF/Origin 拒绝、订单归属、密码/会话摘要、管理员注资同键重试；浏览器使用真实双账户成交和管理员操作。

v0.2 新增契约加载与真实响应校验、生成一致性、23 单分页期间新增无重复遗漏、单笔/按键账户隔离、首次结果稳定、旧库 dataset 升级/写入检查。浏览器新增成功后丢响应并刷新恢复下单/撤单/注资、UI 翻页、存储不可用无写请求、行情数据集/水位比较；[本版结果](../reports/2026-10-11-v0.2.md)与全部规划矩阵区分。

## 1. 验证目标与层级

| 层级 | 验证内容 | 工具与环境 |
| --- | --- | --- |
| 金额与领域 | 解析、精度、规则、规范化、错误码 | Go table-driven 测试、fuzz |
| 纯核心 | 价格时间优先、状态机、资金与幂等 | 直接 Apply，无数据库与网络 |
| 前端单元 | 原键/原内容、未知执行分类、超时、待确认恢复格式/作用域 | Node test + 可控 fetch/只读内存存储，执行真实 TS 源码 |
| 存储集成 | 日志事务、持久化屏障、投影原子性 | 临时本地目录、真实 SQLite 文件 |
| 运行时 | 队列背压、关闭、超时和外围竞态 | 注入存储延迟/错误，go test -race |
| 恢复系统 | 崩溃窗口、重放、版本与损坏处理 | 子进程 + 可控 failpoint + 重启校验 |
| 接口与前端 | 契约、真实联调、WS 重连 | HTTP 测试、Playwright、实际后端 |
| 性能与部署 | 分层性能、资源、云主机与容器运行 | benchmark、负载工具、Linux 服务器 |

核心判据是正确性与恢复可证明，性能随后测量。测试数据固定初始状态和命令序列，失败保留 seed 和最小输入，禁止依赖墙钟先后作为断言。

## 2. 关键业务用例

| ID | 输入与场景 | 预期 |
| --- | --- | --- |
| M01 | `0.1 + 0.2`，数量连续分批扣减 | 精确为 `0.3`，无残余 dust |
| M02 | `"1.0"` 与 `"1.00"` 价格 | 同一个价档和相同幂等载荷 |
| M03 | 指数、负数、零、超精度、超长数字、tick/step 非整数倍 | 确定错误，状态与资金不变 |
| B01 | 卖盘 100×2，买限价 105×3 | 100 成交 2，105 挂余量 1，无交叉簿 |
| B02 | 多个卖价档，买单跨档 | 按卖价升序，maker 价成交 |
| B03 | 同价 A/B/C，撤 B，再到达 D | 顺序 A/C/D，不因删除重排 |
| B04 | 同价不同到达命令的相同 Timestamp | 按日志 seq 排序 |
| B05 | 部分成交再撤余量 | 释放准确余量，活动索引/价档/FIFO 一致 |
| B06 | 最后一个订单完全成交或撤销 | 价档与最佳价缓存同时更新，空盘为 null |
| B07 | 限价 IOC 无成交或部分成交 | 余量取消，不挂单，无冻结残留 |
| B08 | 市价 IOC 有保护价且流动性不足 | 可用深度范围内部分成交，余量取消，无 panic |
| B09 | 空盘或保护价内没有对手 | 零成交 IOC 为 CANCELED，cancel_reason=NO_LIQUIDITY/PRICE_PROTECTION；不是 HTTP 错误码 |
| B10 | 超过最大成交笔数 | 预扫描拒绝，全部资金和订单不变 |
| B11 | 前面其他账户可成交，后面遇到本账户 maker | 前面成交，taker 余量取消，自账户 maker 保留，不跳过队列 |
| B12 | 完全成交订单/未知订单/其他账户订单撤销 | 对应 409/404/归属错误；不会 nil 解引用 |
| F01 | 买 105×3，在 100 成交 2 | 冻结 315→105，释放 10，买方得到 2 ETH，卖方得到 200 USDT |
| F02 | 多笔卖单超出可用 ETH，或买单超出 USDT | 只有可满足资金的订单被接受，余额不负 |
| F03 | 同账户跨两个市场共享 USDT | 未来多市场用例；当前只有 ETH-USDT，不宣称已执行 |
| F04 | 零成交取消、部分成交取消、满额成交 | 冻结全部对账，每种资产守恒 |
| F05 | VWAP：100×1 与 200×9 | 后续展示功能的候选用例；当前未实现 VWAP，不计为通过 |
| I01 | 同键同载荷串行、并发和重启后重试 | 只有一个业务订单和一份冻结，返回首次结果 |
| I02 | 同键不同数量/价格/接口动作 | 409 IDEMPOTENCY_CONFLICT |
| I03 | 首次余额不足被拒绝，后充值再用同键 | 保持首次拒绝；新键可再次尝试 |
| I04 | 同一订单撤单与成交同时接入 | 以全局序号决定；先成交则不可撤，先撤则不能再撮合该订单 |
| I05 | seq 超过 JS 安全整数，以及接近 int64 上限 | JSON 字符串无精度损失；达到上限受控拒绝 |

## 3. 不变量与属性测试

每次完整命令后检查，不只在整个序列末尾检查：

1. `original = remaining + filled + canceled`，任何数量及账户可用/冻结不为负。
2. 价档聚合量等于 FIFO 中剩余量之和；活动索引与 FIFO 节点一一对应；活动订单只在一个价档。
3. 买卖树顺序、最佳价缓存和空盘语义一致；不存在符合价格可成交条件的交叉挂单。
4. 每笔成交的买卖数量相同，价格为 maker 价格，成交量大于零，trade ID 唯一。
5. 买方账户的 USDT 冻结等于仍活动买单 reservation 成本之和；卖方 ETH 冻结等于活动卖单剩余量之和。
6. 每种资产的总可用 + 总冻结保持供应记录一致；资金分录和余额可对账。
7. 核心处理序号连续，投影水位单调且不高于已持久化序号。
8. 同键重试与原结果一致；重复 envelope 不产生重复成交和资金分录。
9. 返回 Order、首次幂等记忆、核心订单彼此独立；运行时响应的指针/切片不能改写尚未提交的投影。

生成限价、市价、撤单和重试混合命令；使用少量账户、少量价档、有限数量，便于 shrink。完整排序列表参考模型仍是后续候选；当前采用乱序价档/同价 FIFO 的双方向人工 fixture 和独立树/索引枚举，不把完整参考模型当作已交付。资金以独立守恒校验及人工可计算 fixture 验证，避免完全复制生产算法。

核心 fuzz 不调用网络或 SQL。非法输入 fuzz 覆盖 JSON decoder、十进制解析、枚举与边界组合；所有失败保证不会进入半更新状态。

## 4. 并发与资源测试

并发测试的对象主要是外围运行时，不让多个 goroutine 同时直接调用一个核心：

- HTTP 并发发送下单、撤单、查询、相同幂等键；捕获最终日志顺序，按该顺序用纯核心重新计算并比对。
- 持久化线程延迟、投影线程延迟、慢 WS 客户端、客户端断开，验证队列满时明确拒绝/背压且不丢业务结果。
- HTTP timeout 后同键重试，验证无重复下单；客户端 context 取消后核心仍可能完成受理命令。
- 达到订单上限、payload 上限、最大 match 数、连接上限时验证拒绝路径；观察 goroutine、内存和 FD 回落。
- 并发查询交易列表和余额，验证响应内数据来自同一投影版本；min_seq 等待有界，返回当前 applied_seq。
- `go test -race ./...` 检查共享值、响应关联表、队列关闭、WS 生命周期；另用静态依赖检查确认核心没有引入业务锁/IO。

投影持久落后可使核心停止消费，这是期望背压而非“继续丢消息”的可用性优化；测试应检查已确认交易在重启后存在。

## 5. 故障注入与恢复

failpoint 仅测试构建启用，通过子进程 IPC/标记文件在指定阶段暂停，由测试主进程结束子进程；不在生产 HTTP 暴露 kill/crash 接口。

| ID | 注入位置 | 必须验证 |
| --- | --- | --- |
| R01 | 日志事务提交前退出 | 恢复后的已提交前缀完整，无未提交效果 |
| R02 | 日志已提交、尚未送核心 | 命令重放生效，ID 与日志一致 |
| R03 | Apply 已完成，HTTP 未收到响应 | 重放后同键取首次结果，成交和冻结不重复 |
| R04 | 输出等待投影时退出 | 投影按日志补齐，余额与订单一致 |
| R05 | 投影事务更新一半时退出 | 数据更新和 applied_seq 一起回滚或一起提交 |
| R06 | 连续重启并在恢复中再次退出 | 恢复幂等，不重复注资/挂单/成交 |
| R07 | 删除 views.db，保留 journal.db | 投影从零重建，与正常执行状态相同 |
| R08 | 日志写入磁盘满/只读/提交返回错误 | 不越过持久化屏障；停止接入，保留诊断数据 |
| R09 | 副本中损坏 journal 页面或截断文件 | 检查失败或恢复失败，禁止跳过记录默默启动 |
| R10 | 副本中损坏 views 文件 | 可通过日志重建；原损坏文件保留 |
| R11 | 未知 schema/engine 规则版本 | 受控拒绝启动，不能错误重放 |
| R12 | 第二实例访问同一目录 | 启动失败，不形成双写者 |
| R13 | 备份恢复到干净目录 | 日志高水位、余额、订单与备份 manifest 对齐 |
| R14 | SIGTERM 期间仍有请求 | 停止接入、排空已受理命令/输出、关闭连接，或明确超时后依靠恢复 |

crash 用例以“日志真实已提交前缀”和“客户端收到成功的订单集合”双重判据：客户端未收到回复的操作可以存在；客户端已收到成功的操作必须恢复。日志和投影的 checksum/不变量均通过后才判断恢复成功。

真实断电、磁盘故障与网络文件系统行为需要额外环境验证，普通 `kill -9` 不覆盖。首版不删除命令历史，因此日志损坏只能恢复备份，不能从 views 假造日志。

## 6. HTTP、前端和实时协议

契约测试验证金额/ID 为字符串、枚举和错误 envelope、分页上限、body 上限、空簿 null、幂等响应及 processed_seq/result_seq 区分。代码生成在 CI 重新运行，出现差异失败。

Playwright 使用真实服务和新建临时数据目录，明确演示账户初始余额：

1. 页面加载后从真实 API 获取市场、盘口、账户；不能只验证静态元素存在。
2. 账户 A 挂卖，账户 B 限价买入部分数量，验证成交列表、双方余额与 A 剩余订单。
3. A 撤销余量，验证冻结释放及活动订单移除。
4. B 提交保护价市价 IOC，验证部分成交/取消余量；提交余额不足与非法精度，验证错误且没有假成功。
5. 中途断开 WS、服务重启、重连取得最新快照；旧快照不得覆盖新水位。
6. 模拟 HTTP 超时，同键确认结果；投影滞后时显示“更新中”，不显示错误余额。
7. 375px 与桌面宽度、键盘操作、reduced-motion、对比度；检查 computed style 无圆角方框，样式无渐变，GSAP 卸载后无残留任务。

保存最终可重复脚本、浏览器控制台/网络异常结果和关键截图；截图只是联调辅助，实际状态需要接口和数据库断言。

## 7. 性能实验

分别报告，不能混合成一个 TPS：

| 实验 | 条件 | 输出 |
| --- | --- | --- |
| 纯 Apply benchmark | 日志序号预先确定，无存储网络；每次样本独立可控状态 | ns/op、allocs/op、不同价档/成交笔数吞吐 |
| JournalWriter | 真实本地 SSD，FULL，1/16/64 批量，无/有 1ms 等待 | 每批延迟、命令吞吐、p99、checkpoint 影响 |
| 端到端 | HTTP → 日志 → 核心结果；另量查询赶上 | p50/p95/p99、拒绝率、CPU、GC、队列水位 |
| 混合负载 | 挂单/可成交/市价/撤单/重试 + REST/WS，固定配比 | 压力增长拐点、资源上限、投影 lag |
| 恢复 | 1万/10万/更大命令数，冷/热缓存分开 | 重放速度、readiness 耗时、峰值内存 |

记录 CPU/内存/磁盘、OS/内核、Go/依赖版本、GOMAXPROCS、SQLite 版本、数据库目录和 journal 配置。当前工作区在 WSL `/mnt/d`，正式性能基线用 Linux 本地磁盘目录，不把跨文件系统表现作为算法结论。

负载生成必须记录计划发送时间和实际完成时间，解释 closed-loop 下延迟低估问题，避免只测响应成功请求忽略超时与排队。不预热后无限使用同一满订单簿而不记录增长影响；历史去重内存增长单独量化。

初步目标仅供后续实验检验：100 commands/s 可顺畅演示、端到端 p99 <100ms、10 万命令恢复 <30s。若不达标提交数据和瓶颈分析，调整目标或实现，不修改报告掩盖结果。

## 8. 自动化与结果模板

后端 CI：格式/静态检查、领域与集成测试、race、生成一致性、必要恢复测试和依赖漏洞检查。前端 CI：lockfile 安装、typecheck、build、必要交互测试。性能实验不以不稳定墙钟阈值阻断所有日常提交。

验证与后续计划命令包括 `go test ./...`、`go test -race ./...`、`go test -bench=. -benchmem`、前端 typecheck/build/Playwright；具体命令按落地工具补全，基础测试、race、vet、前端构建/格式化/审计、真实浏览器和进程崩溃验证已执行，通过结果见报告；v0.3 benchmark/容量/恢复、精确提交/执行/投影/恢复 SIGKILL 窗口和备份/坏投影重建已执行；真实断电/磁盘满不能由这些实验替代。OpenAPI 真实响应/生成 TS 一致性已执行。

每份执行记录应包含：代码提交、日期、环境、命令/场景、预期、实际、原始输出路径、发现问题、修复提交、复测结论。未执行项明确写“未执行”，不能把设计用例列表算作测试通过。

## 9. v0.3 当前架构验证映射

| 矩阵 | 实际实现/入口 | 限制 |
| --- | --- | --- |
| R01–R06 | crash_recovery_test 精确 hooks、子进程 SIGKILL、重复重放与同键确认 | 旧文件名误限 Windows，本轮改名后 Linux 实测通过；生产无故障接口，不是真实断电 |
| R07/R10 | 投影删除恢复、rebuild-views 保留坏文件 | 只修复可派生库，不修权威坏数据 |
| R08 | Journal 关闭拒绝越过屏障、SQLite 投影触发器错误/整批回滚 | 未填满真实磁盘/注入 fsync 硬件故障 |
| R09/R11/R12 | 日志 seq/hash/schema、数据库完整性、未知版本/独占锁 | 不静默截尾或跳记录 |
| R13 | 本地/容器离线 backup/restore、manifest/字节/表对账、会话/原键 | 备份校验不是恶意篡改签名 |
| R14 | 取消等待已受理仍执行、排空、WS 主动关闭、SIGTERM 退出 | 硬件卡死最终由进程管理器强杀 |
| 领域/属性 | 固定 seed 混合命令、资金/冻结守恒、核心依赖禁 IO/锁、match 1025、序号耗尽 | 当前单市场，F03 跨市场和真实费用/VWAP 不在范围 |
| 分页/权限 | 23 同秒用户、AUTH/CREDIT 跨来源边界、同 seq 多成交、数据集/管理员隔离 | 固定集合而非跨请求历史状态快照 |
| 浏览器 | 8 个真实场景，scripts/e2e_check.py 独立环境 | 实际 socket 关闭重连，不等于完整断网矩阵 |
| 性能 | 分层 Go benchmark、Python/Go 开放率负载、10万交易命令恢复 | 短时/热 OS 缓存/本机 WSL，报告完整条件 |

验收使用 `bash scripts/verify.sh`、独立 E2E/container 脚本；GitHub workflow 已提供但未远程执行。性能实验顺序运行，不与 race/构建/其他压力并行，保留初轮探索结果与最终补丁工具链结果的区别。

## 文档与注释改动的验证口径

本轮注释解释对象隔离、批投影、游标及恢复边界，文档纠偏不另造镜像实现的机械测试。检查去注释后的语法结构/脚本内容不变，执行 Go/前端格式、契约、单元回归与构建，核对 Markdown 链接和配置解析。旧源码 SHA256 是当时快照；注释更新后用独立新证据记录当前文件，保留旧证据不覆盖。详见[文档与注释报告](../reports/2026-10-11-documentation.md)。


## Windows 一键启动验证增量

本地模式新增身份行为，须验证别名/密码/回环配置/普通注册规则/RBAC 与登录契约；脚本须用原生 PowerShell/Windows exe 验证，不能用 Linux 交叉编译成功冒充运行。启动用独立临时路径/端口，验证重启原键结果与实际浏览器表单；Ctrl+C、自动默认浏览器与首次依赖安装分别记录是否实测，见[Windows 报告](../reports/2026-10-11-windows-launcher.md)。

## v0.5 链闭环验证

chaintrade/production_test.go 新增 TestHistoryBoundaries（111条/上界/筛选/游标隔离）、TestTaskMigrationAndCAS（旧表升级/raw不变/冲突/终态）、TestIndexerAtomicRestartReorganization（重启/浅尾部/深锚点）、TestIndexTransactionFailure（事件失败游标不推进）、TestReconciliationDetectsCorruption（全量投影守恒/只读/lag）、TestHistoryContractAndDiagnostics（新接口真实契约/raw不泄漏）。

真实 scripts/web3_check.mjs 额外覆盖历史翻页、钱包筛选、详情、重启索引、对账和直方图；浏览器进入成交历史并打开任务详情。先构建同版前后端，再运行真实 Anvil/中间件/容器。WEB3_CHECK_EVIDENCE_DIR 指定本次独立目录，默认为 docs/reports/evidence-v0.5；历史 evidence-web3 不改写。全套命令、失败重试与执行结果见 web3-testing.md 和 v0.5 报告；公共链/云/原生 Windows、硬件断电没有在本轮执行。

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