# v0.2 开发与验证报告

历史记录：下方结果与产物属于当时执行，不因后续源码注释/修复而自动更新。最新正确性与故障收集更正见[测试完善报告](2026-10-11-test-hardening.md)，当前文档一致性见[文档审阅报告](2026-10-11-documentation.md)。原始证据保留，不改写历史成绩。

日期：2026-10-11。环境沿用首版 WSL/Linux amd64、Go 1.26.0、Node 22.22.3、SQLite 驱动 v1.60.1（内嵌 3.53.4）、Vite 6.4.4、Playwright 1.64.0、Docker 29.5.0。源码位于 /mnt/d；测试数据在 /tmp 或 Docker 命名卷。无 Git 仓库，不编造提交号。

## 本版交付

- OpenAPI 3.0.3 真实契约（api/openapi.json）嵌入二进制公开提供，固定 openapi-typescript 7.8.0 生成前端类型；api:check 重生成比对。Go 类型保留手写，kin-openapi v0.133.0 测试校验真实响应。
- 普通/管理员订单游标分页（每页 1–100，UI 20）、当前账户单笔查询、按幂等键查询首次结果；新增索引，SQL 位于外围。
- journal 元数据持久 dataset_id；响应/认证/行情含标识，带旧标识写请求拒绝。旧库升级仅生成一次，不改历史 Command 或 engine_version。
- 下单、撤单、注资原请求先写 sessionStorage，刷新后用户以原键/原内容确认；账号/数据集隔离，存储失败阻止发送；不存密码/Cookie/CSRF。
- 同数据集行情拒绝倒退，新数据集允许低序号；初始 HTTP 不能覆盖已有 WS。新代码充分中文注释，补设计/测试/部署与面试说明。

核心撮合/资金语义不变。具体取舍见[v0.2 设计](../07-history/v0.2-design.md)。

## 验证与证据

| 检查 | 实际结果 |
| --- | --- |
| go test -timeout 60s ./... | 通过，新增契约/23 单分页/按键首次结果/数据集升级与写入检查 |
| go test -race -timeout 60s ./... | 通过，未报告数据竞争 |
| go vet ./... | 通过 |
| 前端 build / format:check | TypeScript + Vite 构建、Prettier 格式检查通过 |
| api:generate / api:check | 生成并比对一致；不直接手改生成物 |
| npm audit | 前期执行为 0 vulnerabilities；收尾复查因 npm 服务网络错误未完成（先 EAI_AGAIN，后 ECONNREFUSED），不能视为最新在线审计通过；期间依赖未改变 |
| 原交易 E2E | 两用户成交/撤单/管理员注资/停用、移动屏及 reduced-motion 保持通过 |
| 请求恢复 E2E | 下单/撤单/注资真实处理后 abort 响应，刷新后原键确认，只有一次业务效果 |
| 分页/存储/行情 E2E | 23 单分为 20/3，前后翻页；sessionStorage 失败无下单请求；同数据集旧水位丢弃、新数据集低水位接受 |
| 本地浏览器整套 | 最终产物 6 passed，17.4s 含 runner 时间（非容量成绩）；前轮 19.3s |
| 容器浏览器整套 | 6 passed，19.2s 含 runner 时间；使用首版持久卷完成旧库升级 |
| scripts/crash_check.py | SIGKILL 重启会话/订单/余额/幂等保持，SIGTERM 正常退出；适配分页 items |
| Dockerfile.runtime | v0.2 产物镜像构建成功；只读根文件系统，USER 10001:10001，持久 /data |
| 最终镜像重建容器/重启 | 同一持久卷保留 dataset、Cookie 会话、订单、余额和按键首次结果；重发只返回原单；公开契约为 0.2.0，健康子命令及撤单通过 |
| 收尾静态检查 | 17 份 Markdown 本地链接/代码围栏、14 个 Go 文件 gofmt、前端格式与契约再生成比对、Compose 配置解析全部通过 |

针对性 Go 验证 `go test -run 'TestOrderPagination|TestCommandLookup|TestDataset|TestOpenAPI' -v ./backend` 全部通过：真实契约约 0.39s、分页约 0.41s、按键查询约 0.30s、数据集升级约 0.26s。这些小测试时间只用于重现，不是延迟/TPS 指标。

浏览器本地地址 18080、数据 /tmp/web3-v02-e2e；容器 web3-v02-validation 使用 18082、镜像 exchange-demo:v0.2-verified、命名卷 web3-exchange-validation-data（首版卷）。管理员明确为独立测试身份。协议注入行情用 Playwright routeWebSocket，不声称验证了实际网络断开后的所有重连窗口。

最终镜像标识为 `sha256:8083e4d26bca8f7fc53e9fca7545b52bbd5a108f797dbfb18b500bf5b96f22e7`（本地构建 manifest）。容器核验使用独立新增账户，保留原 Cookie，不重新登录；确认结果后撤销该测试挂单。收尾停止本任务的本地服务及验证容器，保留上述测试目录、容器和命名卷供复查；没有修改其他容器或用户 Docker 配置。

## 遇到的问题与修复

1. 测试请求恢复时，待确认按钮在“保存后、请求未结束”已出现，测试立即刷新导致 Playwright route.abort 报已处理。改为等待错误通知明确返回后再卸载拦截/刷新，确保注入窗口是服务端成功、浏览器丢失响应，而不是取消仍在运行的测试路由。
2. 分页末页 next_cursor 使用 omitempty，测试复用解码目标可能保留上一页字段。每次清空 Go 解码值，避免把测试状态残留误认为无限分页。
3. 初次新增契约依赖触发默认代理请求等待；后续依赖下载使用已验证 goproxy.cn，保持 GOSUMDB 校验，不关闭校验。
4. 恢复存储失败不能直接归入普通业务拒绝后清理；本地错误保留/阻止，只有明确响应才清理。401、5xx、限流、CSRF/Origin 拒绝及数据集变更都不能证明旧请求未执行，因此保留原记录。
5. 订单列表从数组升级为对象，已同步 App、管理员页面及崩溃脚本，声明前后端同版发布；删除无调用的旧固定列表实现，避免双协议并存。
6. 收尾临时容器核验脚本首轮遇到 HTTP 404，另一次脚本错误假定 Result 含 ok 字段。对照真实路由和契约修正核验请求及断言后，最终镜像重建容器、再次重启和恢复断言全部通过；前述失败不计入通过结果。

## 可重复执行

```bash
go test -timeout 60s ./...
go test -race -timeout 60s ./...
go vet ./...
npm --prefix frontend run api:check
npm --prefix frontend run format:check
npm --prefix frontend run build
CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server
python3 scripts/crash_check.py
# 在 frontend 目录，测试服务已启动并配置测试管理员
E2E_URL=http://127.0.0.1:18080 npm run test:e2e
E2E_URL=http://127.0.0.1:18082 npm run test:e2e
# 根目录
docker build -f Dockerfile.runtime -t exchange-demo:v0.2-verified .
```

## 限制

未做容量压测、阶段 metrics、快照/分区/Redis、用户/审计全量分页、生成 Go 路由或完整类型化 fetch 客户端、线上备份 CLI、真实断电、云服务器部署。命令/去重历史仍增长。标准多阶段在线构建的镜像源 DNS 问题沿用首版边界，未擅改用户 Docker 配置。

sessionStorage 只保证同标签页刷新，不保证关标签/用户清存储/篡改/XSS；恢复旧备份仍可能丢失备份后历史。游标固定创建范围但各页状态不是一个跨请求历史快照。按键查不到只有投影含义，不能当作业务未受理结论。
