# 从零手写 Go + React 模拟交易系统：新手手把手教程

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

> 历史 v0.4 变更记录（当前增量见页首 v0.5）：原23章继续教授从零完成模拟系统，教学数据不要混用链任务。下一阶段按链模式开发手册创建contracts/与chaintrade/：先解释签名和approve，再把立即成交改为pending，写真实EVM原子交换测试，最后加outbox、raw交易持久化、中间件和钱包恢复。完整逐文件教学仍是模拟版，链增量源码注释/设计提供对应阅读路径。 当前链实现见[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-12。对应本项目当前 v0.3 架构。主路线使用 **Windows + PowerShell + VS Code**；Go、React 的代码在 Linux/WSL 也能运行。

这份教程要教你从空目录亲手写出程序，再把它升级到本仓库的完整架构。你会写撮合、资金、单写者运行时、SQLite 持久化、注册登录、管理员、交易页面和测试，最后学习 Windows 运行、容器与云部署。资产是模拟的，没有真实充值提现。

教程分为两个连续阶段：第 1–13 章给出一个可以逐文件输入、编译、操作的教学项目；第 14–23 章在这个基础上升级到当前完整实现。教学代码故意保持较小，进阶章节会明确增加什么、在哪里增加、通过什么用例验收。**前半部分的 `/api`、数据结构、包名与最终项目的 `/api/v1` 不同，不要把两套文件混着编译。**

所有“完整文件”代码块可以复制到指定文件。标为“片段”的内容用于理解或插入已有函数，不能单独运行。每章都先完成验收再继续；不需要第一天懂红黑树或高可用。

## 阅读导航

- [1. 先认识你要做的东西](#chapter-01)
- [2. 安装工具并创建空目录](#chapter-02)
- [3. 写出第一段 Go 和第一个 HTTP 接口](#chapter-03)
- [4. 读懂 Go 的基本语法](#chapter-04)
- [5. 先把交易规则算清楚](#chapter-05)
- [6. 手写精确金额、订单簿和撮合核心](#chapter-06)
- [7. 写第一个业务单元测试](#chapter-07)
- [8. 写单写者运行时与 SQLite 日志](#chapter-08)
- [9. 写注册、登录、会话和管理员身份](#chapter-09)
- [10. 写 HTTP 接口和权限校验](#chapter-10)
- [11. 把后端装配起来](#chapter-11)
- [12. 从空目录写 React 交易页面](#chapter-12)
- [13. 操作、测试并重启你的教学项目](#chapter-13)
- [14. 从教学版升级到完整项目](#chapter-14)
- [15. 补全订单规则、预算和对象所有权](#chapter-15)
- [16. 升级日志、增量投影与恢复](#chapter-16)
- [17. 补全认证、契约和管理员审计](#chapter-17)
- [18. 写分页、实时行情和待确认请求恢复](#chapter-18)
- [19. 设计完整测试并读懂性能结果](#chapter-19)
- [20. 写注释、规范与项目文档](#chapter-20)
- [21. 运行当前完整项目和 Windows 脚本](#chapter-21)
- [22. 容器与云服务器部署](#chapter-22)
- [23. 备份、故障排查与毕业验收](#chapter-23)

<a id="chapter-01"></a>
## 1. 先认识你要做的东西

### 1.1 从生活中的交易理解系统

小王说：“我愿意用每个最多 105 USDT 买 3 个 ETH。”小李说：“我愿意用每个 100 USDT 卖 2 个 ETH。”系统发现二者价格能对上，按既有卖单的 100 成交 2 个，剩下 1 个买单继续等待。USDT 可以先理解成付款单位，ETH 是购买的商品单位。

**订单**是买卖意愿；**成交**是已经发生的交换。下单成功并不等于成交成功。一笔订单可以成交多次，也可以没有成交就被撤销。**撮合**就是按事先约定的规则挑出可以成交的订单。

### 1.2 前端、后端、数据库各做什么

| 名词 | 用白话解释 | 本项目的工具 |
| --- | --- | --- |
| 前端 | 浏览器里看到的页面，收集输入和展示结果 | React + TypeScript |
| 后端 | 收到请求、检查身份、处理交易的程序 | Go |
| 数据库 | 程序关闭后仍能保存数据的文件或服务 | SQLite 文件 |
| HTTP | 浏览器和服务之间的请求/响应协议 | Go 标准库 + fetch |
| JSON | 双方约定的数据文本格式 | `{"price":"105"}` |
| API/接口 | 可以按约定地址调用的一项服务 | `POST /api/orders` |
| 端口 | 同一机器上区分不同网络服务的编号 | 后端 8080，开发页面 5173 |
| localhost/127.0.0.1 | 当前这台机器 | 教学服务仅本机访问 |
| 进程 | 正在运行的一个程序实例 | 一个交易后端 |
| goroutine | Go 中独立推进的一段工作 | HTTP、写日志、核心、投影 |

`GET` 常用于读取，`POST` 常用于提交动作，`PATCH` 常用于修改某些字段。`200` 表示 HTTP 成功，`400` 参数错误，`401` 未登录，`403` 无权，`503` 服务暂时不可用。**HTTP 成功、订单成交、资金充足是三个不同概念。**

```mermaid
flowchart LR
    U[浏览器输入] --> H[HTTP：身份和参数检查]
    H --> J[日志写入 SQLite]
    J --> E[唯一核心：撮合和资金]
    E --> V[查询投影 SQLite]
    V --> U
```

### 1.3 这个项目的主线

普通用户注册 → 登录 → 获得模拟初始资金 → 下单 → 冻结资金 → 成交或挂单 → 撤单释放余量。管理员可以查看用户、停用用户、增加模拟资金。关掉后端再启动，历史订单和资金应该保留。

以后面试时要能回答：“输入在哪里验身份？什么时候算受理？什么时候落盘？谁能修改资金？浏览器断网时怎么办？”它们比页面颜色更能说明你理解了系统。

<a id="chapter-02"></a>
## 2. 安装工具并创建空目录

### 2.1 安装与确认

安装 [Go](https://go.dev/dl/)、[Node.js](https://nodejs.org/en/download)、[VS Code](https://code.visualstudio.com/)。Go 以项目 `go.mod` 的 **1.26.9** 为准；Node 使用 22 或更高版本。本项目使用纯 Go SQLite 驱动，开发不需要安装 MySQL、Redis、C 编译器或 SQLite 服务。

安装完重新打开 PowerShell。可以在开始菜单搜索“PowerShell”，也可以在 VS Code 的“终端 → 新建终端”中选择 PowerShell。输入下面命令，**不复制行首提示符**：

```powershell
go version
node --version
npm --version
```

看到版本号才算安装成功。`go 不是内部或外部命令` 表示 PATH 没生效；重开终端再检查安装路径。PowerShell 若阻止 `npm.ps1`，本文所有 `npm` 命令可改成 `npm.cmd`，无需修改整台机器的执行策略。

### 2.2 专门建立练习目录

下面命令全部在 PowerShell 中执行。路径仅为例子，你可以换成自己的磁盘。**新练习目录不要使用现有 `web3`，避免覆盖完成的项目。**

```powershell
New-Item -ItemType Directory -Force D:\exchange-learn
Set-Location D:\exchange-learn
Get-Location
New-Item -ItemType Directory -Force core,runtime,auth,transport,cmd\server,frontend\src
code .
```

`New-Item` 创建目录；`Set-Location` 切换当前目录；`Get-Location` 查看你现在在哪。最后一条打开编辑器，若 `code` 不可用，通过 VS Code 的“打开文件夹”选择这个目录。

Linux/WSL 对应命令是 `mkdir -p ~/exchange-learn`、`cd ~/exchange-learn`；后面的 `go`/`npm` 大部分一致。**别在 Windows 与 WSL 之间共用同一个 node_modules**，它包含平台相关程序。

### 2.3 创建 Go 模块与依赖

在 `D:\exchange-learn` 根目录执行：

```powershell
go mod init exchangelearn
go mod edit -go=1.26.9
go get github.com/shopspring/decimal@v1.4.0
go get github.com/emirpasic/gods@v1.18.1
go get github.com/gofrs/flock@v0.12.1
go get golang.org/x/crypto@v0.58.0
go get modernc.org/sqlite@v1.60.1
```

`exchangelearn` 是你项目的模块名，因此后面才能写 `import "exchangelearn/core"`。`go.mod` 记录依赖版本，`go.sum` 记录校验摘要；两者都保留。`go get` 下载指定依赖；Go 工具链允许自动下载匹配版本，首次需要联网。若本机设置 `GOTOOLCHAIN=local` 且版本太旧，使用当前终端 `$env:GOTOOLCHAIN="auto"` 或安装所需 Go。

依赖为什么选这些：decimal 做精确十进制计算；GoDS 提供红黑树；flock 防止两个进程同时打开同一数据目录；x/crypto 的 bcrypt 存密码摘要；modernc/sqlite 用 Go 操作内嵌数据库。我们不手写密码算法或红黑树。

创建根目录 `.gitignore`，写入下面完整内容，防止把依赖、数据、产物当源码提交：

```gitignore
/data/
/frontend/node_modules/
/frontend/dist/
/bin/
.env
*.tsbuildinfo
```

**本章验收：**目录存在，版本命令有效，根目录出现 `go.mod` 和 `go.sum`。首次下载失败先检查网络和代理；不要把未下载成功当作代码错误。

<a id="chapter-03"></a>
## 3. 写出第一段 Go 和第一个 HTTP 接口

### 3.1 第一个程序

新建 `cmd/server/main.go`，输入下面完整文件：

```go
package main

import "fmt"

func main() {
    fmt.Println("我的模拟交易项目开始了")
}
```

根目录运行：

```powershell
go run ./cmd/server
```

它应打印一行文字后退出。`package main` 表示可执行程序；`func main()` 是入口；`fmt.Println` 是标准库打印函数。文件保存后再运行，VS Code 标签页上的小圆点表示还没保存。

### 3.2 改成一个常驻服务

用下面完整文件替换同一份 `cmd/server/main.go`：

```go
package main

import (
    "encoding/json"
    "log"
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _ = json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    })
    log.Print("打开 http://127.0.0.1:8080/health")
    if err := http.ListenAndServe("127.0.0.1:8080", mux); err != nil {
        log.Fatal(err)
    }
}
```

运行同一条 `go run ./cmd/server`。这次窗口不退出，因为它在等请求。打开**第二个 PowerShell 窗口**执行：

```powershell
Invoke-RestMethod http://127.0.0.1:8080/health
```

看到 `status ok` 即完成；浏览器直接打开相同地址会看到 JSON。第一个窗口按 Ctrl+C 停止，然后才能继续覆盖代码。端口被占用意味着旧服务还开着；关闭你自己的旧窗口，别随便结束其他程序。

<a id="chapter-04"></a>
## 4. 读懂后面会用到的 Go 基本语法

不要求背完整 Go 教程，但先能看懂以下对应关系。

| 写法 | 含义 | 为什么项目要用 |
| --- | --- | --- |
| `type Order struct { ID string }` | 把几个字段组成一个类型 | 一张订单有编号、方向、数量 |
| `o := Order{ID: "1"}` | 建一个值并推导变量类型 | 创建订单 |
| `*Order` / `&o` | 指向某个订单的指针 / 取得地址 | 核心可更新同一个订单 |
| `[]Order` | 可变长度的订单列表，叫 slice | 一页订单或一批变更 |
| `map[string]*Order` | 用字符串找到订单的字典 | 按 ID 快速撤单 |
| `value, ok := m[key]` | 查字典，并判断键是否存在 | 区分未知订单与已有订单 |
| `func (e *Engine) Apply(...)` | 属于 Engine 的方法 | 让引擎处理命令 |
| `value, err := f()` | 返回结果和错误 | 普通错误通过返回处理 |
| `defer db.Close()` | 当前函数返回时再清理 | 正确关闭数据库 |
| `go f()` | 开始一个 goroutine | 外围任务独立运行 |
| `make(chan T, 64)` | 最多缓冲 64 项的消息队列 | 限制等待命令数量 |
| `ch <- x` / `x := <-ch` | 往队列发送 / 从队列接收 | 按顺序传命令 |
| `for x := range ch` | 依次读取，队列关闭且读完才退出 | 排空工作 |
| `select` | 在多个队列/取消信号之间等待 | 支持超时和拒绝入队 |
| `` `json:"price"` `` | JSON 中字段叫什么 | Go 的 Price 对应 price |
| `_ "modernc.org/sqlite"` | 加载驱动的注册动作 | 让 database/sql 认识 sqlite |

**值复制不等于深拷贝。**`b := a` 会复制结构体，但里面的指针可能仍指着同一个订单，slice 也可能共享底层数组。后面每次把订单交给 HTTP/投影时要复制，不能让其他 goroutine 改核心对象。

`panic` 会中断正常控制流，不能用它表示“余额不足”。本教程只在“已提交日志序号断裂”这种内部不变量损坏时使用它；金额错误、权限错误、无流动性都要返回正常结果。

练习：用自己的话说明 `map[string]*Order` 与 `[]Order` 各适合解决什么问题；再说明 `go e.Apply(c)` 为什么会破坏单写者。

<a id="chapter-05"></a>
## 5. 写代码前，先把交易规则算清楚

### 5.1 五条最基础规则

1. 买价越高优先，卖价越低优先；同一价格先到先成交，这叫 FIFO。
2. 新来并主动吃已有挂单的叫 taker；已有挂单叫 maker；按 maker 的价格成交。
3. 买单冻结 `限价 × 数量` 的 USDT，卖单冻结对应 ETH。
4. 成交只交换资产，零手续费演示中不会凭空增加 USDT 或 ETH；只有 CREDIT 注资增加模拟总供给。
5. 撤单只释放尚未成交部分；已经成交的部分不能撤回。

GTC 表示未成交部分继续挂单；IOC 表示立即能成交多少成交多少，然后取消剩余部分。教学版先实现 LIMIT GTC，最终版加入 IOC 和带保护价的 MARKET。

### 5.2 贯穿全篇的算例

买方开始有 1000 USDT，卖方开始有 10 ETH。先挂卖单 `2 ETH @100`，然后买方提交 `3 ETH @105`。

| 时刻 | 买方可用 USDT | 买方冻结 USDT | 买方 ETH | 卖方可用 ETH | 卖方冻结 ETH | 卖方 USDT |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 初始 | 1000 | 0 | 0 | 10 | 0 | 0 |
| 卖单挂出 | 1000 | 0 | 0 | 8 | 2 | 0 |
| 买单冻结 315 | 685 | 315 | 0 | 8 | 2 | 0 |
| 按 100 成交 2 | 695 | 105 | 2 | 8 | 0 | 200 |
| 买方撤剩余 1 | 800 | 0 | 2 | 8 | 0 | 200 |

关键步骤：买方本次成交部分原冻结 `105×2=210`，实际支付 `100×2=200`，价差 `10` 立刻回可用余额，余量 `1×105=105` 仍冻结。

资产守恒：最终 `800+200=1000 USDT`，`2+8=10 ETH`。订单守恒：买单 `3=成交2+撤销1+余量0`。这些式子会成为测试断言。

### 5.3 为什么金额是字符串

JSON 写 `"price":"0.1"`，不能先把它变成浮点再转 decimal。常见二进制浮点不能精确表示所有十进制小数。后端 decimal 精确运算；前端保留字符串，避免金额和大序号的精度丢失。价格最多 2 位小数，ETH 数量最多 4 位，乘起来的 USDT 最多 6 位。

输入 `1e2`、`+1`、`01`、`0`（需要正数时）或超精度值应拒绝，不能偷偷舍入。`0.10` 与 decimal 输出 `0.1` 数值相同；最终版在外围规范化后计算幂等摘要。


<a id="chapter-06"></a>
## 6. 手写精确金额、订单簿和撮合核心

### 6.1 先决定核心可以碰什么

核心只接收 `Command`，只做内存运算，返回 `Result`。它不能读数据库、调用 HTTP、读当前时间、产生随机编号或取得业务锁。这保证同一批历史命令重新执行时，得到相同业务结果。

先看结构，再输入代码，建议按下面顺序分六次写入同一个文件：

1. 定义 Command/Order/Balance/Trade/Result/State：明确输入、业务对象、输出。
2. 定义 level/ref/saved/Engine 和 New：建立状态容器。
3. 写 Parse/d/balance/move/clone：精确金额、资金变更和对象隔离。
4. 写 add/remove/best/release：管理订单簿与解冻。
5. 写 place：校验→冻结→逐笔撮合→余量挂簿。
6. 写 Apply/Snapshot：命令分发、幂等和状态副本。

输入时可先跳过尚未定义的函数产生的编辑器红线；全文件完成后才编译。不要用空函数替代业务后继续后面的章。

### 6.2 订单簿为什么需要两层结构

红黑树按价格找档位，档位里用双向链表按到达顺序排订单。树键是 `价格×100`，例如 105.25 对应整数 10525。验证价格上限和两位小数后，这个转换才安全。

买树取最大价格，卖树取最小价格。BUY 查卖树，SELL 查买树。链表 Front 是最早的 maker；PushBack 将新单排到同价档队尾。`active[id]` 保存它的链表节点，撤单可以直接删除，不用找遍所有订单。

复杂度中的 P 是“不同价档数”：查档/删空档约 O(log P)，同档插入/删除节点 O(1)。教学版 best 每次取树端点；最终版还缓存最优档，常见读取 O(1)。一张大单吃掉 k 张对手单，工作量仍与 k 有关，不能把整笔撮合说成 O(1)。


下面是 `core/core.go` 的**完整文件**：

```go
package core

import (
	"container/list"
	"fmt"
	"regexp"
	"sort"
	"strconv"

	"github.com/emirpasic/gods/trees/redblacktree"
	"github.com/shopspring/decimal"
)

// Command 是外部固定好的输入；Seq、Hash 由运行时设置，Account 由会话设置。
type Command struct {
	Seq      int64  `json:"seq"`
	Hash     string `json:"hash"`
	Account  string `json:"account"`
	Key      string `json:"key"`
	Kind     string `json:"kind"`
	Side     string `json:"side,omitempty"`
	Price    string `json:"price,omitempty"`
	Quantity string `json:"quantity,omitempty"`
	OrderID  string `json:"order_id,omitempty"`
	Asset    string `json:"asset,omitempty"`
	Amount   string `json:"amount,omitempty"`
	Actor    string `json:"actor,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

type Order struct {
	ID        string `json:"id"`
	Account   string `json:"account"`
	Side      string `json:"side"`
	Price     string `json:"price"`
	Quantity  string `json:"quantity"`
	Remaining string `json:"remaining"`
	Filled    string `json:"filled"`
	Canceled  string `json:"canceled"`
	Status    string `json:"status"`
}

type Balance struct {
	Account   string `json:"account"`
	Asset     string `json:"asset"`
	Available string `json:"available"`
	Frozen    string `json:"frozen"`
}

type Trade struct {
	ID       string `json:"id"`
	Maker    string `json:"maker"`
	Taker    string `json:"taker"`
	Price    string `json:"price"`
	Quantity string `json:"quantity"`
}

// Result 不含所有人的余额；HTTP 可以直接返回它。
type Result struct {
	ProcessedSeq string  `json:"processed_seq"`
	ResultSeq    string  `json:"result_seq"`
	Code         string  `json:"code,omitempty"`
	Replayed     bool    `json:"replayed"`
	Order        *Order  `json:"order,omitempty"`
	Trades       []Trade `json:"trades"`
}

// State 只交给持久化层；公开接口必须按当前会话过滤。
type State struct {
	Orders   []Order   `json:"orders"`
	Balances []Balance `json:"balances"`
}

type level struct {
	price decimal.Decimal
	queue *list.List
}
type ref struct {
	order *Order
	level *level
	node  *list.Element
}
type saved struct {
	hash   string
	result Result
}

type Engine struct {
	seq        int64
	bids, asks *redblacktree.Tree
	active     map[string]*ref
	orders     map[string]*Order
	balances   map[string]*Balance
	dedupe     map[string]saved
}

func New() *Engine {
	cmp := func(a, b interface{}) int {
		x, y := a.(int64), b.(int64)
		if x < y {
			return -1
		}
		if x > y {
			return 1
		}
		return 0
	}
	return &Engine{bids: redblacktree.NewWith(cmp), asks: redblacktree.NewWith(cmp),
		active: map[string]*ref{}, orders: map[string]*Order{},
		balances: map[string]*Balance{}, dedupe: map[string]saved{}}
}

var amountPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)(\.[0-9]+)?$`)

// Parse 验证原始文本，绝不把用户输入静默四舍五入。
func Parse(text string, scale int32, max string) (decimal.Decimal, bool) {
	if len(text) > 32 || !amountPattern.MatchString(text) {
		return decimal.Zero, false
	}
	n, err := decimal.NewFromString(text)
	return n, err == nil && n.IsPositive() && n.Exponent() >= -scale &&
		n.LessThanOrEqual(decimal.RequireFromString(max))
}

// d 仅用于已经验证过的文本；外部输入先调用 Parse。
func d(text string) decimal.Decimal { return decimal.RequireFromString(text) }

func (e *Engine) balance(account, asset string) *Balance {
	key := account + ":" + asset
	if e.balances[key] == nil {
		e.balances[key] = &Balance{account, asset, "0", "0"}
	}
	return e.balances[key]
}

// move 的两个增量可正可负；调用者必须先检查足够资金。
func (e *Engine) move(account, asset string, available, frozen decimal.Decimal) {
	b := e.balance(account, asset)
	b.Available = d(b.Available).Add(available).String()
	b.Frozen = d(b.Frozen).Add(frozen).String()
}

func clone(r Result) Result {
	if r.Order != nil {
		o := *r.Order
		r.Order = &o
	}
	r.Trades = append([]Trade{}, r.Trades...)
	return r
}

// Apply 只能由启动重放或一个核心 goroutine 调用。
func (e *Engine) Apply(c Command) Result {
	if c.Seq != e.seq+1 {
		panic("command sequence gap")
	}
	e.seq = c.Seq
	seq := strconv.FormatInt(c.Seq, 10)
	r := Result{ProcessedSeq: seq, ResultSeq: seq, Trades: []Trade{}}
	key := c.Account + ":" + c.Key
	if old, ok := e.dedupe[key]; ok {
		if old.hash != c.Hash {
			r.Code = "IDEMPOTENCY_CONFLICT"
			return r
		}
		r = clone(old.result)
		r.ProcessedSeq = seq
		r.Replayed = true
		r.Trades = []Trade{} // 首次成交不能再次对外作为新成交发布。
		return r
	}
	switch c.Kind {
	case "CREDIT":
		scale, max := int32(6), "1000000000000"
		if c.Asset == "ETH" {
			scale, max = 4, "1000000"
		}
		n, ok := Parse(c.Amount, scale, max)
		if !ok || (c.Asset != "ETH" && c.Asset != "USDT") {
			r.Code = "INVALID_AMOUNT"
			break
		}
		e.move(c.Account, c.Asset, n, decimal.Zero)
	case "PLACE":
		e.place(c, &r)
	case "CANCEL":
		o := e.orders[c.OrderID]
		if o == nil {
			r.Code = "ORDER_NOT_FOUND"
			break
		}
		if o.Account != c.Account {
			r.Code = "FORBIDDEN"
			break
		}
		item := e.active[o.ID]
		if item == nil {
			r.Code = "ORDER_TERMINAL"
			break
		}
		e.release(o, d(o.Remaining))
		o.Canceled = d(o.Canceled).Add(d(o.Remaining)).String()
		o.Remaining = "0"
		o.Status = "CANCELED"
		e.remove(item)
		r.Order = o
	default:
		r.Code = "INVALID_COMMAND"
	}
	r = clone(r)                            // 隔离核心订单原件。
	e.dedupe[key] = saved{c.Hash, clone(r)} // 再隔离首次结果与返回结果。
	return r
}

func (e *Engine) add(o *Order) {
	tree := e.bids
	if o.Side == "SELL" {
		tree = e.asks
	}
	ticks := d(o.Price).Shift(2).IntPart()
	value, ok := tree.Get(ticks)
	var l *level
	if ok {
		l = value.(*level)
	} else {
		l = &level{d(o.Price), list.New()}
		tree.Put(ticks, l)
	}
	e.active[o.ID] = &ref{o, l, l.queue.PushBack(o)}
}

func (e *Engine) remove(item *ref) {
	item.level.queue.Remove(item.node)
	delete(e.active, item.order.ID)
	if item.level.queue.Len() == 0 {
		tree := e.bids
		if item.order.Side == "SELL" {
			tree = e.asks
		}
		tree.Remove(item.level.price.Shift(2).IntPart())
	}
}

func (e *Engine) best(side string) *level {
	if side == "BUY" {
		if n := e.asks.Left(); n != nil {
			return n.Value.(*level)
		}
	}
	if side == "SELL" {
		if n := e.bids.Right(); n != nil {
			return n.Value.(*level)
		}
	}
	return nil
}

func (e *Engine) release(o *Order, q decimal.Decimal) {
	asset, amount := "ETH", q
	if o.Side == "BUY" {
		asset, amount = "USDT", d(o.Price).Mul(q)
	}
	e.move(o.Account, asset, amount, amount.Neg())
}

func (e *Engine) place(c Command, r *Result) {
	price, okP := Parse(c.Price, 2, "1000000")
	quantity, okQ := Parse(c.Quantity, 4, "1000000")
	if !okP || !okQ || (c.Side != "BUY" && c.Side != "SELL") {
		r.Code = "INVALID_ORDER"
		return
	}
	// 教学版只有 LIMIT GTC；资金校验必须在任何订单簿变更之前。
	asset, needed := "ETH", quantity
	if c.Side == "BUY" {
		asset, needed = "USDT", price.Mul(quantity)
	}
	if d(e.balance(c.Account, asset).Available).LessThan(needed) {
		r.Code = "INSUFFICIENT_FUNDS"
		return
	}
	e.move(c.Account, asset, needed.Neg(), needed)
	o := &Order{ID: strconv.FormatInt(c.Seq, 10), Account: c.Account, Side: c.Side,
		Price: price.String(), Quantity: quantity.String(), Remaining: quantity.String(),
		Filled: "0", Canceled: "0", Status: "OPEN"}
	e.orders[o.ID] = o
	r.Order = o
	for d(o.Remaining).IsPositive() {
		l := e.best(c.Side)
		if l == nil {
			break
		}
		if c.Side == "BUY" && l.price.GreaterThan(price) {
			break
		}
		if c.Side == "SELL" && l.price.LessThan(price) {
			break
		}
		maker := l.queue.Front().Value.(*Order)
		if maker.Account == o.Account {
			// cancel_taker：停止新单，原先自己的挂单保留。
			e.release(o, d(o.Remaining))
			o.Canceled = o.Remaining
			o.Remaining = "0"
			o.Status = "CANCELED"
			break
		}
		q := decimal.Min(d(o.Remaining), d(maker.Remaining))
		buyer, seller := o, maker
		if c.Side == "SELL" {
			buyer, seller = maker, o
		}
		cost := l.price.Mul(q)
		reserved := d(buyer.Price).Mul(q)
		e.move(buyer.Account, "USDT", reserved.Sub(cost), reserved.Neg())
		e.move(buyer.Account, "ETH", q, decimal.Zero)
		e.move(seller.Account, "ETH", decimal.Zero, q.Neg())
		e.move(seller.Account, "USDT", cost, decimal.Zero)
		r.Trades = append(r.Trades, Trade{fmt.Sprintf("%d/%d", c.Seq, len(r.Trades)),
			maker.ID, o.ID, l.price.String(), q.String()})
		for _, item := range []*Order{maker, o} {
			item.Remaining = d(item.Remaining).Sub(q).String()
			item.Filled = d(item.Filled).Add(q).String()
			item.Status = "PARTIALLY_FILLED"
			if item.Remaining == "0" {
				item.Status = "FILLED"
			}
		}
		if maker.Remaining == "0" {
			e.remove(e.active[maker.ID])
		}
	}
	if d(o.Remaining).IsPositive() {
		e.add(o)
	}
}

// Snapshot 复制全部状态，仅为小数据教学。最终项目改用增量投影。
func (e *Engine) Snapshot() State {
	s := State{Orders: []Order{}, Balances: []Balance{}}
	for _, o := range e.orders {
		s.Orders = append(s.Orders, *o)
	}
	for _, b := range e.balances {
		s.Balances = append(s.Balances, *b)
	}
	// map 无固定遍历顺序；排序使同一输入产生相同序列化状态。
	sort.Slice(s.Orders, func(i, j int) bool { return d(s.Orders[i].ID).LessThan(d(s.Orders[j].ID)) })
	sort.Slice(s.Balances, func(i, j int) bool {
		return s.Balances[i].Account+":"+s.Balances[i].Asset < s.Balances[j].Account+":"+s.Balances[j].Asset
	})
	return s
}
```


### 6.3 对着代码走一遍资金算例

`e.place` 先 Parse，再检查 buyer 的 Available≥315，之后 `move(-315,+315)`。循环选到价格100、数量2的 maker，`q=min(3,2)=2`。四次 move 对应：

| 对象/资产 | AvailableDelta | FrozenDelta | 解释 |
| --- | ---: | ---: | --- |
| 买方 USDT | +10 | -210 | 返价差并消费对应冻结 |
| 买方 ETH | +2 | 0 | 获得商品 |
| 卖方 ETH | 0 | -2 | 交付冻结商品 |
| 卖方 USDT | +200 | 0 | 收取货款 |

`maker.Remaining` 归零，remove 从活动簿删除；买方余量1还在簿中。撤单时 release 按原价105释放，不按当前行情。Order 原始 Quantity 不变，Filled 与 Canceled 记录去了哪里。

### 6.4 幂等为什么在核心里

你点了一次下单，但网络断了，不知道是否成功。若新建另一张单会重复买入；因此重发**原 account/key/内容**，核心从 `dedupe` 返回首次结果，禁止再次冻结或成交。

相同 key、不同 Hash 返回冲突。第一次余额不足也会被记住，后来充值后应使用新 key 发新意愿。每次重试仍消费日志 Seq，首次 ResultSeq 不变，本次 ProcessedSeq 增长。

`clone` 的两次调用很重要：一次隔离核心订单原件与本次输出，另一次隔离首次记忆与输出。撤单后重试下单仍拿到“当时首次下单结果”，最新订单应通过查询获取。

**本章验收：**根目录运行 `gofmt -w core` 与 `go test ./core`。暂时显示 `[no test files]` 仅表示编译通过；下一章才验证业务。最常见错误是 import 路径写成原项目的 web3exchange、字段拼写不一致或漏掉大括号。


<a id="chapter-07"></a>
## 7. 写第一个业务单元测试

测试是让程序自动检查“实际结果是否等于我们事先算出的结果”。测试不需要启动浏览器，也不需要真实数据库；现在只验证 Engine。

创建 `core/core_test.go`。Go 会自动发现以 `_test.go` 结尾的文件和 `TestXxx` 函数。`t.Fatal`/`t.Fatalf` 表示失败，不要把计算错误改成“允许一点误差”。


下面是 `core/core_test.go` 的**完整文件**：

```go
package core

import (
	"fmt"
	"testing"
)

func TestTradeAndCancel(t *testing.T) {
	e := New()
	var seq int64
	apply := func(c Command) Result {
		seq++
		c.Seq = seq
		// 单元测试固定摘要，真实运行时由 SHA256 计算。
		c.Hash = fmt.Sprintf("%s|%s|%s|%s|%s|%s|%s", c.Kind, c.Side, c.Price, c.Quantity, c.OrderID, c.Asset, c.Amount)
		r := e.Apply(c)
		if r.Code != "" {
			t.Fatalf("unexpected code: %s", r.Code)
		}
		return r
	}
	apply(Command{Account: "buyer", Key: "fund-buyer", Kind: "CREDIT", Asset: "USDT", Amount: "1000"})
	apply(Command{Account: "seller", Key: "fund-seller", Kind: "CREDIT", Asset: "ETH", Amount: "10"})
	apply(Command{Account: "seller", Key: "sell-001", Kind: "PLACE", Side: "SELL", Price: "100", Quantity: "2"})
	buy := Command{Account: "buyer", Key: "buy-0001", Kind: "PLACE", Side: "BUY", Price: "105", Quantity: "3"}
	first := apply(buy)
	if first.Order.Remaining != "1" || len(first.Trades) != 1 || first.Trades[0].Price != "100" {
		t.Fatalf("bad fill: %+v", first)
	}
	check := func(account, asset, available, frozen string) {
		t.Helper()
		b := e.balance(account, asset)
		if b.Available != available || b.Frozen != frozen {
			t.Fatalf("balance %+v", b)
		}
	}
	check("buyer", "USDT", "695", "105")
	check("buyer", "ETH", "2", "0")
	check("seller", "USDT", "200", "0")
	check("seller", "ETH", "8", "0")
	// 修改返回值，不能修改核心/记忆；也不能改变下一次重试的首次响应。
	id := first.Order.ID
	first.Order.Remaining = "999"
	again := apply(buy)
	if !again.Replayed || again.Order.Remaining != "1" || len(again.Trades) != 0 {
		t.Fatalf("bad dedupe: %+v", again)
	}
	canceled := apply(Command{Account: "buyer", Key: "cancel-01", Kind: "CANCEL", OrderID: id})
	if canceled.Order.Canceled != "1" || canceled.Order.Remaining != "0" {
		t.Fatal(canceled)
	}
	check("buyer", "USDT", "800", "0")
	replay := apply(buy)
	if replay.Order.Remaining != "1" {
		t.Fatal("first result changed after cancel")
	}
	// 1000 USDT 与 10 ETH 的系统总量不因成交/撤单变化。
	totalUSDT := d(e.balance("buyer", "USDT").Available).Add(d(e.balance("seller", "USDT").Available))
	totalETH := d(e.balance("buyer", "ETH").Available).Add(d(e.balance("seller", "ETH").Available))
	if totalUSDT.String() != "1000" || totalETH.String() != "10" {
		t.Fatal("asset conservation broken")
	}
}

func TestParse(t *testing.T) {
	for _, text := range []string{"0", "-1", "01", "1e2", "1.001"} {
		if _, ok := Parse(text, 2, "1000000"); ok {
			t.Fatalf("accepted %s", text)
		}
	}
	if n, ok := Parse("0.10", 2, "1000000"); !ok || n.String() != "0.1" {
		t.Fatal(n, ok)
	}
}

// 相同价格只按入簿顺序决定maker；自成交不挪走原挂单。
func TestFIFOAndSelfTrade(t *testing.T) {
    e := New()
    var seq int64
    apply := func(c Command) Result {
        seq++
        c.Seq = seq
        c.Hash = c.Key // 每项测试输入使用独立key，不测试重试摘要。
        r := e.Apply(c)
        if r.Code != "" { t.Fatalf("unexpected code: %s", r.Code) }
        return r
    }
    apply(Command{Account:"seller",Key:"fund-seller",Kind:"CREDIT",Asset:"ETH",Amount:"10"})
    apply(Command{Account:"buyer",Key:"fund-buyer",Kind:"CREDIT",Asset:"USDT",Amount:"1000"})
    apply(Command{Account:"seller",Key:"fund-quote",Kind:"CREDIT",Asset:"USDT",Amount:"1000"})
    first := apply(Command{Account:"seller",Key:"sell-001",Kind:"PLACE",Side:"SELL",Price:"100",Quantity:"1"})
    second := apply(Command{Account:"seller",Key:"sell-002",Kind:"PLACE",Side:"SELL",Price:"100",Quantity:"1"})
    buy := apply(Command{Account:"buyer",Key:"buy-0001",Kind:"PLACE",Side:"BUY",Price:"100",Quantity:"1"})
    if len(buy.Trades)!=1 || buy.Trades[0].Maker!=first.Order.ID {
        t.Fatalf("FIFO broken: %+v", buy)
    }
    ownBuy := apply(Command{Account:"seller",Key:"self-buy",Kind:"PLACE",Side:"BUY",Price:"100",Quantity:"1"})
    if ownBuy.Order.Status!="CANCELED" || ownBuy.Order.Canceled!="1" || len(ownBuy.Trades)!=0 {
        t.Fatalf("self trade was not canceled: %+v", ownBuy)
    }
    if e.orders[second.Order.ID].Remaining!="1" || e.active[second.Order.ID]==nil {
        t.Fatal("existing maker changed by self trade")
    }
    b := e.balance("seller","USDT")
    if b.Available!="1100" || b.Frozen!="0" { t.Fatalf("self trade reserve not released: %+v",b) }
}

```


根目录执行：

```powershell
go test -count=1 -v ./core
```

你应该看到 `TestTradeAndCancel`、`TestParse`、`TestFIFOAndSelfTrade` 均 PASS。`-count=1` 要求重新执行，避免成功缓存。测试刻意修改 `first.Order.Remaining` 再重试，证明外部对象不能污染核心或首次结果；这比只测返回码更有价值。

动手练习：

- 买单价格从105改为99，应该没有成交；买方冻结297，卖方仍冻结2 ETH。增加独立测试，不改原来的算例。
- 两张同价卖单依次到达，各卖1，买1应先成交最早的 Maker；断言成交 Maker ID，而不只检查数量。
- 第一次余额不足后，用同 key 重试仍拒绝；给新 key 才能表达新的业务意愿。
- 用另一个 Account 撤此买单应 FORBIDDEN，资金与挂单完全不变。

先尝试自己写。最终仓库的 [engine_test.go](../../backend/engine_test.go)、[unit_test.go](../../backend/unit_test.go) 是进阶参考；它们使用完整项目 DTO，不能原样放进 exchangelearn。


<a id="chapter-08"></a>
## 8. 写单写者运行时与 SQLite 日志

### 8.1 先理解为什么不让 HTTP 直接调用 Apply

Go 的 HTTP 可以同时处理很多请求。如果每个 handler 都调用 Engine.Apply，多个人会同时读写 map、余额、链表。给它们都上锁会带来复杂的锁顺序；这里将所有输入排队，只有一个 goroutine 拿到核心并修改状态。

单写者是**状态所有权规则**，不是整个服务只有一个线程。HTTP、密码哈希、数据库读写都在外围。我们采用 LMAX 的单写者思路，通过有界 Go channel 实现，未移植 Disruptor 环形缓冲。

教学版先用下面流程：

```text
Submit → input → writer(SQLite FULL Commit)
       → durable → 核心 Apply → results
       → projector(保存完整视图) → 回包
```

最终版回包位置不同：投影 worker 先复制并回包，再做增量批投影。教学版等投影成功后回包，先减少新手对查询滞后的困惑，第16章再正式改变语义。

### 8.2 SQL 的最低知识

表像带规则的表格，行是一条记录，列是字段。主键保证编号唯一。`INSERT` 新增，`SELECT` 读取，`UPDATE` 改已有行，`DELETE` 删除。`?` 是参数占位，不把用户字符串拼进 SQL。

事务表示几条 SQL 要一起成功：Begin 开始，Commit 提交，Rollback 放弃。SQLite 的 WAL 模式允许读写协作，`synchronous=FULL` 是本项目的持久化配置。**SQLite 自己的 WAL 与 commands 业务日志表是两层不同东西**，不要把文件的 -wal 直接当成可重放命令。

journal.db 存确定性输入，views.db 存方便查询的输出；后面 auth.db 存身份。views 可重建，journal/auth 不能随意删。flock 独占整个目录，防止两套内存核心同时解释同一数据。


下面是 `runtime/runtime.go` 的**完整文件**：

```go
package runtime

import (
	"context"
	"crypto/sha256"
	"database/sql"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"

	"exchangelearn/core"
	"github.com/gofrs/flock"
	_ "modernc.org/sqlite"
)

type envelope struct {
	command core.Command
	reply   chan answer
	result  core.Result
	state   core.State
}
type answer struct {
	result core.Result
	err    error
}

type Runtime struct {
	journal, views          *sql.DB
	lock                    *flock.Flock
	input, durable, results chan envelope
	done                    chan struct{}
	last                    int64 // 只有日志 writer 修改。
}

// OpenDB 只由外围调用；连接限制避免不同连接使用不一致 PRAGMA。
func OpenDB(path string) (*sql.DB, error) {
	db, err := sql.Open("sqlite", path)
	if err != nil {
		return nil, err
	}
	db.SetMaxOpenConns(1)
	for _, stmt := range []string{"PRAGMA journal_mode=WAL", "PRAGMA synchronous=FULL",
		"PRAGMA foreign_keys=ON", "PRAGMA busy_timeout=5000"} {
		if _, err = db.Exec(stmt); err != nil {
			db.Close()
			return nil, err
		}
	}
	return db, nil
}

func Open(dir string) (*Runtime, error) {
	if err := os.MkdirAll(dir, 0700); err != nil {
		return nil, err
	}
	lock := flock.New(filepath.Join(dir, "instance.lock"))
	ok, err := lock.TryLock()
	if err != nil {
		return nil, err
	}
	if !ok {
		return nil, errors.New("data directory already in use")
	}
	r := &Runtime{lock: lock, input: make(chan envelope, 64), durable: make(chan envelope, 64),
		results: make(chan envelope, 64), done: make(chan struct{})}
	success := false
	defer func() {
		if !success {
			r.closeDB()
		}
	}()
	r.journal, err = OpenDB(filepath.Join(dir, "journal.db"))
	if err != nil {
		return nil, err
	}
	r.views, err = OpenDB(filepath.Join(dir, "views.db"))
	if err != nil {
		return nil, err
	}
	if _, err = r.journal.Exec(`CREATE TABLE IF NOT EXISTS commands(
        seq INTEGER PRIMARY KEY,payload TEXT NOT NULL)`); err != nil {
		return nil, err
	}
	if _, err = r.views.Exec(`CREATE TABLE IF NOT EXISTS projection(
        id INTEGER PRIMARY KEY CHECK(id=1),seq INTEGER NOT NULL,payload TEXT NOT NULL);
        CREATE TABLE IF NOT EXISTS results(
        seq INTEGER PRIMARY KEY,account TEXT NOT NULL,key TEXT NOT NULL,payload TEXT NOT NULL)`); err != nil {
		return nil, err
	}
	// 启动时重放全部输入；教学版清空可重建的 views，不清空 journal/auth。
	if _, err = r.views.Exec(`DELETE FROM projection; DELETE FROM results`); err != nil {
		return nil, err
	}
	e := core.New()
	rows, err := r.journal.Query(`SELECT seq,payload FROM commands ORDER BY seq`)
	if err != nil {
		return nil, err
	}
	for rows.Next() {
		var seq int64
		var raw string
		var c core.Command
		if err = rows.Scan(&seq, &raw); err != nil {
			break
		}
		if err = json.Unmarshal([]byte(raw), &c); err != nil {
			break
		}
		if c.Seq != seq || seq != r.last+1 {
			err = errors.New("invalid journal sequence")
			break
		}
		result := e.Apply(c)
		if err = r.project(envelope{command: c, result: result, state: e.Snapshot()}); err != nil {
			break
		}
		r.last = seq
	}
	if err == nil {
		err = rows.Err()
	}
	rows.Close()
	if err != nil {
		return nil, err
	}
	if r.last == 0 {
		if err = r.project(envelope{state: e.Snapshot()}); err != nil {
			return nil, err
		}
	}
	go r.write()
	go r.run(e)
	go r.consume()
	success = true
	return r, nil
}

func (r *Runtime) Submit(ctx context.Context, c core.Command) (core.Result, error) {
	// 序号不信任客户端；摘要只包括业务内容，不包括每次重试的日志位置。
	c.Seq = 0
	c.Hash = ""
	raw, err := json.Marshal(c)
	if err != nil {
		return core.Result{}, err
	}
	sum := sha256.Sum256(raw)
	c.Hash = hex.EncodeToString(sum[:])
	msg := envelope{command: c, reply: make(chan answer, 1)}
	select {
	case <-ctx.Done():
		return core.Result{}, ctx.Err()
	default:
	}
	select {
	case r.input <- msg:
	default:
		return core.Result{}, errors.New("OVERLOADED")
	}
	select {
	case a := <-msg.reply:
		return a.result, a.err
	case <-ctx.Done():
		return core.Result{}, errors.New("RESULT_UNKNOWN")
	}
}

func (r *Runtime) write() {
	defer close(r.durable)
	var failed error
	for msg := range r.input {
		if failed != nil {
			msg.reply <- answer{err: failed}
			continue
		}
		if r.last == int64(1<<63-1) {
			failed = errors.New("sequence exhausted")
			msg.reply <- answer{err: failed}
			continue
		}
		msg.command.Seq = r.last + 1
		raw, err := json.Marshal(msg.command)
		var tx *sql.Tx
		if err == nil {
			tx, err = r.journal.Begin()
		}
		if err == nil {
			_, err = tx.Exec(`INSERT INTO commands(seq,payload) VALUES(?,?)`, msg.command.Seq, string(raw))
			if err == nil {
				err = tx.Commit()
			} else {
				tx.Rollback()
			}
		}
		if err != nil {
			failed = fmt.Errorf("journal unavailable: %w", err)
			msg.reply <- answer{err: failed}
			continue
		}
		r.last = msg.command.Seq
		r.durable <- msg // Commit 成功后，才允许修改核心业务状态。
	}
}

func (r *Runtime) run(e *core.Engine) {
	defer close(r.results)
	for msg := range r.durable {
		msg.result = e.Apply(msg.command)
		msg.state = e.Snapshot()
		r.results <- msg
	}
}

func (r *Runtime) project(msg envelope) error {
	state, err := json.Marshal(msg.state)
	if err != nil {
		return err
	}
	result, err := json.Marshal(msg.result)
	if err != nil {
		return err
	}
	tx, err := r.views.Begin()
	if err != nil {
		return err
	}
	defer tx.Rollback()
	if _, err = tx.Exec(`INSERT INTO projection(id,seq,payload) VALUES(1,?,?)
        ON CONFLICT(id) DO UPDATE SET seq=excluded.seq,payload=excluded.payload`, msg.command.Seq, string(state)); err != nil {
		return err
	}
	if msg.command.Seq > 0 {
		if _, err = tx.Exec(`INSERT INTO results(seq,account,key,payload) VALUES(?,?,?,?)`,
			msg.command.Seq, msg.command.Account, msg.command.Key, string(result)); err != nil {
			return err
		}
	}
	return tx.Commit()
}

func (r *Runtime) consume() {
	defer close(r.done)
	var failed error
	for msg := range r.results {
		if failed == nil {
			failed = r.project(msg)
		}
		// 投影失败后继续回未知结果，但停止发布新视图；重启从权威日志重建。
		if failed != nil {
			msg.reply <- answer{err: errors.New("RESULT_UNKNOWN")}
		} else {
			msg.reply <- answer{result: msg.result}
		}
	}
}

func (r *Runtime) State(ctx context.Context) (core.State, error) {
	var raw string
	var s core.State
	err := r.views.QueryRowContext(ctx, `SELECT payload FROM projection WHERE id=1`).Scan(&raw)
	if err != nil {
		return s, err
	}
	err = json.Unmarshal([]byte(raw), &s)
	return s, err
}

func (r *Runtime) closeDB() {
	if r.views != nil {
		r.views.Close()
	}
	if r.journal != nil {
		r.journal.Close()
	}
	if r.lock != nil {
		r.lock.Unlock()
	}
}

// Close 必须在 HTTP Shutdown 等待所有 handler 结束之后调用，不能与 Submit 并发。
func (r *Runtime) Close() { close(r.input); <-r.done; r.closeDB() }
```


### 8.3 按顺序理解五个函数

- Open：取得目录锁，开库建表，按 Seq 重放历史，再启动三个 worker。未恢复完不监听 HTTP。
- Submit：固定摘要，尝试入有界 input，发送后只等自己的 reply。reply 容量1，客户端不等了也不会堵死回包。
- write：分配连续 Seq，事务 INSERT+Commit，成功才发到 durable。已提交不能因浏览器取消等待就删掉。
- run：唯一持有 Engine；Apply 后得到独立 Snapshot，交给外围 JSON/SQL。
- consume：将视图与结果置于同一事务；状态序号也一起提交。Close 关闭接入后按 channel 方向排空。

客户端取消不等于撤单。一旦入队，其后取消等待仍可能执行，返回 RESULT_UNKNOWN；不能替它生成新 key。日志提交报错也可能是未知提交边界，教学版封住 writer 后续写入并保留原键确认能力。

### 8.4 教学版有意保留的限制

每条命令复制/写出整个状态，数据一多会很慢；日志单条提交没有批处理；启动重放会清空并全量重建 views；没有 dataset/版本、防投影故障的完整 fail-fast、全流程 inflight 或关闭超时治理。writer 失败后不再接受新日志，投影失败后返回未知，但教学进程没有最终版完整健康退场机制。

因此它适合小数据学习，不是最终项目的性能实现。**不要为了“优化”将 Snapshot 放到 HTTP goroutine 直接读 Engine。**正确升级是 core 产出增量副本，外围独立维护查询投影。

**本章验收：**`gofmt -w runtime`、`go test ./...` 都通过；还未启动服务器，不应出现业务数据目录。若“undefined core”先检查模块名和 import；SQL 错误先读完整原始报错。


<a id="chapter-09"></a>
## 9. 写注册、登录、会话和管理员身份

### 9.1 分清四个概念

注册建立身份；登录验证密码；会话让后续请求知道“是谁”；权限决定“他能做什么”。管理员也是一个用户，区别是后端数据库记录 role=ADMIN，而不是前端传个 role 就能提权。

密码不存明文，也不自己拿普通 SHA256 哈希密码。bcrypt 专门做带盐且有计算成本的密码摘要；SHA256 在这里用于随机会话 token 的索引摘要。浏览器拿随机 token 放 Cookie，数据库只保存其 hash，随机性来自 crypto/rand。

HttpOnly 让页面 JavaScript 不能读取会话 Cookie；CSRF token 则由登录响应返回，后续写操作附在请求头。Origin 校验检查网页来自哪里，CSRF 检查网页是否持有会话配套的写凭证，RBAC 检查账号角色；三者分工不同。


下面是 `auth/auth.go` 的**完整文件**：

```go
package auth

import (
	"context"
	"crypto/rand"
	"crypto/sha256"
	"database/sql"
	"encoding/hex"
	"errors"
	"net/mail"
	"strings"
	"time"

	"golang.org/x/crypto/bcrypt"
)

type User struct {
	ID       string `json:"id"`
	Email    string `json:"email"`
	Role     string `json:"role"`
	Disabled bool   `json:"disabled"`
}
type Store struct{ DB *sql.DB }

func New(db *sql.DB) (*Store, error) {
	_, err := db.Exec(`CREATE TABLE IF NOT EXISTS users(
        id TEXT PRIMARY KEY,email TEXT NOT NULL UNIQUE,hash TEXT NOT NULL,
        role TEXT NOT NULL CHECK(role IN ('USER','ADMIN')),disabled INTEGER NOT NULL DEFAULT 0);
        CREATE TABLE IF NOT EXISTS sessions(
        hash TEXT PRIMARY KEY,user_id TEXT NOT NULL REFERENCES users(id),
        csrf TEXT NOT NULL,expires INTEGER NOT NULL)`)
	return &Store{db}, err
}

func token() (string, error) {
	b := make([]byte, 32)
	_, err := rand.Read(b)
	return hex.EncodeToString(b), err
}
func hash(s string) string { n := sha256.Sum256([]byte(s)); return hex.EncodeToString(n[:]) }
func email(s string) (string, error) {
	s = strings.ToLower(strings.TrimSpace(s))
	a, err := mail.ParseAddress(s)
	if err != nil || a.Address != s || !strings.Contains(s, "@") {
		return "", errors.New("invalid email")
	}
	return s, nil
}

// Create 的 role 来自可信调用者，公开注册 handler 必须固定 USER。
func (s *Store) Create(ctx context.Context, address, password, role string) (User, error) {
	var u User
	address, err := email(address)
	if err != nil {
		return u, err
	}
	if len(password) < 12 || len(password) > 72 {
		return u, errors.New("password requires 12–72 bytes")
	}
	if role != "USER" && role != "ADMIN" {
		return u, errors.New("invalid role")
	}
	digest, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
	if err != nil {
		return u, err
	}
	id, err := token()
	if err != nil {
		return u, err
	}
	u = User{id, address, role, false}
	_, err = s.DB.ExecContext(ctx, `INSERT INTO users(id,email,hash,role) VALUES(?,?,?,?)`, id, address, string(digest), role)
	return u, err
}

func (s *Store) Bootstrap(ctx context.Context, address, password string) (User, error) {
	var u User
	address, err := email(address)
	if err != nil {
		return u, err
	}
	err = s.DB.QueryRowContext(ctx, `SELECT id,email,role,disabled FROM users WHERE email=?`, address).
		Scan(&u.ID, &u.Email, &u.Role, &u.Disabled)
	if err == nil {
		if u.Role != "ADMIN" || u.Disabled {
			return u, errors.New("existing account is not an active admin")
		}
		return u, nil // 不把原有普通用户提权，不改已有管理员密码。
	}
	if !errors.Is(err, sql.ErrNoRows) {
		return u, err
	}
	return s.Create(ctx, address, password, "ADMIN")
}

func (s *Store) Login(ctx context.Context, address, password string) (User, error) {
	var u User
	var digest string
	address, err := email(address)
	if err != nil {
		return u, errors.New("invalid credentials")
	}
	err = s.DB.QueryRowContext(ctx, `SELECT id,email,role,disabled,hash FROM users WHERE email=?`, address).
		Scan(&u.ID, &u.Email, &u.Role, &u.Disabled, &digest)
	if err != nil {
		return u, errors.New("invalid credentials or auth unavailable")
	}
	if u.Disabled || bcrypt.CompareHashAndPassword([]byte(digest), []byte(password)) != nil {
		return User{}, errors.New("invalid credentials")
	}
	return u, nil
}

func (s *Store) NewSession(ctx context.Context, user string) (string, string, error) {
	t, err := token()
	if err != nil {
		return "", "", err
	}
	csrf, err := token()
	if err != nil {
		return "", "", err
	}
	_, err = s.DB.ExecContext(ctx, `INSERT INTO sessions(hash,user_id,csrf,expires) VALUES(?,?,?,?)`,
		hash(t), user, csrf, time.Now().Add(24*time.Hour).Unix())
	return t, csrf, err
}

func (s *Store) Session(ctx context.Context, t string) (User, string, error) {
	var u User
	var csrf string
	err := s.DB.QueryRowContext(ctx, `SELECT u.id,u.email,u.role,u.disabled,s.csrf
        FROM sessions s JOIN users u ON u.id=s.user_id
        WHERE s.hash=? AND s.expires>? AND u.disabled=0`, hash(t), time.Now().Unix()).
		Scan(&u.ID, &u.Email, &u.Role, &u.Disabled, &csrf)
	return u, csrf, err
}
func (s *Store) Logout(ctx context.Context, t string) error {
	_, err := s.DB.ExecContext(ctx, `DELETE FROM sessions WHERE hash=?`, hash(t))
	return err
}

// Disable 将状态变更与注销所有旧会话放在同一事务。
func (s *Store) Disable(ctx context.Context, id string, disabled bool) error {
	tx, err := s.DB.BeginTx(ctx, nil)
	if err != nil {
		return err
	}
	defer tx.Rollback()
	res, err := tx.ExecContext(ctx, `UPDATE users SET disabled=? WHERE id=? AND role='USER'`, disabled, id)
	if err != nil {
		return err
	}
	n, err := res.RowsAffected()
	if err != nil {
		return err
	}
	if n != 1 {
		return errors.New("user not found or is admin")
	}
	if disabled {
		if _, err = tx.ExecContext(ctx, `DELETE FROM sessions WHERE user_id=?`, id); err != nil {
			return err
		}
	}
	return tx.Commit()
}
```


按 Create→Login→NewSession→Session→Disable 理解。Create 只管理身份，不直接改交易余额；资金必须进入 CREDIT 日志。密码长度按 UTF-8 **字节**算，12–72；中文字符不一定一字一字节。

会话有效期是创建后24小时，不访问续期。Disable 更新用户并删除全部旧会话，在一个事务里完成；重新启用仍需重新登录，不能复活删除的 token。停用不是自动撤单，已存在挂单仍可能成交。

Bootstrap 只能创建新管理员或返回已有管理员，不能把同邮箱普通用户提升权限，也不覆盖已有管理员密码。教学版先使用邮箱管理员与长密码；最终 Windows 指定短密码模式在第21章单独解释。

教学版将部分认证数据库故障合并为认证失败，最终版需区分 401 与 AUTH_UNAVAILABLE，并补认证限流、审计和更完整邮箱校验。创建临时用户测试也会做 bcrypt，测试稍慢不是撮合线程被阻塞。

**本章验收：**`gofmt -w auth`、`go test ./...` 通过。不要输出 digest/Cookie/CSRF 到日志来“检查是否成功”，下一章通过真实登录接口验证。


<a id="chapter-10"></a>
## 10. 写 HTTP 接口与权限校验

### 10.1 先列清楚接口

| 教学接口 | 身份要求 | 用途 |
| --- | --- | --- |
| GET /health | 无 | 初步健康检查 |
| POST /api/auth/register、/login | 无；检查 Origin | 注册/登录 |
| GET /api/auth/me | 登录 | 页面刷新恢复身份和CSRF |
| POST /api/auth/logout | 登录+CSRF | 退出当前会话 |
| GET /api/state | 登录 | 仅当前账户的订单/余额 |
| POST /api/orders | 登录+CSRF+幂等键 | 限价GTC |
| POST /api/orders/{id}/cancel | 登录+CSRF+幂等键 | 撤自己的订单 |
| GET /api/admin/users | ADMIN | 用户列表 |
| PATCH /api/admin/users/{id} | ADMIN+CSRF | 停用/启用普通用户 |
| POST /api/admin/credits | ADMIN+CSRF+幂等键 | 正向增加模拟资金 |

GET /api/state 不能把全体用户余额返回出去。即使页面不显示，数据已经发给浏览器就泄露了。核心 RESULT 只带本次必要交易结果；State 是供投影使用的全量内部副本，读取 handler 必须过滤。

新建下面文件。`protected` 统一做 Cookie/Origin/角色/CSRF 检查，但“订单是否属于当前用户”仍由核心 CANCEL 检查。注册请求体不提供 Role 字段，严格 JSON 解码会拒绝客户端自行塞入未知字段。


下面是 `transport/http.go` 的**完整文件**：

```go
package transport

import (
	"context"
	"crypto/subtle"
	"encoding/json"
	"errors"
	"io"
	"net/http"
	"regexp"

	"exchangelearn/auth"
	"exchangelearn/core"
	rt "exchangelearn/runtime"
)

type Server struct {
	Auth    *auth.Store
	Runtime *rt.Runtime
	Origin  string
}

func write(w http.ResponseWriter, status int, value any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(value)
}
func fail(w http.ResponseWriter, status int, message string) {
	write(w, status, map[string]string{"error": message})
}
func read(w http.ResponseWriter, r *http.Request, v any) bool {
	r.Body = http.MaxBytesReader(w, r.Body, 16<<10)
	decoder := json.NewDecoder(r.Body)
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(v); err != nil {
		fail(w, 400, "invalid JSON")
		return false
	}
	var extra any
	if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) {
		fail(w, 400, "only one JSON value allowed")
		return false
	}
	return true
}
func (s *Server) origin(w http.ResponseWriter, r *http.Request) bool {
	if o := r.Header.Get("Origin"); o != "" && o != s.Origin {
		fail(w, 403, "origin rejected")
		return false
	}
	return true
}

func (s *Server) protected(admin bool, next func(http.ResponseWriter, *http.Request, auth.User)) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if !s.origin(w, r) {
			return
		}
		cookie, err := r.Cookie("exchange_session")
		if err != nil {
			fail(w, 401, "login required")
			return
		}
		u, csrf, err := s.Auth.Session(r.Context(), cookie.Value)
		if err != nil {
			fail(w, 401, "session unavailable")
			return
		}
		if admin && u.Role != "ADMIN" {
			fail(w, 403, "admin required")
			return
		}
		if r.Method != "GET" && subtle.ConstantTimeCompare([]byte(r.Header.Get("X-CSRF-Token")), []byte(csrf)) != 1 {
			fail(w, 403, "csrf rejected")
			return
		}
		next(w, r, u)
	}
}

// Fund 固定幂等键可修复身份成功但初始化资金中断的情况。
func (s *Server) Fund(ctx context.Context, id string) error {
	for _, v := range []struct{ asset, amount string }{{"ETH", "10"}, {"USDT", "100000"}} {
		result, err := s.Runtime.Submit(ctx, core.Command{Account: id, Kind: "CREDIT",
			Key: "system.initial." + v.asset, Asset: v.asset, Amount: v.amount})
		if err != nil {
			return err
		}
		if result.Code != "" {
			return errors.New(result.Code)
		}
	}
	return nil
}

func (s *Server) login(register bool) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if !s.origin(w, r) {
			return
		}
		var body struct {
			Email    string `json:"email"`
			Password string `json:"password"`
		}
		if !read(w, r, &body) {
			return
		}
		var u auth.User
		var err error
		if register {
			u, err = s.Auth.Create(r.Context(), body.Email, body.Password, "USER")
		} else {
			u, err = s.Auth.Login(r.Context(), body.Email, body.Password)
		}
		if err != nil {
			fail(w, 400, "registration or login failed")
			return
		}
		if err = s.Fund(r.Context(), u.ID); err != nil {
			fail(w, 503, "funding incomplete; retry login")
			return
		}
		token, csrf, err := s.Auth.NewSession(r.Context(), u.ID)
		if err != nil {
			fail(w, 503, "session unavailable")
			return
		}
		http.SetCookie(w, &http.Cookie{Name: "exchange_session", Value: token, Path: "/",
			HttpOnly: true, SameSite: http.SameSiteStrictMode, MaxAge: 86400})
		write(w, 200, map[string]any{"user": u, "csrf": csrf})
	}
}

var keyPattern = regexp.MustCompile(`^[A-Za-z0-9_.-]{8,128}$`)

func key(w http.ResponseWriter, r *http.Request) string {
	k := r.Header.Get("Idempotency-Key")
	if !keyPattern.MatchString(k) || len(k) >= 7 && k[:7] == "system." {
		fail(w, 400, "invalid idempotency key")
		return ""
	}
	return k
}

func (s *Server) submit(w http.ResponseWriter, r *http.Request, c core.Command) {
	result, err := s.Runtime.Submit(r.Context(), c)
	if err != nil {
		fail(w, 503, "RESULT_UNKNOWN or unavailable; retry original key/body")
		return
	}
	status := 200
	if result.Code != "" {
		status = 422
	}
	write(w, status, result)
}

func (s *Server) Handler() http.Handler {
	m := http.NewServeMux()
	m.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) { write(w, 200, map[string]string{"status": "ok"}) })
	m.HandleFunc("POST /api/auth/register", s.login(true))
	m.HandleFunc("POST /api/auth/login", s.login(false))
	m.HandleFunc("GET /api/auth/me", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		c, _ := r.Cookie("exchange_session")
		_, csrf, err := s.Auth.Session(r.Context(), c.Value)
		if err != nil {
			fail(w, 503, "auth unavailable")
			return
		}
		write(w, 200, map[string]any{"user": u, "csrf": csrf})
	}))
	m.HandleFunc("POST /api/auth/logout", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		c, _ := r.Cookie("exchange_session")
		if err := s.Auth.Logout(r.Context(), c.Value); err != nil {
			fail(w, 503, "logout failed")
			return
		}
		http.SetCookie(w, &http.Cookie{Name: "exchange_session", Value: "", Path: "/", HttpOnly: true,
			SameSite: http.SameSiteStrictMode, MaxAge: -1})
		write(w, 200, map[string]bool{"ok": true})
	}))
	m.HandleFunc("GET /api/state", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		state, err := s.Runtime.State(r.Context())
		if err != nil {
			fail(w, 503, "query failed")
			return
		}
		visible := core.State{Orders: []core.Order{}, Balances: []core.Balance{}}
		for _, o := range state.Orders {
			if o.Account == u.ID {
				visible.Orders = append(visible.Orders, o)
			}
		}
		for _, b := range state.Balances {
			if b.Account == u.ID {
				visible.Balances = append(visible.Balances, b)
			}
		}
		write(w, 200, visible)
	}))
	m.HandleFunc("POST /api/orders", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		k := key(w, r)
		if k == "" {
			return
		}
		var body struct {
			Side     string `json:"side"`
			Price    string `json:"price"`
			Quantity string `json:"quantity"`
		}
		if !read(w, r, &body) {
			return
		}
		s.submit(w, r, core.Command{Account: u.ID, Key: k, Kind: "PLACE", Side: body.Side, Price: body.Price, Quantity: body.Quantity})
	}))
	m.HandleFunc("POST /api/orders/{id}/cancel", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		k := key(w, r)
		if k == "" {
			return
		}
		s.submit(w, r, core.Command{Account: u.ID, Key: k, Kind: "CANCEL", OrderID: r.PathValue("id")})
	}))
	m.HandleFunc("GET /api/admin/users", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		rows, err := s.Auth.DB.QueryContext(r.Context(), `SELECT id,email,role,disabled FROM users ORDER BY rowid`)
		if err != nil {
			fail(w, 503, "query failed")
			return
		}
		defer rows.Close()
		users := []auth.User{}
		for rows.Next() {
			var v auth.User
			if err = rows.Scan(&v.ID, &v.Email, &v.Role, &v.Disabled); err != nil {
				fail(w, 503, "query failed")
				return
			}
			users = append(users, v)
		}
		if rows.Err() != nil {
			fail(w, 503, "query failed")
			return
		}
		write(w, 200, users)
	}))
	m.HandleFunc("PATCH /api/admin/users/{id}", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		var body struct {
			Disabled *bool `json:"disabled"`
		}
		if !read(w, r, &body) {
			return
		}
		if body.Disabled == nil {
			fail(w, 400, "disabled required")
			return
		}
		if err := s.Auth.Disable(r.Context(), r.PathValue("id"), *body.Disabled); err != nil {
			fail(w, 400, "update failed")
			return
		}
		write(w, 200, map[string]bool{"ok": true})
	}))
	m.HandleFunc("POST /api/admin/credits", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) {
		k := key(w, r)
		if k == "" {
			return
		}
		var body struct {
			Account string `json:"account"`
			Asset   string `json:"asset"`
			Amount  string `json:"amount"`
			Reason  string `json:"reason"`
		}
		if !read(w, r, &body) {
			return
		}
		var exists int
		if body.Reason == "" || s.Auth.DB.QueryRowContext(r.Context(), `SELECT 1 FROM users WHERE id=?`, body.Account).Scan(&exists) != nil {
			fail(w, 400, "target/reason invalid")
			return
		}
		// 操作者、原因也进入摘要和日志；最终版再增加独立执行审计表。
		s.submit(w, r, core.Command{Account: body.Account, Key: "admin." + u.ID + "." + k,
			Kind: "CREDIT", Asset: body.Asset, Amount: body.Amount, Actor: u.ID, Reason: body.Reason})
	}))
	m.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) { fail(w, 404, "route not found") })
	m.Handle("/", http.FileServer(http.Dir("frontend/dist")))
	return m
}
```


### 10.2 初始资金为什么要使用固定键

注册身份提交后，ETH 注资成功但 USDT 注资失败是可能的，因为 auth、journal 不在一个跨库事务里。不能假装一切原子完成。

Fund 每次使用同一账号的 system.initial.ETH/USDT。登录时再调用：已完成那笔只返回首次结果，未完成那笔补齐。因此不能把 Key 改成每次随机值，否则每次登录都送钱。

管理员注资的目标 Account 与操作者不同，key 加 admin.<操作者ID> 前缀，Actor/Reason 也进入摘要和日志。教学版没有独立执行审计表，最终版要补，让操作原因、执行结果与水位能查询。

### 10.3 严格输入比“能解析”多一层

限制16KB请求体，拒绝未知字段，拒绝一段正文含两个JSON。下单 Account 只从会话取得，前端只传 side/price/quantity。幂等键限定字符与长度，system.前缀留给内部初始化。

本地 teaching 的 Cookie 不带 Secure，是因为使用 HTTP。云端 HTTPS 必须启用 Secure，后面最终配置支持此开关。教学 /health 仅表示接口可响应，最终项目分 live 与 ready，并让后台存储故障反映到 ready。

**本章验收：**`gofmt -w transport`、`go test ./...`。先不用手动构造 Cookie；前端会自动管理它，13章集成测试再直接检验 HTTP 权限。


<a id="chapter-11"></a>
## 11. 把后端装配起来

现在替换第3章的 `cmd/server/main.go` 为下方完整文件。装配顺序是 runtime恢复→auth→管理员初始化→HTTP；启动错误必须退出，不能打印“成功”继续假跑。


下面是 `cmd/server/main.go` 的**完整文件**：

```go
package main

import (
	"context"
	"errors"
	"log"
	"net/http"
	"os"
	"os/signal"
	"path/filepath"
	"syscall"
	"time"

	"exchangelearn/auth"
	rt "exchangelearn/runtime"
	"exchangelearn/transport"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
func run() error {
	runtime, err := rt.Open("data")
	if err != nil {
		return err
	}
	defer runtime.Close()
	db, err := rt.OpenDB(filepath.Join("data", "auth.db"))
	if err != nil {
		return err
	}
	defer db.Close()
	users, err := auth.New(db)
	if err != nil {
		return err
	}
	server := &transport.Server{Auth: users, Runtime: runtime, Origin: "http://127.0.0.1:5173"}
	if email := os.Getenv("LEARN_ADMIN_EMAIL"); email != "" {
		u, err := users.Bootstrap(context.Background(), email, os.Getenv("LEARN_ADMIN_PASSWORD"))
		if err != nil {
			return err
		}
		if err = server.Fund(context.Background(), u.ID); err != nil {
			return err
		}
	}
	httpServer := &http.Server{Addr: "127.0.0.1:8080", Handler: server.Handler(),
		ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 15 * time.Second}
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	done := make(chan error, 1)
	go func() { done <- httpServer.ListenAndServe() }()
	log.Print("backend http://127.0.0.1:8080; frontend http://127.0.0.1:5173")
	select {
	case err = <-done:
		if !errors.Is(err, http.ErrServerClosed) {
			return err
		}
	case <-ctx.Done():
		// 教学版先 Shutdown 所有 HTTP handler，再排空 runtime，满足 Close 的前提。
		// 超时直接退出进程，不在仍有 handler Submit 时 close(input)。
		shutdown, cancel := context.WithTimeout(context.Background(), 20*time.Second)
		defer cancel()
		if err = httpServer.Shutdown(shutdown); err != nil {
			log.Print(err)
			os.Exit(1)
		}
	}
	return nil
}
```


根目录 PowerShell 中执行以下命令，演示密码只用于你自己的练习目录：

```powershell
$env:LEARN_ADMIN_EMAIL="admin@example.com"
$env:LEARN_ADMIN_PASSWORD="learn-admin-password"
go mod tidy
gofmt -w core runtime auth transport cmd
go test ./...
go run ./cmd/server
```

新窗口执行 `Invoke-RestMethod http://127.0.0.1:8080/health` 应返回 ok。第一次启动出现 `data/journal.db`、`data/views.db`、`data/auth.db`、锁文件及可能的 WAL/SHM。别手工编辑运行中的库。

终端环境变量只影响该终端启动的子程序；重开终端要重新设置。LEARN_ 是教学版参数，最终服务使用 EXCHANGE_，两者不能混用。

关闭时先 Shutdown HTTP，确保没有 handler 再 Submit，才关闭 input 和数据库。这是教学 Close 的明确调用前提。最终版支持并发关闭受理、排空、期限和故障退场，不要把教学版 Close 拷到最终运行时。

练习：关闭再启动后，用同管理员登录，不应得到新ID或重复初始资金；普通账号与订单也保留。管理员同邮箱已存在时新环境密码不会覆盖原密码。


<a id="chapter-12"></a>
## 12. 从空目录写 React 交易页面

### 12.1 浏览器需要另一套语言和构建工具

HTML描述页面结构，CSS描述外观，JavaScript描述交互。TypeScript 在 JavaScript 上加编译期类型检查；浏览器最终运行编译后的 JavaScript。React 把页面写成组件，Vite负责开发服务器与打包。Go不会直接执行TSX。

不要用 create-vite@latest 生成不同版本的模板。下面从空 frontend 目录明确创建文件，固定本项目的版本。


下面是 `frontend/package.json` 的**完整文件**：

```json
{
  "name": "exchangelearn-web",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc -b && vite build"
  },
  "dependencies": {
    "react": "19.1.0",
    "react-dom": "19.1.0"
  },
  "devDependencies": {
    "@types/react": "19.1.0",
    "@types/react-dom": "19.1.1",
    "@vitejs/plugin-react": "4.4.1",
    "typescript": "5.8.3",
    "vite": "6.4.4"
  }
}
```


下面是 `frontend/tsconfig.json` 的**完整文件**：

```json
{
  "compilerOptions": {
    "target": "ES2022", "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext", "moduleResolution": "Bundler", "jsx": "react-jsx",
    "strict": true, "skipLibCheck": true, "noEmit": true,
    "allowImportingTsExtensions": true, "esModuleInterop": true
  },
  "include": ["src"]
}
```


下面是 `frontend/vite.config.ts` 的**完整文件**：

```typescript
// 开发代理统一同源 /api 与 WS，Cookie/CSRF 不依赖跨域配置；生产由 Go 直接提供 dist。
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      "/api": { target: "http://127.0.0.1:8080", ws: true },
      "/health": "http://127.0.0.1:8080",
    },
  },
});
```


下面是 `frontend/index.html` 的**完整文件**：

```html
<!doctype html>
<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>模拟交易练习</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>
```


下面是 `frontend/src/main.tsx` 的**完整文件**：

```tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
ReactDOM.createRoot(document.getElementById("root")!).render(<React.StrictMode><App /></React.StrictMode>);
```


在根目录执行：

```powershell
npm --prefix frontend install
```

第一次还没有 package-lock.json，所以用 install 创建锁文件。之后复现同版环境用 `npm --prefix frontend ci`；ci 要求已有且与 package.json 一致的锁文件，会重建 node_modules。不要丢掉 lock 文件，也别每次升级依赖到 latest。

代理的作用：浏览器请求 http://127.0.0.1:5173/api/orders，Vite将它转给8080后端。这样浏览器视角是同源，Cookie不用跨域配置。只在开发存在两个服务，部署时Go直接提供dist。

### 12.2 先认识组件中的五种写法

- `useState` 保存界面状态，set函数更新后React重新渲染；不是可变全局变量。
- `useEffect` 在组件挂载/依赖改变时做外部工作，WS和定时器需要返回清理函数。
- `async/await` 等HTTP返回；等待不会让后端撤销业务。
- `{list.map(...)}` 把数组转成一组页面元素，每项用稳定id作key。
- `FormData` 读取表单字段，金额保持 string，不能parseFloat后再提交。

下面页面包含注册、登录、当前资金、下单、撤单、退出、管理员停用与注资。先保证行为正确，最后再增加最终项目的实时行情、分页、GSAP与响应式布局。


下面是 `frontend/src/App.tsx` 的**完整文件**：

```tsx
import { FormEvent, useEffect, useState } from "react";
import "./style.css";

type User = { id: string; email: string; role: string; disabled: boolean };
type Auth = { user: User; csrf: string };
type Order = { id: string; side: string; price: string; remaining: string; status: string };
type State = { orders: Order[]; balances: { asset: string; available: string; frozen: string }[] };
type Pending = { account: string; path: string; key: string; body: unknown };

// 422 是核心已经确定的拒绝；其他异常保留原写请求供确认。
class RequestError extends Error {
  constructor(message: string, public known: boolean) { super(message); }
}
async function call<T>(path: string, csrf = "", method = "GET", body?: unknown, key?: string): Promise<T> {
  const response = await fetch("/api" + path, {
    method, credentials: "same-origin",
    headers: { "Content-Type": "application/json", ...(csrf ? { "X-CSRF-Token": csrf } : {}),
      ...(key ? { "Idempotency-Key": key } : {}) },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const data = await response.json();
  if (!response.ok) throw new RequestError(data.code || data.error || "请求失败", response.status === 422);
  return data;
}

export default function App() {
  const [auth, setAuth] = useState<Auth | null>(null);
  const [state, setState] = useState<State>({ orders: [], balances: [] });
  const [users, setUsers] = useState<User[]>([]);
  const [message, setMessage] = useState("");
  const [busy, setBusy] = useState(false);
  const [pending, setPending] = useState<Pending | null>(null);

  // 教学版不自动信任旧记录：只允许同一账号明确点击确认。
  // 完整版 pending.ts 还验证版本、数据集、操作和每个字段。
  useEffect(() => {
    try {
      const raw = sessionStorage.getItem("learn.pending");
      if (raw) {
        const p = JSON.parse(raw);
        if (typeof p.account !== "string" || typeof p.path !== "string" || typeof p.key !== "string")
          throw new Error("待确认记录格式错误");
        setPending(p);
      }
    } catch { setMessage("待确认记录无法读取，请先核对原订单"); }
    call<Auth>("/auth/me").then(setAuth).catch(() => {});
  }, []);

  async function refresh(a: Auth) {
    setState(await call<State>("/state"));
    if (a.user.role === "ADMIN") setUsers(await call<User[]>("/admin/users"));
  }
  useEffect(() => { if (auth) refresh(auth).catch(e => setMessage(String(e))); }, [auth]);

  async function login(e: FormEvent<HTMLFormElement>) {
    e.preventDefault(); setBusy(true);
    const form = new FormData(e.currentTarget);
    try {
      const a = await call<Auth>(form.get("mode") === "register" ? "/auth/register" : "/auth/login", "", "POST",
        { email: String(form.get("email")), password: String(form.get("password")) });
      setAuth(a); setMessage("已登录");
    } catch (e) { setMessage(String(e)); } finally { setBusy(false); }
  }

  async function execute(p: Pending) {
    if (!auth || p.account !== auth.user.id) throw new Error("请登录原账号确认");
    try {
      await call(p.path, auth.csrf, "POST", p.body, p.key);
    } catch (e) {
      if (e instanceof RequestError && e.known) {
        sessionStorage.removeItem("learn.pending"); setPending(null);
      }
      throw e;
    }
    sessionStorage.removeItem("learn.pending"); setPending(null);
    setMessage("操作已确认"); await refresh(auth);
  }
  async function write(path: string, body?: unknown) {
    if (!auth || pending || sessionStorage.getItem("learn.pending")) throw new Error("先确认之前的请求");
    const p: Pending = { account: auth.user.id, path, body, key: crypto.randomUUID() };
    sessionStorage.setItem("learn.pending", JSON.stringify(p)); // 保存失败就不会发送。
    setPending(p); await execute(p);
  }
  async function action(fn: () => Promise<void>) {
    setBusy(true);
    try { await fn(); } catch (e) { setMessage(String(e)); } finally { setBusy(false); }
  }
  function place(e: FormEvent<HTMLFormElement>) {
    e.preventDefault(); const f = new FormData(e.currentTarget);
    void action(() => write("/orders", { side: String(f.get("side")), price: String(f.get("price")), quantity: String(f.get("quantity")) }));
  }
  function credit(e: FormEvent<HTMLFormElement>) {
    e.preventDefault(); const f = new FormData(e.currentTarget);
    void action(() => write("/admin/credits", { account: String(f.get("account")), asset: String(f.get("asset")), amount: String(f.get("amount")), reason: String(f.get("reason")) }));
  }

  return <main>
    <h1>ETH / USDT 模拟交易</h1>
    <p role="status">{message}</p>
    {!auth ? <form onSubmit={login}>
      <input name="email" type="email" placeholder="邮箱" aria-label="邮箱" required />
      <input name="password" type="password" placeholder="密码，12–72 字节" aria-label="密码" required />
      <select name="mode" aria-label="登录或注册"><option value="login">登录</option><option value="register">注册</option></select>
      <button disabled={busy}>提交</button>
    </form> : <>
      <p>{auth.user.email} · {auth.user.role}</p>
      <button disabled={busy} onClick={() => void action(async () => {
        await call("/auth/logout", auth.csrf, "POST"); setAuth(null); setState({ orders: [], balances: [] }); setUsers([]);
      })}>退出</button>
      <button disabled={busy} onClick={() => void action(() => refresh(auth))}>刷新</button>
      {pending && <p>有待确认请求 <button disabled={busy || pending.account !== auth.user.id}
        onClick={() => void action(() => execute(pending))}>原键确认</button></p>}
      <h2>资金</h2>
      {state.balances.map(b => <p key={b.asset}>{b.asset} · 可用 {b.available} · 冻结 {b.frozen}</p>)}
      <h2>下限价单</h2>
      <form onSubmit={place}>
        <select name="side" aria-label="方向"><option>BUY</option><option>SELL</option></select>
        <input name="price" placeholder="价格" aria-label="价格" required />
        <input name="quantity" placeholder="数量" aria-label="数量" required />
        <button disabled={busy || !!pending}>下单</button>
      </form>
      <table><thead><tr><th>订单</th><th>方向</th><th>价格</th><th>余量</th><th>状态</th><th>操作</th></tr></thead>
      <tbody>{state.orders.map(o => <tr key={o.id}>
        <td>{o.id}</td><td>{o.side}</td><td>{o.price}</td><td>{o.remaining}</td><td>{o.status}</td>
        <td>{o.remaining !== "0" && <button disabled={busy || !!pending}
          onClick={() => void action(() => write(`/orders/${o.id}/cancel`))}>撤单</button>}</td>
      </tr>)}</tbody></table>
      {auth.user.role === "ADMIN" && <>
        <h2>用户管理</h2>
        {users.map(u => <p key={u.id}>{u.email} · {u.role} · {u.disabled ? "停用" : "启用"}
          {u.role === "USER" && <button disabled={busy} onClick={() => void action(async () => {
            await call(`/admin/users/${u.id}`, auth.csrf, "PATCH", { disabled: !u.disabled }); await refresh(auth);
          })}>{u.disabled ? "启用" : "停用"}</button>}</p>)}
        <form onSubmit={credit}>
          <select name="account" aria-label="目标用户">{users.map(u => <option key={u.id} value={u.id}>{u.email}</option>)}</select>
          <select name="asset" aria-label="资产"><option>USDT</option><option>ETH</option></select>
          <input name="amount" placeholder="增加数量" aria-label="增加数量" required />
          <input name="reason" placeholder="原因" aria-label="原因" required />
          <button disabled={busy || !!pending}>增加模拟资金</button>
        </form>
      </>}
    </>}
  </main>;
}
```


下面是 `frontend/src/style.css` 的**完整文件**：

```css
/* 使用 Carbon 深色体系基础色；无渐变、无圆角。先保证可用，再扩展动画。 */
:root { color: #f4f4f4; background: #161616; font-family: system-ui, sans-serif; }
body { margin: 0; }
main { max-width: 1000px; padding: 24px; margin: auto; }
h1 { font-size: 24px; }
h2 { font-size: 18px; margin-top: 24px; }
form { display: flex; gap: 8px; flex-wrap: wrap; margin: 16px 0; }
input, select, button { font: inherit; border-radius: 0; padding: 8px; }
input, select { background: #262626; color: #f4f4f4; border: 1px solid #8d8d8d; }
button { background: #0f62fe; color: white; border: 0; cursor: pointer; margin-right: 8px; }
button:disabled { opacity: .5; cursor: default; }
:focus-visible { outline: 2px solid white; outline-offset: 2px; }
table { width: 100%; border-collapse: collapse; }
th, td { border-bottom: 1px solid #525252; text-align: left; padding: 8px; }
@media (max-width: 600px) { main { padding: 12px; overflow-x: auto; } input { max-width: 100%; } }
```


### 12.3 为什么这个页面先保存再发下单

write 创建随机幂等键和固定body，先写 sessionStorage，再调用execute。存储失败直接停止发送。断网/异常保留原请求，用户点击“原键确认”只重发同一个path/key/body，不重新读取表单。

422是教学核心确定拒绝，可以移除本次待确认记录；网络错误、会话失效或5xx不能证明此前没执行，继续保留。若删除存储失败也不能谎称记录已清理。

此教学版本只校验恢复记录的几个字段，未绑定dataset；第18章将其替换为同步校验、固定路径/请求体、数据集/账户/操作隔离的完整pending.ts。现在只用于自己新建的小数据练习，勿把这段简化恢复直接当最终实现。

开发运行（第三个终端，根目录）：

```powershell
npm --prefix frontend run dev
```

浏览器访问 **http://127.0.0.1:5173**，别把localhost与127.0.0.1交替使用，否则Origin/Cookie可能不一致。后端仍需保持运行。

构建检查：

```powershell
npm --prefix frontend run build
```

看到 tsc检查成功与Vite生成dist。红线“Cannot find module react”通常是还没安装依赖或打开了错误目录；`React` 页面白屏先看浏览器F12→Console和Network。

本教学服务Origin固定5173，浏览器交互按5173验收。8080直出dist虽能访问文件，但登录写入会被Origin拒绝；最终项目用配置/请求同源规则处理开发与部署，21章再使用最终服务。不要删Origin校验来掩盖配置错误。


<a id="chapter-13"></a>
## 13. 操作、测试并重启你的教学项目

### 13.1 做一次真实双用户成交

保持两个服务都运行。普通浏览器注册 alice@example.com，密码 alice-password-123；另开**无痕窗口**注册 bob@example.com，密码 bob-password-123。两个普通标签页通常共用Cookie，不算两个独立账号会话。

1. Bob以SELL，price=100，quantity=2下单，刷新：ETH可用8、冻结2。
2. Alice以BUY，price=105，quantity=3下单：ETH可用12；USDT可用99695、冻结105。
3. Bob刷新：ETH可用8、冻结0；USDT可用100200、冻结0。
4. Alice撤买单余量：USDT可用99800、冻结0；买单FILLED数量2、CANCELED数量1、余量0（教学页面主要显示余量/状态）。

这里每个注册用户都有10ETH/100000USDT，所以数字与第5章最小单元测试起始资金不同，成交变化相同。查全库总量时要把初始化的管理员也计入，不能只加两个用户然后说资金不守恒。

管理员在第三个独立会话登录admin@example.com，能看到用户，给Alice增加5 USDT后资金为99805。停用Bob，Bob旧Cookie下一次查询应拒绝；再启用，Bob重新登录才能继续。已有挂单不会自动撤掉。

### 13.2 增加真实HTTP+重启测试

下面完整测试使用临时目录、真实三库、真实bcrypt、httptest和CookieJar；不会连接你正在运行的服务，也不修改data。


下面是 `transport/http_test.go` 的**完整文件**：

```go
package transport

import (
	"bytes"
	"context"
	"encoding/json"
	"net/http"
	"net/http/cookiejar"
	"net/http/httptest"
	"net/url"
	"path/filepath"
	"testing"

	"exchangelearn/auth"
	rt "exchangelearn/runtime"
)

// 使用真实三库、Cookie 和处理器；每个测试拥有自己的临时数据。
func TestHTTPAndRestart(t *testing.T) {
	dir := t.TempDir()
	runtime, err := rt.Open(dir)
	if err != nil {
		t.Fatal(err)
	}
	db, err := rt.OpenDB(filepath.Join(dir, "auth.db"))
	if err != nil {
		t.Fatal(err)
	}
	users, err := auth.New(db)
	if err != nil {
		t.Fatal(err)
	}
	app := &Server{Auth: users, Runtime: runtime, Origin: "http://127.0.0.1:5173"}
	admin, err := users.Bootstrap(context.Background(), "admin@example.com", "learn-admin-password")
	if err != nil {
		t.Fatal(err)
	}
	if err = app.Fund(context.Background(), admin.ID); err != nil {
		t.Fatal(err)
	}
	server := httptest.NewServer(app.Handler())
	// 清理顺序：先停止 HTTP，再关 auth，最后关 runtime。
	t.Cleanup(func() {
		server.Close()
		if db != nil { db.Close() }
		if runtime != nil { runtime.Close() }
	})
	jar, _ := cookiejar.New(nil)
	client := &http.Client{Jar: jar}
	request := func(method, path string, body any, csrf, key string, status int) map[string]any {
		t.Helper()
		var buf bytes.Buffer
		if body != nil {
			if err := json.NewEncoder(&buf).Encode(body); err != nil {
				t.Fatal(err)
			}
		}
		req, err := http.NewRequest(method, server.URL+path, &buf)
		if err != nil {
			t.Fatal(err)
		}
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("Origin", app.Origin)
		if csrf != "" {
			req.Header.Set("X-CSRF-Token", csrf)
		}
		if key != "" {
			req.Header.Set("Idempotency-Key", key)
		}
		resp, err := client.Do(req)
		if err != nil {
			t.Fatal(err)
		}
		defer resp.Body.Close()
		var result map[string]any
		if err = json.NewDecoder(resp.Body).Decode(&result); err != nil {
			t.Fatal(err)
		}
		if resp.StatusCode != status {
			t.Fatalf("%s: %d %+v", path, resp.StatusCode, result)
		}
		return result
	}
	a := request("POST", "/api/auth/register", map[string]string{"email": "alice@example.com", "password": "alice-password-123"}, "", "", 200)
	csrf := a["csrf"].(string)
	request("POST", "/api/orders", map[string]string{"side": "BUY", "price": "105", "quantity": "3"}, "", "buy-0001", 403)
	body := map[string]string{"side": "BUY", "price": "105", "quantity": "3"}
	first := request("POST", "/api/orders", body, csrf, "buy-0001", 200)
	again := request("POST", "/api/orders", body, csrf, "buy-0001", 200)
	if again["replayed"] != true || again["result_seq"] != first["result_seq"] {
		t.Fatal(again)
	}
	request("GET", "/api/admin/users", nil, "", "", 403)
	state, err := runtime.State(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	// HTTP 已停，才允许 Close；下面验证正常重启而非模拟断电。
	server.Close()
	db.Close()
	db = nil
	runtime.Close()
	runtime = nil
	runtime, err = rt.Open(dir)
	if err != nil {
		t.Fatal(err)
	}
	db, err = rt.OpenDB(filepath.Join(dir, "auth.db"))
	if err != nil {
		t.Fatal(err)
	}
	// Cleanup 闭包读取重赋值后的指针，因此最终清理新 runtime/db。
	users, err = auth.New(db)
	if err != nil {
		t.Fatal(err)
	}
	after, err := runtime.State(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	beforeRaw, _ := json.Marshal(state)
	afterRaw, _ := json.Marshal(after)
	if !bytes.Equal(beforeRaw, afterRaw) {
		t.Fatalf("replay mismatch: %s / %s", beforeRaw, afterRaw)
	}
	me, _, err := users.Session(context.Background(), jar.Cookies(mustURL(t, server.URL))[0].Value)
	if err != nil || me.Email != "alice@example.com" {
		t.Fatal(me, err)
	}
}

func mustURL(t *testing.T, raw string) *url.URL {
	t.Helper()
	u, err := url.Parse(raw)
	if err != nil {
		t.Fatal(err)
	}
	return u
}
```


根目录运行：

```powershell
go test -count=1 -v ./...
go vet ./...
```

测试证明：注册资金初始化、缺CSRF被拒绝、原键重复不重复交易、普通用户不能用管理员接口、正常重启全视图一致且身份会话保留。它**没有**模拟突然断电，也没实际跑浏览器；后面完整项目再做故障窗口和E2E。

测试尾部先停HTTP再关Runtime，符合Close前提。Cleanup闭包读取重赋值后的runtime/db，因此最终清理新实例；不要把它改成绑定旧实例的defer而重复close队列。

### 13.3 到这里你已经亲手写出什么

```text
exchange-learn/
  go.mod / go.sum / .gitignore
  core/core.go / core_test.go
  runtime/runtime.go
  auth/auth.go
  transport/http.go / http_test.go
  cmd/server/main.go
  frontend/package.json / package-lock.json
  frontend/tsconfig.json / vite.config.ts / index.html
  frontend/src/main.tsx / App.tsx / style.css
  data/                 # 运行生成，不是源码
```

别一口气删教学代码再复制完整仓库。先尝试解释每个文件输入/输出，以及一笔单如何流经各层。接下来的章节才逐项改变它们，补齐本项目最终能力。

<a id="chapter-14"></a>
## 14. 从教学版升级到完整项目

### 14.1 先保存一个可以回退的学习成果

停掉教学服务，保留 exchange-learn 源码和自己的练习数据。接下来可以另建 `exchange-full-learn`，从你理解的代码重写完整版。在新目录使用 `go mod init web3exchange`；最终源码 import 都以 `web3exchange` 开头。

你已经写出来的算法和规则继续成立，但教学版数据库/路由/日志 JSON **不能直接当最终旧数据升级**。教学数据在教学目录保留；完整版使用新的空数据目录。最终所谓“旧 schema=0兼容”指本项目的历史版本，不指这份教学版简化日志。

当某一步卡住，按这一顺序处理：读本章输入/输出→自己实现单个函数→编译→写或运行对应测试→和仓库同名函数对照。参考源码是有中文解释的实现答案，不要求先复制整个仓库再猜它做了什么。

### 14.2 最终文件应该按什么顺序创建

| 顺序 | 创建/改写的文件 | 从教学版转过去的东西 | 新增能力 |
| --- | --- | --- | --- |
| 1 | backend/types.go、engine.go | core领域对象和算法 | 完整订单规则、增量变更、预算 |
| 2 | backend/store.go | runtime中的OpenDB/投影 | 三库schema、盘口聚合、水位/版本 |
| 3 | backend/runtime.go | 教学Runtime | 批日志、在途额度、fail-fast/关闭 |
| 4 | backend/auth.go、http.go | auth与transport | 严格校验/限流/权限、完整API |
| 5 | api/openapi.json、spec.go | 现有JSON字段 | 契约嵌入/真实响应校验/TS生成 |
| 6 | backend/query.go、admin_query.go、market_query.go | /state查询 | 分页/单笔/按key确认/完整行情 |
| 7 | frontend/src/api.ts、pending.ts、generated/api.ts | call和Pending | 精确契约、恢复作用域 |
| 8 | frontend/src/App.tsx、style.css | 教学界面 | 盘口/分页/水位/实时推送/管理 |
| 9 | backend/maintenance.go、observability.go | 手动看库/日志 | 离线运维、指标、pprof |
| 10 | cmd/server、exchangectl、loadcheck | 教学入口 | 配置/运维CLI/负载工具 |
| 11 | tests、scripts、deploy、Dockerfile | 手工操作 | 自动验收/发布/部署 |

最终仓库把同包后端文件放在 backend，这是当前组织方式；它不是每个文件独立微服务。Go同一package内可以调用未导出的函数，外围cmd只调用导出API。

初期依赖以第2章五项为基础；最终还加入 websocket v1.8.13、kin-openapi v0.133.0，以及前端GSAP、openapi-typescript、Prettier、Playwright。最终版本清单以 [go.mod](../../go.mod) 和 [package.json](../../frontend/package.json) 为准，包括间接依赖。不要引入当前不存在的 chi、decimal.js、Prometheus Go SDK，也不要声称生成了Go路由或fetch客户端。

### 14.3 怎样拆一项改造

以“新增IOC”为例：先补DTO枚举→验证组合→修改撮合循环结束行为→补资金/数量断言→更新OpenAPI→生成TS→页面选择IOC→浏览器验证→更新设计/测试文档。只改一个下拉框并不算实现。

建议每次只完成表中一行，并保存自己的版本记录。当前工作区没有Git历史，报告不能编造提交号；你在自己的练习目录可 `git init` 后按里程碑提交，`.gitignore` 先排除数据/依赖/密码。每次提交写具体行为，例如“IOC余量释放资金”，比“优化架构”清楚。

<a id="chapter-15"></a>
## 15. 补全订单规则、预算和对象所有权

### 15.1 把领域类型升级到最终DTO

对照 [types.go](../../backend/types.go) 逐项扩充教学类型：

- Command 增加 SchemaVersion、PayloadHash、Timestamp、Type、TIF、ActorID、Reason；资金账户改为 AccountID。
- Order 保留 Quantity/Remaining/Filled/Canceled，增加类型、TIF、撤销原因、创建时刻和内部Seq；JSON字段为 remaining_quantity 等，不沿用教学短名。
- Result 增加 Orders/Balances/Entries 增量副本；这些字段 `json:"-"`，不对HTTP公开。Trades等同样由内部投影消费。
- Balance 在内核仍是文本数值，资金运算转decimal；Entry记每次AvailableDelta/FrozenDelta和原因。
- Snapshot 包含 dataset_id/applied_seq/bids/asks/trades，订单ID和所有序号用字符串。

Seq来自日志writer；Timestamp由Submit外围固定；ID取下单Seq文本，不用rand.Intn或当前时间生成。不保证订单ID连续，因为注资/撤单/拒绝/重试都会消费日志位置。一次命令多次成交用 `Seq/成交下标` 唯一编号。

写新类型后编译会提示旧字段名；按核心→运行时→HTTP→测试顺序修改，别用多余的兼容字段让两份协议混杂。

### 15.2 一次只扩一个业务分支

[engine.go](../../backend/engine.go) 中的主要方法与教学对应关系：

| 最终方法 | 你已有的基础 | 要补的工作 |
| --- | --- | --- |
| NewEngine | New | 最优档缓存、完整状态容器 |
| balance/move | balance/move | 每笔资金同时记录Entry |
| Apply | Apply | changed订单集、确定性排序、独立余额副本 |
| place | place | 类型/TIF组合、预扫描预算、IOC余量取消 |
| crosses | place价格条件 | 两种方向复用同一价格裁决 |
| opposite/bestOpposite | best | 预扫描树顺序与最优缓存 |
| add/remove | add/remove | 空档更新最优Bid/Ask缓存 |
| release | release | 明确资金原因、原价释放 |

支持的组合是 LIMIT+GTC、LIMIT+IOC、MARKET+IOC。MARKET仍必须有price保护价：BUY允许对手价≤price，SELL允许≥price。没有流动性时正常取消剩余，不panic；部分成交后IOC取消剩余；LIMIT GTC余量留在簿上。自成交取消taker余量，已有maker继续等待。

扩展步骤：先在冻结前验证组合；撮合循环仍按maker价格；循环结束时判断 `GTC且不是自成交` 才挂余量，其余release并累计Canceled、Remaining归零、记录原因。最终状态CANCELED可以同时Filled>0，页面不能当它“完全没成交”。

### 15.3 预扫描为什么必须早于冻结

最终版单命令最多接触1024张可成交maker，活动订单预算100000。单写者若被巨型命令长时间占用，所有后续用户都会等。

正确做法是在任何资金/订单修改前，用和实际撮合相同的价差、自成交与余量停止规则预扫描。一旦超过成交预算，**整条命令拒绝且不产生资金副作用**。不要先成交1024笔再拒绝第1025笔，否则你需要处理已经发生的部分业务。

步骤可以写成以下片段（省略具体树迭代，完整实现见place）：

```text
验证字段与余额
按对手最优价顺序遍历可能成交maker
遇非交叉价格、自成交或余量归零停止
若计数>1024：返回MATCH_LIMIT_EXCEEDED，尚未冻结
检查活动预算
创建订单并冻结
再执行有界撮合
```

这是两次遍历的成本换明确预算。红黑树解决价格索引，但不自动解决单条命令工作量。

### 15.4 用增量副本替换Snapshot全量复制

Apply内创建 `changed := map[string]*Order{}`。下单新单、成交maker、撤单目标都放进去，结束时复制这些Order值到r.Orders，按Seq排序。资金move追加Entry；结束时按受影响 account:asset 去重，复制最新Balance到r.Balances。不要复制全部历史。

Orders/Balances是“变更后的完整值”，Entries是“有符号增量”。投影若把余额完整值再次当增量相加，会翻倍。每次返回Order、首次dedupe记忆的Order各自复制；之后runtime的copyResult再复制所有slice及Order/Error指针，隔离HTTP与还未落库的投影。

不能只靠race检查所有权。单线程环境里外部修改返回指针同样能污染下一次结果，它可能没有并发读写。要明确断言篡改返回对象后原结果/数据库不受影响。

**对应最终验收命令（在最终项目根目录，非exchangelearn）：**

```powershell
go test -count=1 -v -run 'TestMatchingFIFOAndSettlement|TestIOCAndSelfTrade|TestMatchBudgetRejectsBeforeMutation|TestCoreResultOwnership|TestPricePriorityBothDirections' ./backend
```

练习完成标准：能解释第5章四笔move、自成交规则、首次快照与最新订单差别，并证明非法订单不改变资金。

<a id="chapter-16"></a>
## 16. 升级日志、增量投影和恢复

### 16.1 先建最终数据库结构

在 [store.go](../../backend/store.go) 依次写openDB→OpenStore→Close→ProjectBatch→applyProjected→Balances/Snapshot。先写建表和读取水位，再实现投影；每个阶段用临时目录做集成测试。

| 库 | 表/元数据 | 是否权威 | 为什么保存 |
| --- | --- | --- | --- |
| journal.db | commands、metadata | 是 | 已持久化输入、dataset_id、engine_version等 |
| auth.db | users、sessions、auth_audit | 是 | 身份/密码摘要/权限/会话/认证审计 |
| views.db | orders、balances、levels、trades、ledger、results、credit_audit、progress、projection_metadata | 可派生 | 查询/盘口/首次结果/资金分录/执行审计/可见水位 |

按源码中的DDL创建主键和索引，金额列TEXT。SQL里不做浮点资金运算。新数据目录在外围生成dataset_id并持久化，它用于区分两个独立历史；来自恢复同一套库时保留原dataset，不因每次进程启动换一个。

### 16.2 先写单条投影，再加批事务

ProjectBatch先校验命令和结果长度相等，Begin一次事务，依次applyProjected，最后Commit一次。中间任何SQL错整批Rollback，包括progress，不能某几张订单写入而水位只推进一半。

每条applyProjected：

1. 查progress；当前命令必须是下一条或已提交前缀，缺口拒绝。
2. 对变更订单先读取旧快照，用负旧余量减去旧价档，再加新余量到新档。例：余量3变1，盘口净减2。
3. upsert订单，覆盖最新余额；成交与分录按命令序号/下标插入。
4. 管理员CREDIT记录操作者/目标/原因/金额/结果码/重试标记，不只记录“请求过”。
5. 保存本次Result，推进progress；以上全在同一事务。

已投影前缀不能再累加分录或盘口；旧库补缺资金审计按明确兼容路径做。首次按key查询取最早Result记录，重复envelope有自己ProcessedSeq，不意味着新成交。

测试思路：用临时SQLite trigger使批内第二项失败，断言订单、资金、分录、progress都没部分提交；重开后从journal补齐。这是真实事务测试，比mock出一个nil错误更有价值。

### 16.3 新运行时的四个阶段

[Runtime](../../backend/runtime.go) 改为下面顺序。input/durable/results都是有界channel，默认各1024。全流程最多2048个inflight，日志默认最多64条或等1ms聚一批。

```mermaid
sequenceDiagram
    participant H as HTTP
    participant W as 日志writer
    participant E as 唯一核心
    participant P as 投影worker
    H->>W: Submit：占用inflight并入队
    W->>W: 批INSERT、FULL Commit
    W->>E: durable：已提交命令
    E->>P: Apply产生增量副本
    P-->>H: copyResult后回包
    P->>P: 增量批投影Commit
    P->>P: 释放inflight
```

project只收集已就绪结果，最多批大小，不再等待日志的1ms。成功回包保证**输入日志已提交并完成核心处理**，不保证视图立即可见。所以要加min_seq读取屏障，第18章讲查询。

实现顺序：先由单条writer分配Seq→改同事务批写→Commit后整批发durable→run逐个Apply→project聚已就绪结果→回包前copyResult→ProjectBatch→成功后释放slots。批失败r.fail停止受理并通知监督退出，不能继续使用内存递增后但未提交的Seq。

### 16.4 in-flight不是HTTP连接数

slots可看成有2048张通行证，受理命令先拿一张，直到可靠投影完成才归还。HTTP回包、超时或用户断网都不能归还；否则投影慢时客户端可以持续积压后台工作。

Submit入队失败立即归还；入队成功由project负责归还。接入关闭与send/close要协调，最终runtime外围使用锁/原子保护生命周期，**核心Engine仍无业务锁**。用户提出“去掉锁”是核心状态单写者，不要求外部库、生命周期和指标都完全无锁。

并发请求被拒绝是正常保护，不是丢失已接受命令。排队越长，延迟越大；增加队列长度不等于增加处理速度。

### 16.5 恢复要同时恢复内存与视图

最终启动检查目录锁、engine/schema、dataset、日志连续性和投影水位。重放所有历史命令恢复Engine的订单簿/余额/dedupe；视图已提交前缀跳过，落后尾部补投影。即便views已追平，也不能跳过内存重放，因为活动簿和首次结果仍在内存。

未知命令格式、序号缺口、权威损坏、投影超过日志上界都拒绝启动，不删库“修好”。未实现快照，所以历史越大重放越慢；checkpoint只合并SQLite WAL，不截断commands。

Close先停止受理，writer排空并关durable，核心排空并关results，project提交后退出，最后关库。正常关闭先不cancel全部worker，否则已受理任务可能被跳过；超时/故障走明确中止，再靠权威日志恢复。

**最终验收：**

```powershell
go test -count=1 -v -run 'TestBackpressureAndCanceledWait|TestProjectionBatchIsAtomic|TestProjectionRollbackAndRecovery|TestRuntimeResponseCannotMutateProjection|TestSequenceExhaustionIsControlled' ./backend
```

精确崩溃窗口的收集/执行在第19章；不要用上述正常测试推断断电耐久性。

<a id="chapter-17"></a>
## 17. 补全认证、公开契约和管理员审计

### 17.1 完整认证与HTTP接入的新增工作

对照 [auth.go](../../backend/auth.go) 与 [http.go](../../backend/http.go)，将教学版补到以下行为：

| 要加的行为 | 写在哪 | 验证什么 |
| --- | --- | --- |
| 严格邮箱/密码校验、普通注册固定USER | normalizeEmail/validPassword/CreateUser、authAction | 角色伪造、超长/过短、重复邮箱拒绝 |
| 认证入场/限流预算 | allowAuth、authAction | bcrypt在外围且不能无限堆积 |
| 缺会话与认证库故障分开 | Session/protected | 不把库错误都变成401 |
| Cookie Secure/HttpOnly/SameSite及安全响应头 | authAction/Handler | HTTP本地与HTTPS配置分别验证 |
| 停用+删除会话+auth_audit同事务 | SetDisabled | 审计失败整个操作回滚 |
| 初始化资金失败登录可补齐 | EnsureFunding | 同键不重复增发 |
| 管理员注资namespace/ActorID/Reason | credit | 目标账户、操作者、执行结论可解释 |
| 各条管理接口独立RBAC | protected(true,...) | 不能只保护管理首页 |

停用语义必须写清：之后会话被拒绝，旧挂单不自动撤销，已受理命令仍可能完成。这是边界事实，若想“停用立刻取消所有挂单”需新增有顺序的领域命令，不能在auth事务中直接触碰Engine。

### 17.2 从接口表写OpenAPI

OpenAPI是一份机器可读的请求/响应说明书。先写info、paths，再在components/schemas复用User、Auth、PlaceOrder、Result、OrderPage等；写清security、状态码、金额/序号为string、枚举、required。对照 [api/openapi.json](../../api/openapi.json) 作为完整参考。

以下是**阅读片段**，展示为什么quantity不能写number；完整规格必须按实际DTO/路径建立：

```json
{
  "quantity": { "type": "string", "example": "0.0001" },
  "price": { "type": "string", "example": "105" },
  "processed_seq": { "type": "string", "example": "12" }
}
```

在 api/spec.go 用go:embed嵌入JSON，HTTP `GET /api/v1/openapi.json` 返回本次编译的内容。你修改磁盘规格但没重编服务时，老二进制仍返回老版本，因此前后端必须同版。

前端package增加openapi-typescript 7.8.0与Prettier 3.5.3；写api:generate和api:check脚本，使用同版规格。当前项目提供现成 [check-api.mjs](../../frontend/scripts/check-api.mjs)，生成后格式化再逐字比较。

```powershell
npm --prefix frontend run api:generate
npm --prefix frontend run api:check
go test -count=1 -v -run '^TestOpenAPIContractAndRealResponses$' ./backend
```

api:check只是生成一致性；真正请求响应由contract_test使用kin-openapi校验。TypeScript的 `as`/泛型不会在运行时验证JSON，后端仍负责参数/角色校验。当前GoDTO、路由、fetch手写，不能把一份generated/api.ts讲成“整个API自动生成”。

### 17.3 把前端网络层从App拆出来

新建 [api.ts](../../frontend/src/api.ts)，从generated/api导出类型，写APIError、api、errorText、unknownResult。请求包含Cookie、CSRF、原key与dataset，12s AbortController只取消客户端等待。response非成功读业务错误；网络/解码失败转换RESULT_UNKNOWN；finally清理计时器。

不要把401/403一律删除pending：原单成功但响应丢失，确认时会话刚过期，401并不能否定原单。先恢复身份再原键确认。泛型 `api<Result>` 仅帮助编辑器，不自动保证收到的对象符合Result。

**最终验收：**

```powershell
go test -count=1 -v -run 'TestAuthValidationRules|TestSessionExpiryAndReenableDoesNotReviveTokens|TestDisableAuditFailureRollsBack|TestEveryAdminRouteEnforcesRBAC|TestAuthStoreFailureIsNotUnauthenticated' ./backend
```

完整角色/会话说明参考 [认证设计](../02-architecture/auth-design.md)，手工请求字段参考 [接口指南](api-guide.md)。

<a id="chapter-18"></a>
## 18. 写分页、实时行情和待确认请求恢复

### 18.1 用min_seq处理写后读

最终版下单回包时投影可能落后。例如下单Result的processed_seq="100"，马上查订单时views还在99，这不等于订单丢了。

在http.waitProjection里解析min_seq，用int64检查范围，外围最多等2s，投影progress≥目标时查询，未追上返回503 PROJECTION_LAG。不要锁住Engine等数据库，也别让用户一直无限等。

前端写确认后刷新：

```typescript
// 插入片段：auth/result已经来自最终版API。
const page = await api<OrderPage>(
  `/orders?limit=20&min_seq=${encodeURIComponent(result.processed_seq)}`,
  auth.csrf_token,
);
```

订单、余额分别查询并不是同一数据库事务，Promise.all也不把它们变成全局快照。min_seq表示至少看见此水位，不表示恰好历史seq=100的静态状态。

### 18.2 先写订单游标，再扩用户/成交

[query.go](../../backend/query.go) 定义OrderPage/OrderView/CommandLookup与游标编码解码。第一页读取投影水位，固定新订单创建seq上界；下一页seek“更小的创建seq”，用limit+1判断有没有下一页。SQL再限定当前account或管理员scope。

下面是**SQL设计片段**，实际列名/游标字段按query.go实现：

```sql
SELECT payload FROM orders
WHERE account_id = ? AND seq <= ? AND seq < ?
ORDER BY seq DESC LIMIT ?;
```

第一页before可按实现用无界分支，别为省事硬造一个可能溢出的maxSeq+1。返回items、dataset_id、applied_seq与可选next_cursor，页面先显示20条；API范围1–100。

游标携带dataset、账户/范围、上界与位置，Base64只是编码，既不是加密也不是授权。客户端可以修改它，服务端仍需验格式/数据集/作用域，SQL必须限制账号。翻页期间旧订单仍会成交或撤单，因此固定的是“哪些订单被纳入遍历”，不是每张单的状态。

单笔 `/orders/{id}` 查询最新视图；`/commands/by-key` 只返回当前账号的首次结果。found=false可能是投影尚未可见，不能凭它换键重复下单。

扩展顺序：

1. 在admin_query.go用用户rowid游标，返回UserPage。
2. 在market_query.go用成交rowid游标，返回TradePage；不能只用命令seq翻页，因为一命令能产出多成交，同seq边界会漏。
3. 管理审计AUTH/CREDIT来源独立，当前分组分页各有上界，不假装跨库全局时间排序/快照。
4. 前端每个列表保存next_cursor，“加载更多”编码原游标，切身份/数据集重置列表和游标。

**最终验收：**

```powershell
go test -count=1 -v -run 'TestOrderPaginationBoundaryAndOwnership|TestCommandLookupFirstResultAndLag|TestAdminPaginationAndCreditResults|TestPublicTradesPagination|TestDatasetIdentityUpgradeAndWriteFence' ./backend
```

### 18.3 写实时行情：先REST，再WS

行情是公开盘口与近期成交，不发私有余额。Store.Snapshot在同一读事务取得applied_seq、bids/asks、trades。盘口levels由投影增量维护，查行情不能每次扫全订单再排序。

Server.RunSampler每100ms采样20档/最近50笔，各WS连接每100ms tick首次或水位改变发送完整Snapshot，2s写超时断开慢客户端。网络写必须在外围，不能让某浏览器拖住Engine。

实现顺序：公共GET /snapshot→后台采样→coder/websocket接入→来源与连接预算→首次/更新发送→关闭所有流→前端重连。最终代码入口是 [http.go](../../backend/http.go) 的RunSampler/stream/CloseStreams。

前端App使用effect创建socket，onmessage解析并按dataset/applied_seq裁决；返回清理函数关闭socket、清掉重连定时器。初次挂载REST一次，此后WS重连等待新快照，退避0.5s逐步到10s。HTTPS使用wss。

**不要用 Number 比序号。**仅同dataset可用BigInt比较；新数据集从低seq开始仍必须接收。完整快照可以跳过中间序号，它不是逐条可靠成交投递，完整成交历史走分页接口。

例如旧数据集A当前seq=500，切到B收到seq=2，应接受B并重置缓存；A内从500收到499才是旧消息。trade近期快照同seq文本ID排序与历史rowid排序不同，不据此判定少了一笔。

### 18.4 把简化pending升级成可审阅恢复协议

最终 [pending.ts](../../frontend/src/pending.ts) 的记录至少包含：

```typescript
// 类型片段：完整hook使用前端Auth并按scope校验。
type PendingAction = {
  version: 1;
  dataset: string;
  account: string;
  key: string;
  path: string;
  body?: unknown;
};
```

分别为place/cancel/credit保存，存储key包含dataset/account/scope。restorePending必须验证大小、version、身份、dataset、键字符、固定路径、body对象及每个字段类型。cancel只允许对应数字订单ID路径且没有body；credit的目标账户仍由后端权限验证。

实现顺序：独立纯函数restorePending→单元非法格式测试→usePending同步初始化→begin先保存→发送API→明确结论后clear→页面显示原请求确认。不要用effect延后读取记录，因为页面可能先短暂显示“可下单”，读到旧pending之前又发送新单。

begin返回已保存的原动作，确认不再读表单；clear失败保留记录并显示错误；不按TTL自动清掉未知动作。sessionStorage跨同标签刷新保留，但关闭标签、清存储、换设备没有恢复保证；后端幂等保证业务效果，不是浏览器分布式锁。

dataset变更停止自动确认旧动作，先核对身份/备份/当前数据。退出不删除未知写记录，回到原身份继续确认。管理员注资没有任意目标账号按key查询接口，只能原POST原操作者原内容确认。

### 18.5 页面完善的实现次序

最终 [App.tsx](../../frontend/src/App.tsx) 以组件和hook组织：App负责身份/行情/刷新；AuthForm负责登录注册；Book负责盘口；OrderForm负责新单；OrderTable负责订单与撤单；AdminPanel负责用户/订单/审计与注资。当前都在App.tsx，不是多个服务。

先完成auth加载与身份切换取消旧结果；再分页/写后读；然后WS重连/pending；最后样式与动画。异步返回时核对当前身份或请求代次，避免A账号慢响应覆盖B账号列表。

沿用Carbon成熟颜色，平面直角、无渐变、精简文字；金额/seq仍字符串，盘口量条的相对宽度可以Number展示但不参与结算。最终GSAP 3.13.0配@gsap/react 2.1.2，组件作用域和卸载清理、prefers-reduced-motion；不要让动画替代busy/错误状态。

动画可从已有App中的useGSAP读起，先核对作用域、卸载清理和减少动态效果设置，再为新交互补浏览器验收。金额、按钮状态和错误处理不依赖动画完成。

<a id="chapter-19"></a>
## 19. 设计完整测试，并读懂性能结果

### 19.1 每种测试证明的事情不同

| 测试 | 是否要真实数据库/服务 | 最重要的断言 |
| --- | --- | --- |
| 核心单元 | 否 | FIFO/价格/资金公式/幂等/边界/所有权 |
| 组件集成 | 真实SQLite/httptest | 事务、权限、投影、水位、游标 |
| 属性测试 | 内存核心 | 每步资产守恒、冻结与挂单一致、索引一致 |
| 崩溃恢复 | 测试子进程/独立服务 | 特定窗口杀进程后重放确定性 |
| 前端单元 | 真实TS源，受控fetch/storage | pending校验、头、异常与未知结果 |
| 浏览器E2E | 真浏览器+后端 | Cookie/CSRF/页面交易/管理/刷新恢复/WS |
| 性能 | 独立环境 | 负载、完成量、拒绝、延迟、最终对账 |

先写“输入—动作—预期”，再写代码。例如“停用审计插入失败”预期用户状态与旧session全保留，因为同事务回滚；“返回指针被调用者修改”预期投影仍是原结果。

### 19.2 用业务不变量检查一组命令

遍历所有账户，对每种资产求 `Available+Frozen`，应等于累计合法CREDIT增加的总供给。无负数；活动买单需USDT冻结等于全部 `price×remaining` 总和，活动卖单ETH冻结等于remaining总和；每单 `Quantity=Remaining+Filled+Canceled`；终态Remaining=0。

在 [property_test.go](../../backend/property_test.go) 的TestRandomizedCoreProperties里，固定seed生成合法/非法命令，每一步核对这些式子与树/FIFO/反向索引。固定seed保证失败可重现；生产核心仍没有随机输入。它不是完整参考撮合模型对拍。

钱相等但簿节点重复仍会出错，所以还要查：每个活动订单只出现一次、ref指向同一节点、空价档不存在、最优缓存等于树极值。

### 19.3 崩溃窗口要实际被测试收集

提交前、提交后未Apply、Apply后未投影、投影事务中、重放中等窗口，父测试等待明确标记再Kill子进程，重开同目录核对。只“随机杀一次服务”不能证明所有精确窗口。

最终测试文件 [crash_recovery_test.go](../../backend/crash_recovery_test.go)。先确认收集：

```powershell
go test -list '^TestCrashRecoveryWindows$' ./backend
go test -count=1 -v -run '^TestCrashRecoveryWindows$' ./backend
```

名称里的Windows指故障窗口，不表示只测微软Windows。Go文件名 `_windows_test.go` 会被GOOS过滤，Linux可能悄悄漏测；现有文件已更名避免这个坑。helper在没有父进程参数时skip是正常，真正验证看父用例的六个子场景。

Kill进程验证的是进程崩溃，不是真实断电/fsync硬件故障。FULL配置也不能据此推断所有磁盘都绝对可靠。

### 19.4 分层执行，不一次把所有工具乱开

以下bash/Python脚本在 **Linux/WSL** 的最终项目根目录执行；PowerShell直接执行Go/npm即可。Windows的race需要对应C工具链，普通go test不需要；不要把 `CGO_ENABLED=0` 用于race。

```bash
bash scripts/test.sh unit
bash scripts/test.sh backend
bash scripts/test.sh coverage
bash scripts/test.sh fuzz
bash scripts/test.sh all
```

all顺序执行格式/依赖/Go测试/race/vet/前端单元/契约/构建/故障，再覆盖率、有限fuzz、浏览器。首次浏览器准备：

```bash
npx --prefix frontend playwright install chromium
python3 scripts/e2e_check.py
```

浏览器脚本用自己的临时目录/管理员/随机端口，不重置用户data；无浏览器依赖是准备失败，不写成业务通过。Go测试使用t.TempDir，不拿演示用户目录做损坏/trigger实验。

覆盖率生成HTML后查看未测分支，不能把“80%”当成正确性证明。node内置test的前端用例不等于浏览器测试，也不等于已统计前端行覆盖率。详细操作看 [测试手册](../04-testing/testing-guide.md)、[用例目录](../04-testing/test-cases.md)。

### 19.5 开始做有意义的性能实验

先单独测Engine，再测FULL日志/投影/恢复，最后测HTTP端到端。核心benchmark不能声称是可靠下单TPS，因为没认证、序列化、磁盘、网络。

最终项目命令（Linux/WSL，独立环境）：

```bash
go test -run '^$' -bench . -benchmem ./backend
CGO_ENABLED=0 go build -trimpath -o bin/loadcheck ./cmd/loadcheck
python3 scripts/load_check.py --rates 100,500,1000 --seconds 5 --output /tmp/exchange-tutorial-load.json
```

低并发客户端通常发一条等一条，会自然降低压力，掩盖过载。loadcheck按开放到达率产生计划请求，还要记录客户端因自身能力而丢弃的请求、服务拒绝、实际完成与延迟。

读报告时至少说清：硬件/磁盘、Go版本、是否FULL、用户/订单量、交叉成交比例、流量持续时间、成功/拒绝/丢弃、p50/p95/p99及最终对账。p99不是平均值，也不是metrics的max；4000req/s短时历史实验不是当前最大新订单TPS或生产SLA。

单机能力常被最慢阶段限制：核心、FULL磁盘、投影、HTTP/认证、GC。2048是inflight预算，不是每秒2048单。单市场和多市场共享资金分区仍属不同难度；Redis/多写者分区未实现，不把它们写进实测成绩。对应讨论见 [详细面试Q&A](../06-interview/interview-qa.md)。

<a id="chapter-20"></a>
## 20. 写注释、规范和项目文档

### 20.1 学会解释为什么，不只解释语法

下面是你可以仿照的**注释片段**：

```go
// release 按订单原价与余量解冻，不按最新成交价解冻。
// 买单剩1 ETH、原价105时释放105 USDT；已成交部分不会释放第二次。
// 调用者必须是唯一核心，保证Frozen与活动挂单对应。
```

比“调用函数，更新金额”有价值。每个模块先说明用途、输入/输出、谁拥有可变状态；关键函数说明执行顺序、边界和失败处理；资金公式给可计算例子。生成文件、依赖不手工注释，业务变更同步更新注释。

前端effect写清启动/清理、身份切换、异步旧响应；测试写触发条件和证明点；脚本注明平台、工作目录、参数、产物、失败退出/清理谁的资源；部署配置注明数据路径和密码规则。

### 20.2 从你的实现逐步写出这些文档

| 文档 | 新手可以先写的一页内容 | 最终参考 |
| --- | --- | --- |
| 目标 | 谁使用、模拟资产、订单类型、不做什么 | [goal.md](../../goal.md) |
| 架构 | 一张调用链、所有权、提交/回包/可见边界 | [architecture.md](../02-architecture/architecture.md) |
| 认证设计 | 注册/会话/权限/停用语义 | [auth-design.md](../02-architecture/auth-design.md) |
| 规范 | 金额字符串、错误、单写者、注释、依赖锁 | [engineering-standards.md](engineering-standards.md) |
| 测试设计 | 业务不变量、权限矩阵、崩溃窗口 | [test-design.md](../04-testing/test-design.md) |
| 测试记录 | 日期、命令、版本、实际输出、未执行项 | [reports](../README.md)中的报告入口 |
| 部署 | 配置/端口/卷/停止/备份/升级 | [deployment.md](../05-deployment/deployment.md) |
| 维护 | 三库、损坏、未知结果、投影重建 | [data-lifecycle.md](../05-deployment/data-lifecycle.md)、[operations-runbook.md](../05-deployment/operations-runbook.md) |
| 面试 | 具体问题、方案、公式、测试证据、剩余限制 | [interview-guide.md](../06-interview/interview-guide.md)、[interview-qa.md](../06-interview/interview-qa.md) |

别先写“支持高并发高可用”再找代码去凑。每项能力关联函数和测试，计划/示例/实测分别标明。代码阅读时按 [code-reading-guide.md](code-reading-guide.md) 的调用链走，而不是按照文件长度从上到下背。

练习：写一个决策记录解释“为什么先日志后核心”，包含问题、候选、决定、代价、验收；再写“为什么全量Snapshot不能放在核心热路径”。

<a id="chapter-21"></a>
## 21. 运行当前完整项目与Windows一键脚本

到这里回到**本仓库根目录**，不要继续在exchange-learn里输入EXCHANGE参数。

### 21.1 最方便的Windows路线

安装Go与Node22+后，文件管理器双击 [run-windows.cmd](../../run-windows.cmd)。管理员名 **pinkode**，密码 **2312a132**。首次下载/构建后自动打开 http://127.0.0.1:8080；普通用户通过邮箱注册，密码仍12–72字节。

PowerShell可传参数：

```powershell
# 先进入本仓库，实际路径按你的机器修改。
Set-Location 'D:\codex小项目\go\web3'
.\run-windows.cmd -PrepareOnly
.\run-windows.cmd -Port 18080 -NoBrowser -DataDir 'D:\exchange-full-demo-data'
```

第二条只准备构建，第三条启动独立演示目录并手动打开18080。保持窗口，Ctrl+C停止，下一次重启保留身份/资金/订单；已有管理员不会自动改回指定密码。账号内部邮箱是pinkode@localhost，登录允许pinkode别名。

用户指定密码只有8字节，因此服务显式开启**数值回环本地模式**，拒绝公网/0.0.0.0和常规管理员邮箱配置混用。它不是普通注册规则被改成8字节，也不用于云/容器。详细说明看 [Windows指南](../05-deployment/windows-local-run.md)。

### 21.2 如果你想自己手写启动脚本

先把过程写成明确步骤，再组合CMD/PowerShell，参考 [run-windows.ps1](../../scripts/run-windows.ps1)：

1. 从脚本路径求根目录，不依赖双击时的当前目录；路径加引号支持中文/空格。
2. 检查go/node/npm，固定GOTOOLCHAIN=auto、原生windows与CGO=0。
3. 将前端/api复制到bin/windows，Windows npm依赖安装在这个副本；lock摘要变更时ci。
4. api:check→前端build→go build exe，任何命令失败立即非零并显示原错误。
5. 明确本机Origin/Cookie/资源与独立data-windows，局部进程env，退出恢复原值。
6. 启动自己子进程，检查ready与进程状态，成功后才打开浏览器。
7. 管理本次进程退出，不自动杀占端口的陌生进程，不删除锁或用户库。

CMD只是双击入口，执行PowerShell脚本并在失败时保留窗口；PowerShell5.1中文脚本用UTF-8 BOM/CRLF。不要把 `go run`、`npm install`、打开浏览器三行连一起就叫一键可靠运行。

### 21.3 最终项目的手动开发运行

纯Windows根目录（前提frontend/node_modules属于Windows；若此目录已在WSL安装过，使用上面的隔离脚本）：

```powershell
go mod download
npm --prefix frontend ci
npm --prefix frontend run build
$env:EXCHANGE_DATA_DIR="data-manual-learn"
$env:EXCHANGE_LISTEN_ADDR="127.0.0.1:8080"
go run ./cmd/server
```

普通用户可注册，需管理员则首次启动前设置常规EXCHANGE_ADMIN_EMAIL/PASSWORD，密码12–72字节；不要同时设置LOCAL_ADMIN_NAME。常规服务没有默认管理员。

前端开发另开终端 `npm --prefix frontend run dev`，访问5173，Vite代理/api与WS。部署则直接8080提供构建的dist。final的live/ready路径分别是 `/health/live`、`/health/ready`，不是教学 `/health`。

本机故障：连不上先看终端服务是否仍在、端口、恢复是否完成；登录403核对Origin、CSRF与访问地址；数据锁拒绝说明同一目录已有实例，别删锁文件绕过。

<a id="chapter-22"></a>
## 22. 容器和云服务器部署

### 22.1 部署是把哪些东西搬过去

浏览器只需要编译后静态文件，不需要TypeScript/Vite/node_modules；服务器只需要同版Go二进制、前端dist、配置和持久数据路径。构建工具留在构建环境，数据留在持久盘。

前半教学版不直接用于云部署。下面针对完整项目，使用已补齐的Origin/Secure Cookie、健康检查/排空、预算/运维工具。部署步骤是教学命令，不表示本轮真的部署了你的云服务器。

### 22.2 Docker的几个概念

镜像是程序/依赖打包模板；容器是正在运行的实例；卷保存容器删掉后仍需要的数据。`8080:8080` 是宿主端口映射容器端口。容器内127.0.0.1是容器自己，不是宿主。

阅读根 [Dockerfile](../../Dockerfile)，按以下三段理解：Node阶段用ci构建前端；Go阶段CGO=0构建exchange/exchangectl；运行阶段Debian slim只放产物，以非root UID10001运行。**离线Dockerfile.runtime才是scratch**，别把两个运行层混着解释。

Compose是用YAML集中写容器、环境、端口、卷、资源。只有一个exchange写者，卷挂/data，根文件系统只读、/tmp tmpfs、stop宽限90s。独立loopback诊断不公开。

安装Docker Desktop并确认Linux containers/daemon可用。完整项目根目录PowerShell执行（密码示例仅本地容器学习）：

```powershell
$env:EXCHANGE_ADMIN_EMAIL="container-admin@example.com"
$env:EXCHANGE_ADMIN_PASSWORD="container-learn-password"
$env:EXCHANGE_ALLOWED_ORIGIN="http://127.0.0.1:8080"
$env:EXCHANGE_COOKIE_SECURE="false"
docker compose -f deploy/compose.yaml config --quiet
docker compose -f deploy/compose.yaml up -d --build
docker compose -f deploy/compose.yaml logs --tail=100 exchange
Invoke-RestMethod http://127.0.0.1:8080/health/ready
```

先停你自己的本机8080服务或调整映射并同步Origin。打开8080注册/登录，停启动验证数据保留：

```powershell
docker compose -f deploy/compose.yaml stop exchange
docker compose -f deploy/compose.yaml start exchange
```

`down -v`会删除数据卷，正常升级不使用。不能把replicas增加为2却共用/data；这不是单写者分区，目录锁应拒绝。bind mount宿主目录要给UID10001写权限；命名卷按镜像ownership初始化。

若镜像拉取失败先检查daemon/镜像源DNS与网络，别误判业务逻辑失败。本项目曾遇在线基础镜像源DNS失败；历史离线runtime验证不能冒充标准在线构建本次已通过。

### 22.3 从零准备云服务器

选择Ubuntu24.04、本地SSD起步，2vCPU/4GiB作为学习预算；资源不代表TPS承诺。创建实例后保存SSH连接方式，安全组只允许你的来源SSH，网页需要80/443；8080/9090不公开。配置域名A记录指向服务器IP，使用Caddy终结HTTPS。

第一次连接：在本机PowerShell运行 `ssh <你的用户名>@<实际服务器IP>`，以后本节Linux命令在**服务器SSH窗口**执行。不要把服务器路径当Windows路径。

构建Linux产物最容易在Linux/WSL独立构建目录完成：

```bash
go mod download
npm --prefix frontend ci
npm --prefix frontend run build
CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server
CGO_ENABLED=0 go build -trimpath -o bin/exchangectl ./cmd/exchangectl
```

服务器架构要匹配，amd64二进制不能直接跑arm64；按目标GOOS/GOARCH构建。完整发布可运行release.sh，但它拒绝覆盖已有同版本产物，使用不含旧bin/releases的独立源码副本，保留历史证据。不要直接拿历史v0.3包当当前源码。

将exchange、exchangectl、前端dist、deploy配置作为一个新版本目录上传。示例本机PowerShell（新建release-local目录并放入这些产物后执行）：

```powershell
scp -r .\release-local deployuser@203.0.113.10:~/exchange-release
```

203.0.113.10是文档示例地址，需替换；上传目录中最终网页目录名设为frontend，不携带node_modules/data/明文密码。若有SHA256SUMS，在服务器先校验。接着SSH服务器：

```bash
sudo useradd --system --home /var/lib/exchange --shell /usr/sbin/nologin exchange
sudo install -d -o exchange -g exchange -m 0700 /var/lib/exchange /var/backups/exchange
sudo install -d -m 0755 /opt/exchange/releases /etc/exchange
# 首次部署使用新路径；已有路径时使用另一个版本，别覆盖正在运行目录。
sudo cp -a "$HOME/exchange-release" /opt/exchange/releases/tutorial-20261012
sudo chmod 0755 /opt/exchange/releases/tutorial-20261012/exchange /opt/exchange/releases/tutorial-20261012/exchangectl
sudo ln -s /opt/exchange/releases/tutorial-20261012 /opt/exchange/current
cd /opt/exchange/current
sudo install -m 0600 deploy/exchange.env.example /etc/exchange/exchange.env
sudoedit /etc/exchange/exchange.env
```

编辑时逐项确认：

```dotenv
EXCHANGE_LISTEN_ADDR=127.0.0.1:8080
EXCHANGE_DATA_DIR=/var/lib/exchange
EXCHANGE_FRONTEND_DIR=/opt/exchange/current/frontend
EXCHANGE_ADMIN_EMAIL=your-admin@example.com
EXCHANGE_ADMIN_PASSWORD=replace-with-your-own-long-password
EXCHANGE_ALLOWED_ORIGIN=https://trade.your-domain.example
EXCHANGE_COOKIE_SECURE=true
EXCHANGE_DIAGNOSTICS_ADDR=127.0.0.1:9090
```

替换邮箱、域名和密码，不用本地pinkode短密码；不启用LOCAL_ADMIN_NAME。EnvironmentFile不是shell脚本，不直接source未知内容。

然后安装服务：

```bash
sudo install -m 0644 deploy/exchange.service /etc/systemd/system/exchange.service
sudo systemctl daemon-reload
sudo systemctl enable --now exchange
curl --fail http://127.0.0.1:8080/health/ready
sudo journalctl -u exchange -n 100 --no-pager
```

systemd负责自启动/故障重启和以exchange用户运行，WorkingDirectory/路径必须对得上。Caddy安装按其平台官方文档，参考 [Caddyfile.example](../../deploy/Caddyfile.example) 设置域名及反向代理127.0.0.1:8080，validate成功再启用。证书获取需DNS和公网80/443实际可达。

最终从自己的电脑打开HTTPS域名，真实登录/双用户成交/重启/备份验收，而不是只在服务器curl一次。没域名可用SSH tunnel暂演示，但HTTP时CookieSecure=false与准确Origin需同步，参考 [部署手册](../05-deployment/deployment.md)。

<a id="chapter-23"></a>
## 23. 备份、故障排查与毕业验收

### 23.1 先写离线工具，再实际练恢复

[maintenance.go](../../backend/maintenance.go) 的实现顺序：OpenExistingStore只打开已有库→InspectStore重放对账→白名单/摘要/同步复制→BackupStore→RestoreBackup→RebuildViews。cmd/exchangectl把它们接成命令行，遇错退出非零。

备份必须停唯一实例且持相同目录锁。checkpoint三库，再固定白名单复制、fsync文件/manifest，记录dataset/engine/水位/数量/表摘要/SHA256。不是运行时随便复制.db；SQLite WAL可能还有新内容。

restore目标必须不存在，验证manifest/摘要再复制到新目录，重放对账通过才考虑切服务。SHA256用于发现字节损坏，不是防攻击签名。坏views可以重建，auth/journal是权威不能当缓存删掉。

rebuild-views先在staging重放/对账，保留坏views/WAL/SHM，再多个rename切换；多个rename不是一个全目录原子操作。普通错误尝试清理自己staging，强杀可能残留，按 [数据生命周期](../05-deployment/data-lifecycle.md) 核对，不凭文件名猜测哪个安全。

### 23.2 在Windows独立目录练一次

先停止对应服务，构建exe，PowerShell最终根目录：

```powershell
go build -trimpath -o bin\exchangectl.exe ./cmd/exchangectl
.\bin\exchangectl.exe check --data data-windows
.\bin\exchangectl.exe backup --data data-windows --backup D:\exchange-backup-20261012
.\bin\exchangectl.exe restore --backup D:\exchange-backup-20261012 --data D:\exchange-restored-20261012
.\run-windows.cmd -Port 18080 -NoBrowser -DataDir D:\exchange-restored-20261012
```

备份和恢复目标必须是新路径；若已经存在，保留旧证据，换个新名字。check会补投影和临时重放对账，不是只读快速检查。恢复启动后核对原身份、资金、订单、dataset和首次结果；原目录仍保留。

云服务器先 `sudo systemctl stop exchange`，离线工具以exchange用户运行，恢复到新目录、对账再改配置，最后start。容器停服务后用同版exchangectl挂同卷，完整命令在部署手册。卷内备份不抵御整盘损坏，要拷到受限异机位置。

### 23.3 遇到错误先定位所在层

| 现象 | 最先看哪里 | 正确动作 |
| --- | --- | --- |
| 编译失败 | 原始错误文件/行号、模块/import | 修字段/路径、装固定依赖，别删报错代码 |
| 网页白屏 | F12 Console、Network、静态dist | 确认同版构建与访问端口 |
| 登录后401 | Cookie、会话期限/停用状态 | 重新登录原身份，保留pending |
| 写入403 | Origin、CSRF、角色 | 修准确配置/身份，不去掉校验 |
| RESULT_UNKNOWN | 原pending与首次按key查询 | 原键原内容确认，禁止新键重下 |
| PROJECTION_LAG | 提交/执行/投影水位与日志 | 等待或修存储，已确认单不是没发生 |
| OVERLOADED | inflight/队列/最慢阶段 | 降流量、测瓶颈，非盲目扩队列 |
| 数据目录锁占用 | 哪个自己实例仍在 | 停旧实例，不能删锁绕过 |
| 坏views | 离线check、journal/auth是否完整 | 保留坏库，离线重建 |
| 权威库损坏 | 备份manifest/对账 | 保留原件、恢复新目录，不跳日志 |
| 云启动失败 | journalctl、权限、二进制架构 | 检查exchange用户可写data与版本 |

本地独立诊断监听127.0.0.1:9090，包含/metrics和标准pprof；业务端口相应路径404。累计count/sum/max不是p99。pprof用来定位CPU/分配/GC瓶颈，不能因方便排错把它公开给所有人。

### 23.4 给自己做一次毕业验收

可以不看源码回答并现场证明以下事项，才算真正完成这个手把手项目：

1. 从空目录解释工具、模块、依赖、HTTP/JSON并写出health。
2. 输入一笔命令，指出日志、核心、回包、投影分别在哪里发生。
3. 当场计算3ETH@105对卖2ETH@100的冻结、价差和撤余量。
4. 演示FIFO/自成交/IOC、市价保护价、订单与资产守恒。
5. 原键重复不重复扣钱，返回对象被修改不污染状态；区分首次Result与最新Order。
6. 注册登录与管理员前后端都能使用，普通用户直接访问管理API仍被拒绝。
7. 页面刷新/断网后保留原请求；min_seq和dataset处理正确。
8. 分页不会漏同一命令多笔成交；WS重连收到新快照并能清理资源。
9. 单元/集成/属性/故障/E2E测试各能说明证明点，记录实际执行而非只有文件。
10. Windows启动、容器卷、云配置、停机备份恢复能按文档操作。
11. 明确当前只有一个核心/一个实例/一个市场，全历史重放与去重增长，无Redis/快照/HA/真实资金。
12. 用测试与具体取舍讲项目，不把计划、历史短时负载或未执行云部署说成生产成绩。

不知道一项就回对应章节补一小步，不用重写所有东西。你做出的不是“记住一套架构词”，而是可以亲手修改、测试、解释的完整模拟交易项目。

### 教程验证说明

本教程代码的实际检查与适用边界见 [2026-10-12 教程验证记录](../reports/2026-10-12-from-zero-tutorial.md)。前半教学代码在隔离目录编译、测试、构建；后半指向最终源码与既有完整测试入口，文档命令不自动代表本轮重跑了所有故障、浏览器、Docker或云服务器。历史报告/发布包继续保留原版本。

## 从零补上 v0.5 的业务闭环

先在教程练习目录完成前面的模拟工程，再在本项目独立钱包模式练习以下步骤，不能把教学 journal 与 chain-journal 混用。

1. 阅读 chaintrade/index.go：创建 events 和 progress 表；手写一个事务，让 INSERT 事件与 UPDATE 游标一起 Commit。思考 INSERT 报错时为什么不能前进游标，运行 TestIndexTransactionFailure 看真实反例。
2. 读取 blockHash 指定的日志。确认深度 2 时 head=10，只记录到 9；从 0 补拉，每轮最多 64 块。比对父块和最后锚点，遇已确认历史变化停下，绝不直接把旧 filled 清零。
3. 阅读 tasks.go，给任务加 version。更新条件 WHERE id=? AND version=?；受影响行数不是 1 就拒绝。旧任务时间没记录应显示“未知”，不能用升级时间伪造历史。运行 TestTaskMigrationAndCAS。
4. 阅读 history.go：第一页先取 MAX 排序键；后续 WHERE key<=upper AND key<after ORDER BY key DESC LIMIT 26，显示 25 条，额外一条判断下一页。钱包/类型/数据集绑定在 base64 游标内，游标只编码查询，不是身份令牌。运行 TestHistoryBoundaries。
5. 打开钱包页面“交易记录”，切换订单/成交/任务/链事件，连接钱包后勾选“仅当前钱包”，从成交打开任务详情；观察 pending 与 CONFIRMED 的区别。
6. 设置回环诊断，访问 /check。对账重新跑一个独立 Engine，读快照水位内日志，再比较所有订单，不只最新100条。TestReconciliationDetectsCorruption 故意损坏临时投影，证明能发现问题，但检查不会帮你自动改钱。
7. 按 web3-deployment.md 加 Prometheus 和告警，采样失败时看 sample_failed，避免把陈旧 gauge 当健康。教程中的断言是正确性演示，不是公网链 TPS 测量。

在项目根运行 `go test -run 'Test(History|TaskMigration|Indexer|IndexTransaction|Reconciliation)' -v ./chaintrade`，预期 PASS；临时数据由 Go 测试自动清理。对应实测与局限见 v0.5 报告。
