# 2026-10-12 v0.4 后端中间件与链上结算交付记录

用户要求按“主要后端、少量智能合约”的业务路线完善项目、设计/开发/测试/部署与所有当前文档，开发后真实模拟验证，并保持充分中文注释。本轮新增独立模式而保留既有模拟账户/管理员/接口；没有Git仓库，不提供捏造提交号。历史报告、旧包和证据不重写。

## 交付与设计

[v0.4架构](../07-history/v0.4-design.md)定义EOA签单、pending与confirmed数量、FULL日志→单写者→投影/outbox→外围任务；[开发手册](../03-development/web3-development.md)列配置和两钱包流程；[测试手册](../04-testing/web3-testing.md)覆盖分层用例；[部署手册](../05-deployment/web3-deployment.md)提供Linux云/systemd、非root只读容器和备份恢复。原架构/规范/认证/接口/运维/开发计划/测试/教学/Windows/选型/面试文档补充模式归属与最新导航；历史v0.2/v0.3设计主体保留并标明范围，Q&A新增Q52–Q67。

新增 `chaintrade`、`cmd/web3server`、`contracts`、`frontend/src/Web3App.tsx`、独立OpenAPI及生成TS、Windows链入口、Linux容器模板/镜像构建、模拟检查脚本和CI步骤。三中间件使用真实Redis/PG/Kafka；无中间件配置的明确本地模式另用SQLite任务，不偷偷故障降级。

合约按maker价原子交换标准18/6位测试代币，EIP712域、双方签名、方向、限价、deadline、filled/cancelled、settlementId再验证；指定relayer，EOA，LIMIT GTC。模拟注册资金/CREDIT从不映射到链上。钱包approve不是冻结。核心无业务锁/SQL/RPC/JSON/时钟，外围锁和签名不受此禁止。充分中文注释覆盖新增状态、函数、测试和部署资源。

## 本轮测试证据

环境为WSL Linux amd64，AMD Ryzen AI 7 H 350，Go1.26.9、Node22.22.3、npm12.0.2；源码在/mnt/d，链测试数据库创建于独立/tmp目录。Anvil1.4.4、solc0.8.37、OpenZeppelin5.4.0、ethers6.17.0。真实Docker开发中间件为Redis7.4.2、PostgreSQL17.4、Kafka3.9.0，单副本只证明演示功能。

| 验证 | 证据 | 结果/边界 |
| --- | --- | --- |
| 常规verify | [verify.txt](evidence-web3/verify.txt) | 模块、gofmt/vet、全Go/race、44前端单元、两份契约生成一致性、格式、构建、模拟SIGKILL恢复 |
| 全Go及语句覆盖 | [go-tests.txt](evidence-web3/go-tests.txt)、[coverage.txt](evidence-web3/coverage.txt) | 全套通过，总语句覆盖63.3%，backend82.6%、chaintrade45.8%；链外部Anvil/browser进程不计覆盖，web3server入口未单元覆盖 |
| race | [go-race.txt](evidence-web3/go-race.txt)、[chaintrade-race-final.txt](evidence-web3/chaintrade-race-final.txt) | 完整Go与链包通过；真实中间件race另见下项 |
| 前端单元 | [frontend-unit.txt](evidence-web3/frontend-unit.txt) | 44通过；新增10项原签单完整域、签名、正文、钱包和坏存储校验 |
| 真实中间件 | [middleware-test.txt](evidence-web3/middleware-test.txt) | Kafka outbox/消费、SQL去重任务/故障原批重试、Redis限流/缓存防倒退、第二owner拒绝、PG锁连接断开、Redis失败拒绝通过 |
| 合约真实EVM | [contract-tests.txt](evidence-web3/contract-tests.txt) | partial/maker价/守恒/重复/overfill/cancel/域/relayer/allowance回滚通过 |
| 本地链与钱包 | [simulation-local.json](evidence-web3/simulation-local.json)、[日志](evidence-web3/simulation-local-log.txt)、[截图](evidence-web3/wallet-page.png) | 本地链闭环＋Chromium测试钱包adapter，丢响应刷新原签单；不是生产钱包扩展兼容性实测 |
| 三中间件完整链闭环 | [simulation-middleware.json](evidence-web3/simulation-middleware.json)、[日志](evidence-web3/simulation-middleware-log.txt) | pending、maker价/资产、重试/篡改、取消、重启、revert、硬杀原交易、浅/深重组通过 |
| 只读容器闭环 | [simulation-container.json](evidence-web3/simulation-container.json)、[构建](evidence-web3/container-build.txt) | scratch UID10001、host网络、命名卷、完整后端链闭环通过；卷保留 |
| 原模拟浏览器回归 | [simulation-browser-regression.txt](evidence-web3/simulation-browser-regression.txt) | 8场景：注册/交易/管理员/分页/恢复等实际浏览器回归 |
| API/构建 | [web3-api-check.txt](evidence-web3/web3-api-check.txt)、[frontend-build.txt](evidence-web3/frontend-build.txt) | 独立OpenAPI生成；Go真实响应schema；lazy分包避免ethers进入原页面启动块 |
| 依赖审计 | [Go](evidence-web3/govulncheck.txt)、[contracts npm](evidence-web3/contracts-audit-final.json)、[frontend npm](evidence-web3/frontend-audit-final.json) | Go可达漏洞0，仍有2导入包和1模块中未调用漏洞；npm均0，不是长期安全保证 |

链包14个顶层Test（包括默认环境显式skip的真实中间件测试）；其真实中间件测试另显式配置运行并通过。端到端真实Anvil按数量和代币余额断言：卖2WETH@100、买3WETH@105，buyer增加2WETH、减少200USDT，卖方增加200USDT；pending不提前filled。授权归零使原子交易revert，资产不变。广播后SIGKILL恢复hash/nonce不变；未确认浅重组继续同raw；深重组停止服务并在重启拒绝失效最终事实。深重组ERROR日志属于预期通过条件。

## 审阅及失败修复记录

专用PG连接持advisory lock并检查失锁，避免业务池自动重连导致原互斥丢失；启动合约getter检查实际token/relayer。日志恢复补schema/域/签名摘要校验，原交易恢复校验sender/to/value/nonce/hash/data。扫描采纳块hash持久化并按hash RPC，有界循环活动订单及历史receipt，不虚称完整索引器。Kafka过滤dataset并保留失败消费批次，防止SQL失败后再次Poll跨过旧记录提交更高offset；真实测试先断SQL再恢复接收。Redis高水位不随缓存TTL消失。钱包每次复核账户/链，域绑定原签单，明确拒绝清理而未知结果保留。

依赖初次审计：ganache、旧ethers/solc/tmp存在漏洞，已改Anvil并升级；Go初选go-ethereum1.15.11/pgx5.7.5/gorilla1.4.2被govulncheck指出6项可达漏洞，升级到1.17.0/5.9.2/1.5.3；[修复前Go证据](evidence-web3/govulncheck-before-fix.txt)保留。首次工具以Go1.24编译不支持本项目1.26，改显式GOTOOLCHAIN=go1.26.9，不冒称最早扫描通过。

Kafka初始卷权限与日志目录、首次主题创建和offset起点失败，补初始化/LOG_DIR/主动topic创建/AtStart后通过。容器首次构建的通用.dockerignore忽略bin/dist，增加专门runtime dockerignore后通过；不修改用户daemon镜像源。

深重组测试初始等待15秒不足以覆盖Kafka消费者退出，扩大到受控60秒窗口，不改链判断。[最早等待失败](evidence-web3/middleware-shutdown-timeout-before-fix.txt)。浅重组测试初始固定sleep/挖块假设与浏览器撤单扫描竞态失败；测试最终先等旧remaining/pending归零，再持续挖块观察实际确认。[挖块失败](evidence-web3/shallow-mine-race-before-fix.txt)、[撤单扫描失败](evidence-web3/browser-cancel-scan-race-before-fix.txt)保留。取消已入块不等于后端已扫描，合约正确拒绝使用已取消旧买单；没有通过删数据掩盖此窗口。

## 性能证据与生产差距

[core-benchmark.txt](evidence-web3/core-benchmark.txt)：每op是两次Engine.Apply形成一个pending意图，每1000对重置历史，三次约2333–2364ns/op、3180–3181B/op、29allocs/op。只测本机纯核心，不含签名、HTTP、日志、投影、Kafka、PG、RPC、Gas与最终链确认；不把倒数写成链TPS，不沿用模拟v0.3的4000请求/秒实验作为链容量。

现有限制：单sender串行、每订单最多一个pending、固定500ms worker、链confirmations、逐命令投影均可能是端到端瓶颈，持续饱和容量与Redis读压收益尚未测量。平台掌握排序/活性，确认后maker档尾重挂影响绝对FIFO。PG会话锁不构成HA，approve不冻结资产，Kafka不是exactly-once。

## 未执行范围与资源

公共测试网/主网/云服务器、真实硬件断电、真实钱包扩展版本兼容、合约安全审计、长时链拥塞/自动Gas替换、全量事件补拉、多市场分区、跨链/金库/EIP1271、fee/rebase代币和自动故障切换未执行或未实现。systemd/云说明和Windows链脚本是实现模板，Windows原生未实测；远程CI定义更新但未在GitHub执行。任务跨库备份恢复需停机共同水位，当前没有链专用恢复CLI。

本次中间件项目exchange-web3独立卷保留，测试Anvil/服务仅清理自身；不删除用户数据。当前容器/源码摘要另保存，不宣称旧发布包属于新源码；未发布外部应用或合约。

最终核对：[文档链接/代码围栏](evidence-web3/document-check.json)检查29份当前文档，错误0；[Go顶层注释](evidence-web3/comments-check.txt)缺失0；[环境](evidence-web3/environment.json)、[本轮源码摘要](evidence-web3/source-sha256.txt)、[中间件镜像](evidence-web3/middleware-images.txt)、[链镜像配置](evidence-web3/container-image.json)均独立保存。上述注释检查不替代人工语义审阅，覆盖率不代表正确率。

最终收尾：三套链闭环JSON分别记录本地钱包10项、真实三中间件9项、容器9项通过；本次中间件容器均已停止，命名卷保留，测试Anvil/web3server无残留。最终运行镜像ID以container-image.json为准。
