# 代码阅读与注释指南

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 页面恢复。操作见[手动验收](../04-testing/sale-acceptance.md)，协议见[发售架构](../02-architecture/flash-sale-design.md)。

本轮已在 29 个源码、测试与配置文件中补充详细中文注释，并核对有效代码未变，见[注释完善记录](../reports/2026-11-02-chinese-comments.md)。建议按下列顺序沿源码阅读：

| 阅读入口 | 注释重点 |
| --- | --- |
| [类型与金额](../../flashsale/types.go)、[库存事务](../../flashsale/store.go) | 份数/lot/原子额、库存守恒、行锁、请求键与钱包限购、提交成功点 |
| [钱包认证](../../flashsale/auth.go)、[HTTP](../../flashsale/http.go) | 登录签名、一次性挑战、Cookie/CSRF/Origin、资格归属、准入与限流 |
| [RabbitMQ](../../messaging/rabbitmq.go)、[分发](../../flashsale/middleware.go) | 持久队列、confirm、手动 ack、重连、重投与坏消息隔离 |
| [后台调度](../../flashsale/worker.go)、[状态事务](../../flashsale/processing.go) | 签名固定正文、迟到任务、inbox、成交与回收的原子状态迁移 |
| [链读取](../../flashsale/chain.go)、[合约](../../contracts/src/FlashSale.sol) | 同 hash 证据、确认深度、深重组冻结、防重放、付款与交付回滚 |
| [活动页](../../frontend/src/SaleApp.tsx)、[接口](../../frontend/src/sale-api.ts) | 页面状态与链事实的区别、过期倒计时、上下文代数、刷新恢复、金额精度 |
| [一键启动](../../scripts/sale-dev.mjs)、[集成验收](../../scripts/sale-check.mjs) | 新链/新库隔离、只清理自有进程、故障触发方式和各断言的证明点 |

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

> 历史 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架构](../07-history/v0.5-design.md)，操作见[开发](web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](../05-deployment/web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


更新：2026-10-11。适用于目前已实现的 Go + SQLite + React 单市场模拟交易系统。用户要求“完善代码的注释，越全越好”，已写入 [goal.md](../../goal.md) 和[开发规范第 8 节](engineering-standards.md#8-代码注释要求2026-10-10-新增)。新增功能必须同步说明状态所有权、算法原因、失败边界和验证证据。

## 1. 从哪里开始

| 文件 | 阅读重点 |
| --- | --- |
| [doc.go](../../backend/doc.go) | 模块边界、完整流水线、权威数据与可重建数据 |
| [types.go](../../backend/types.go) | 命令/订单/结果/分录字段，金额与 ID 字符串，输入精度限制 |
| [engine.go](../../backend/engine.go) | 纯内存核心、幂等、红黑树与 FIFO、资金冻结结算、最优价缓存 |
| [runtime.go](../../backend/runtime.go) | 三阶段唯一写者、批提交屏障、有界资源、未知结果、关闭与重放 |
| [query.go](../../backend/query.go) | 页内一致投影水位、seek 游标、单笔/首次结果查询 |
| [api 契约](../../api/openapi.json)、[前端 API](../../frontend/src/api.ts)、[请求恢复](../../frontend/src/pending.ts) | 生成类型、未知请求、sessionStorage/数据集边界 |
| [store.go](../../backend/store.go) | 数据目录锁、三库边界、版本拒绝、原子投影、行情聚合与查询 |
| [auth.go](../../backend/auth.go)、[http.go](../../backend/http.go) | 密码/会话、RBAC/CSRF/Origin、认证初始化、交易接口、WS |
| [main.go](../../cmd/server/main.go) | 配置、启动顺序、管理员 bootstrap、监督与退出 |
| [App.tsx](../../frontend/src/App.tsx) | 真 API、异步状态、水位、未知请求确认、组件、动画清理 |
| [核心测试](../../backend/engine_test.go)、[集成测试](../../backend/integration_test.go) | 每个场景证明的性质、故障注入方式与边界 |
| [浏览器测试](../../frontend/tests/exchange.spec.ts)、[崩溃脚本](../../scripts/crash_check.py) | 多身份真实成交、停用、子进程 SIGKILL 恢复 |
| [容器配置](../../deploy/compose.yaml)、[systemd](../../deploy/exchange.service) | 非 root、持久卷、只读文件系统、优雅关闭 |

注释提供阅读背景；判断能力是否交付时仍需对照实际代码、[测试完善报告](../reports/2026-10-11-test-hardening.md)和[测试设计](../04-testing/test-design.md)。计划中的快照、分区、Redis、Go 路由/完整 fetch 客户端生成和完整监控告警平台不能当作已实现；目前已有独立 loopback metrics/pprof；v0.2 TS 类型生成/订单分页/请求恢复见[设计](../07-history/v0.2-design.md)。

## 2. 用一个订单理解状态所有权

1. `Server.protected` 从 Cookie 查会话，确认角色/CSRF，得到可信的用户 ID。`place` 不接受客户端 `account_id`，将金额规范为 decimal 字符串。
2. `Runtime.Submit` 取得在途额度，生成业务摘要和时间，把命令交给 `input`。外部 HTTP 超时只能停止等待，不能撤销已受理的命令。
3. `Runtime.write` 独占日志序号，将最多 64 条或等待 1ms 收到的请求在 SQLite `FULL` 事务中提交。只有成功提交的命令才发布到 `durable`。
4. `Runtime.run` 独占 `Engine.Apply`。它检查连续序号及幂等，校验资金，预扫描成交工作量，冻结资产，执行价格时间优先撮合。
5. `Apply` 拷贝本次订单/余额变化和首次响应，不能把核心可变指针交给 HTTP/投影。后续成交不改变先前返回的订单快照。
6. `Runtime.project` 合并已就绪结果（不等待 1ms），先用 `copyResult` 隔离响应与投影的指针/切片并回包，再将订单、余额、成交、分录、价档及水位整批 FULL 提交到 `views.db`。投影完成后才归还在途额度。
7. 前端拿 `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 扩展阅读路径

1. runtime.go 的 schema/seq/hash 检查与已投影前缀跳过：不要误以为跳过投影就是跳过恢复核心。
2. store.go 的 ProjectBatch/applyProjected：整批提交，第二条失败首条也回滚，提交后才释放额度。
3. admin_query.go/market_query.go：同秒用户使用 rowid，多笔同 seq 成交也用 rowid seek；审计两个来源各自上界。
4. maintenance.go 与 cmd/exchangectl：同目录 flock，正规文件/manifest 校验，独立重放逐表摘要，坏投影保留与 staging。
5. observability.go：只发布外围原子副本/时长，标准 pprof 独立回环监听；字段数量由唯一核心调用者读取后发布。
6. cmd/loadcheck 和 scripts/load_check.py：固定工作者与有界客户端积压、计划至完成延迟、拒绝/丢弃/对账；发生器瓶颈与服务瓶颈分开。
7. crash_recovery_test/runtime_test/maintenance_test/property_test：精确窗口、整批事务回滚、额度生命周期、恢复/对账、固定 seed 守恒与静态依赖边界。

本轮测试入口与证明点补充见[测试手册](../04-testing/testing-guide.md)、[用例目录](../04-testing/test-cases.md)。`engine_boundary_test` 验证首次幂等记忆不能共享返回 Order 指针；`runtime_boundary_test` 占用唯一投影连接验证 `copyResult` 将响应与投影切片分离。前端 `tests/unit` 执行真实 api/pending TS 源码，React hook 的 DOM 行为仍由浏览器验证。

新增代码继续充分中文注释，解释用途、字段、顺序、边界和例子；对应设计见[v0.3](../07-history/v0.3-design.md)，实际证据见[报告](../reports/2026-10-11-v0.3.md)。

## 9. 配套使用与维护阅读

先用[接口使用指南](api-guide.md)走一遍登录—下单—原键确认—min_seq 查询；再用[数据生命周期](../05-deployment/data-lifecycle.md)区分三库、备份和投影重建。异常时按[故障排查手册](../05-deployment/operations-runbook.md)检查进程、认证、投影与磁盘。

本次注释审阅记录见[文档与注释报告](../reports/2026-10-11-documentation.md)。它记录文档纠偏与行为不变检查，旧测试源码摘要属于旧历史快照，不应在注释更新后继续宣称与当前文件逐字相同。


## Windows 本地运行代码路径

[CMD 入口](../../run-windows.cmd) → [PowerShell 构建与生命周期](../../scripts/run-windows.ps1) → server.localAdminConfig 回环检查 → BootstrapLocalAdmin → authAction 的配置别名映射 → 真实会话/RBAC。CreateUser/BootstrapAdmin 的常规 12 字节下限保留，本地模式只有可信初始化允许 8 字节。注册仍邮箱输入，登录允许文本别名；契约分别为 Credentials/LoginCredentials。使用与验证见[Windows 指南](../05-deployment/windows-local-run.md)。

## v0.5 阅读路线

先读 history.go（上界与钱包游标），再 tasks.go（schema 迁移和版本 CAS），index.go（连续块与事务），reconcile.go（固定投影水位重放），observability.go（无核心依赖的指标），最后 Web3History.tsx（取消旧读取、筛选重置、详情）。production_test.go 给出每条恢复边界的实际反例。
