v0.6 发售调用链:FlashSale.sol 条款/验签 → flashsale/types.go 单位 → store.go 库存与资格事务 → auth.go/http.go 钱包会话 → middleware.go 与 messaging/rabbitmq.go 发布确认/消费 ack → processing.go 签名任务 → chain.go 索引/安全回收 → SaleApp.tsx 页面恢复。操作见手动验收,协议见发售架构。
本轮已在 29 个源码、测试与配置文件中补充详细中文注释,并核对有效代码未变,见注释完善记录。建议按下列顺序沿源码阅读:
| 阅读入口 | 注释重点 |
|---|---|
| 类型与金额 ↗、库存事务 ↗ | 份数/lot/原子额、库存守恒、行锁、请求键与钱包限购、提交成功点 |
| 钱包认证 ↗、HTTP ↗ | 登录签名、一次性挑战、Cookie/CSRF/Origin、资格归属、准入与限流 |
| RabbitMQ ↗、分发 ↗ | 持久队列、confirm、手动 ack、重连、重投与坏消息隔离 |
| 后台调度 ↗、状态事务 ↗ | 签名固定正文、迟到任务、inbox、成交与回收的原子状态迁移 |
| 链读取 ↗、合约 ↗ | 同 hash 证据、确认深度、深重组冻结、防重放、付款与交付回滚 |
| 活动页 ↗、接口 ↗ | 页面状态与链事实的区别、过期倒计时、上下文代数、刷新恢复、金额精度 |
| 一键启动 ↗、集成验收 ↗ | 新链/新库隔离、只清理自有进程、故障触发方式和各断言的证明点 |
当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。
历史 v0.4 变更记录(当前增量见页首 v0.5):新增阅读顺序:chaintrade/types.go单位与EIP712→engine.go数量状态→store.go三阶段日志流水线→tasks.go专用PG会话锁→middleware.go缓存/至少一次→chain.go原交易/receipt/锚点→http.go→cmd/web3server/main.go→Web3App.tsx→contracts/src/Settlement.sol。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。
更新:2026-10-11。适用于目前已实现的 Go + SQLite + React 单市场模拟交易系统。用户要求“完善代码的注释,越全越好”,已写入 goal.md ↗ 和开发规范第 8 节。新增功能必须同步说明状态所有权、算法原因、失败边界和验证证据。
1. 从哪里开始#
| 文件 | 阅读重点 |
|---|---|
| doc.go ↗ | 模块边界、完整流水线、权威数据与可重建数据 |
| types.go ↗ | 命令/订单/结果/分录字段,金额与 ID 字符串,输入精度限制 |
| engine.go ↗ | 纯内存核心、幂等、红黑树与 FIFO、资金冻结结算、最优价缓存 |
| runtime.go ↗ | 三阶段唯一写者、批提交屏障、有界资源、未知结果、关闭与重放 |
| query.go ↗ | 页内一致投影水位、seek 游标、单笔/首次结果查询 |
| api 契约 ↗、前端 API ↗、请求恢复 ↗ | 生成类型、未知请求、sessionStorage/数据集边界 |
| store.go ↗ | 数据目录锁、三库边界、版本拒绝、原子投影、行情聚合与查询 |
| auth.go ↗、http.go ↗ | 密码/会话、RBAC/CSRF/Origin、认证初始化、交易接口、WS |
| main.go ↗ | 配置、启动顺序、管理员 bootstrap、监督与退出 |
| App.tsx ↗ | 真 API、异步状态、水位、未知请求确认、组件、动画清理 |
| 核心测试 ↗、集成测试 ↗ | 每个场景证明的性质、故障注入方式与边界 |
| 浏览器测试 ↗、崩溃脚本 ↗ | 多身份真实成交、停用、子进程 SIGKILL 恢复 |
| 容器配置 ↗、systemd ↗ | 非 root、持久卷、只读文件系统、优雅关闭 |
注释提供阅读背景;判断能力是否交付时仍需对照实际代码、测试完善报告和测试设计。计划中的快照、分区、Redis、Go 路由/完整 fetch 客户端生成和完整监控告警平台不能当作已实现;目前已有独立 loopback metrics/pprof;v0.2 TS 类型生成/订单分页/请求恢复见设计。
2. 用一个订单理解状态所有权#
Server.protected从 Cookie 查会话,确认角色/CSRF,得到可信的用户 ID。place不接受客户端account_id,将金额规范为 decimal 字符串。Runtime.Submit取得在途额度,生成业务摘要和时间,把命令交给input。外部 HTTP 超时只能停止等待,不能撤销已受理的命令。Runtime.write独占日志序号,将最多 64 条或等待 1ms 收到的请求在 SQLiteFULL事务中提交。只有成功提交的命令才发布到durable。Runtime.run独占Engine.Apply。它检查连续序号及幂等,校验资金,预扫描成交工作量,冻结资产,执行价格时间优先撮合。Apply拷贝本次订单/余额变化和首次响应,不能把核心可变指针交给 HTTP/投影。后续成交不改变先前返回的订单快照。Runtime.project合并已就绪结果(不等待 1ms),先用copyResult隔离响应与投影的指针/切片并回包,再将订单、余额、成交、分录、价档及水位整批 FULL 提交到views.db。投影完成后才归还在途额度。- 前端拿
processed_seq请求min_seq,查询投影追上后再显示新余额。随后轮询继续携带最大已知水位,并忽略旧身份及晚到请求的结果。
| 可变资源 | 唯一写入/协调方 | 外围能否直接访问核心原件 |
|---|---|---|
| 核心树、链表、活动索引、订单、余额、去重 | 启动重放;随后只有 Runtime.run |
不能 |
| 日志序号、commands 表 | Runtime.write |
查询读取日志可以,不能并发分配业务序号 |
| 查询投影 | Runtime.project;启动时由恢复流程补齐 |
HTTP 读投影,不读核心 |
| 认证状态 | 外围认证 SQL,独立连接/事务 | 不进入核心 |
| 共享行情快照 | RunSampler 整体发布,外围 RWMutex 协调 |
WS 只读已发布快照 |
| 接入关闭标记、限流表 | 外围锁 | 不构成核心业务锁 |
这套实现采用 LMAX 单写者思想和 Go 有界 channel,未实现 Disruptor 环形缓冲区,也未实现集群多写者。
3. 手算资金变化#
假设买方初始有 100000 USDT,提交买 3 ETH、限价 105;卖方有两个各 1 ETH、卖价 100 的 maker:
| 步骤 | 买方可用 USDT | 买方冻结 USDT | 说明 |
|---|---|---|---|
| 初始 | 100000 | 0 | 测试准备通过 CREDIT 进入日志 |
| 冻结 | 99685 | 315 | 105 × 3 |
| 成交 2 ETH | 99695 | 105 | 解扣冻结 210,实际支付 200,返价差 10 |
| 撤剩余 1 ETH | 99800 | 0 | 释放原限价 × 余量 = 105 |
成交后买方 ETH 增 2,卖方 ETH 减 2、USDT 增 200。零手续费下每种资产的全账户 Available + Frozen 总和守恒,只有 CREDIT 会增发模拟资产。
数量始终满足 Quantity = Remaining + Filled + Canceled;冻结 ETH 等于账户所有活动卖单余量之和,冻结 USDT 等于所有活动买单 Price × Remaining 之和。测试每条命令后独立重算这些性质。
4. 撮合算法为什么这样写#
- 价档用红黑树维护有序 ticks;同价订单用双向链表 FIFO。订单 ID 到链表节点的索引让同档撤单不需要线性扫描。
- 买最优档取最高价,卖最优档取最低价。缓存使每次找最优对手档为 O(1),新档定位和删除空档仍有 O(log P) 成本;删除最优空档时从树更新缓存。
- 正式变更资金前预扫描最多 1024 个可能成交 maker。否则成交一半才超限,会引入复杂的业务回滚。预扫描和撮合使用相同价格/自成交停止条件。
- 成交采用 maker 价格;MARKET 必须给保护价且 IOC。无流动性时产生零成交的 CANCELED 订单,有部分流动性时成交后取消余量,不保证全额成交。
- 自成交使用 cancel_taker:保留自己的 maker,取消当前订单余量;不会越过自身 maker 去吃后面的挂单。
Apply中排序的仅是本命令改变的订单,目的是消除 map 输出顺序差异;订单簿没有每次查询全量排序。
5. 失败和恢复应怎样理解#
| 边界 | 当前行为 | 不应误解为 |
|---|---|---|
| 入队之前容量不足 | 明确拒绝,未执行 | 已成交但查询没到 |
| 入队之后等待超时/断网 | 原键原内容重试,结果可能已执行 | 可以换新键再下同单 |
| 日志提交失败 | 不发布对应命令到核心,停止流水线 | 跳过失败序号继续撮合 |
| 投影失败 | 核心结果可能已回包,进程停机,日志恢复可补投影 | 成功回包表示所有查询立即可见 |
| 内部序号不连续/panic | 外围监督停机,不继续执行受损核心 | 普通余额不足也应 panic |
| 程序关闭 | 先取消后台采样/关闭 WS,再停止 runtime 受理并排空、等待 HTTP 关闭与采样退出,最后关数据库 | 先关数据库再等待后台任务 |
| 引擎版本不兼容 | 拒绝并释放启动过程中资源/数据锁 | 自动清空旧库启动 |
| SIGKILL 验证 | 六窗口覆盖日志提交前后、Apply 后、回包前、投影事务内与恢复中;另有回包后 SIGKILL 脚本 | 完成真实断电或全部磁盘故障验证 |
重启时保留 journal.db 与 auth.db,从日志头恢复内存核心与去重,重放仍逐条 Apply,ProjectBatch 跳过已应用前缀并补齐后缀;旧库资金审计可在前缀额外补写。views.db 可以在停止所有实例后重建,不能按同样方式删除 auth.db。没有快照时,日志、去重、恢复成本随历史增长。
6. 认证及前端注释的重点#
密码采用 bcrypt 慢哈希(12–72 UTF-8 字节),随机会话使用 SHA256 摘要落库(24h)。两者不同,不能因为会话可直接摘要就把密码改成 SHA256。Cookie 为 HttpOnly/SameSite Strict,HTTPS 配置 Secure;CSRF token 仅保存在页面内存。
公开注册固定 USER;管理员由环境配置 bootstrap,已有 USER 不自动提升、已有 ADMIN 不改密码。停用会撤销会话,但不原子撤销已有挂单,也不取消已经受理命令。注资走核心日志,不能直接改查询余额。
前端金额输入不经过 Number。盘口深度条使用 Number 只绘制比例;金额原文、下单输入和余额继续保留字符串。序号比较采用 BigInt。WS 重连退避至 10s,收到完整快照仅接受不倒退水位;当前通过 dataset_id 区分新数据集,并接受它的低序号;初始 HTTP 不能覆盖已收到 WS。
未知下单/撤单/注资保存原幂等键和原请求,锁定下单/注资表单直至确认;v0.2 在发送前写 sessionStorage,同标签页刷新或重登录该身份可恢复,关闭标签/清存储后没有恢复保证。存储故障会阻止发送,不把浏览器存储称为服务端耐久日志。账号作为私有组件 key,避免把前一身份的待确认请求复用到另一账号。
GSAP 限定组件 scope,只动画 transform/opacity,支持 reduced-motion。定时器、WS、matchMedia/context 在卸载时清理。注释说明这些规则的原因,不把“调用了 hook”本身当作资源清理证明。
7. 后续审阅检查#
修改业务时同时检查:核心所有权是否泄漏、日志能否重放、资金公式是否守恒、错误是否在变更前可拒绝、幂等结果是否稳定、投影水位是否原子推进、前端是否把未知执行当失败、资源是否有上限和关闭路径。
注释应说明真实保证及代价,避免重复赋值、过期叙述和未经测试的性能数字。Go 使用 gofmt,前端提供 npm run format / npm run format:check;注释仅在实际实现或相关证据改变时更新。
8. v0.3 扩展阅读路径#
- runtime.go 的 schema/seq/hash 检查与已投影前缀跳过:不要误以为跳过投影就是跳过恢复核心。
- store.go 的 ProjectBatch/applyProjected:整批提交,第二条失败首条也回滚,提交后才释放额度。
- admin_query.go/market_query.go:同秒用户使用 rowid,多笔同 seq 成交也用 rowid seek;审计两个来源各自上界。
- maintenance.go 与 cmd/exchangectl:同目录 flock,正规文件/manifest 校验,独立重放逐表摘要,坏投影保留与 staging。
- observability.go:只发布外围原子副本/时长,标准 pprof 独立回环监听;字段数量由唯一核心调用者读取后发布。
- cmd/loadcheck 和 scripts/load_check.py:固定工作者与有界客户端积压、计划至完成延迟、拒绝/丢弃/对账;发生器瓶颈与服务瓶颈分开。
- crash_recovery_test/runtime_test/maintenance_test/property_test:精确窗口、整批事务回滚、额度生命周期、恢复/对账、固定 seed 守恒与静态依赖边界。
本轮测试入口与证明点补充见测试手册、用例目录。engine_boundary_test 验证首次幂等记忆不能共享返回 Order 指针;runtime_boundary_test 占用唯一投影连接验证 copyResult 将响应与投影切片分离。前端 tests/unit 执行真实 api/pending TS 源码,React hook 的 DOM 行为仍由浏览器验证。
新增代码继续充分中文注释,解释用途、字段、顺序、边界和例子;对应设计见v0.3,实际证据见报告。
9. 配套使用与维护阅读#
先用接口使用指南走一遍登录—下单—原键确认—min_seq 查询;再用数据生命周期区分三库、备份和投影重建。异常时按故障排查手册检查进程、认证、投影与磁盘。
本次注释审阅记录见文档与注释报告。它记录文档纠偏与行为不变检查,旧测试源码摘要属于旧历史快照,不应在注释更新后继续宣称与当前文件逐字相同。
Windows 本地运行代码路径#
CMD 入口 ↗ → PowerShell 构建与生命周期 ↗ → server.localAdminConfig 回环检查 → BootstrapLocalAdmin → authAction 的配置别名映射 → 真实会话/RBAC。CreateUser/BootstrapAdmin 的常规 12 字节下限保留,本地模式只有可信初始化允许 8 字节。注册仍邮箱输入,登录允许文本别名;契约分别为 Credentials/LoginCredentials。使用与验证见Windows 指南。
v0.5 阅读路线#
先读 history.go(上界与钱包游标),再 tasks.go(schema 迁移和版本 CAS),index.go(连续块与事务),reconcile.go(固定投影水位重放),observability.go(无核心依赖的指标),最后 Web3History.tsx(取消旧读取、筛选重置、详情)。production_test.go 给出每条恢复边界的实际反例。