# 交易撮合演示项目架构设计

本页主体为模拟 v0.3 架构；全项目 v0.6 现状见[开发进度](../00-overview/current-progress.md)，既有链协议背景见[v0.5](../07-history/v0.5-design.md)，已实现业务见[限量发售与秒杀](flash-sale-design.md)。发售的 PG 库存事务独立于无 SQL 的撮合核心；交易和发售的消息传输均已改用 RabbitMQ。

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

> 历史 v0.4 新增独立单写者、pending/finalized 数量状态、可靠 outbox、Redis/PG/Kafka 及 Settlement，见[旧报告](../reports/2026-10-12-v0.4.md)。链模式成功回包须等本地投影，不能套用模拟回包先于投影语义；固定预算、FIFO 简化、链事实轮询与深重组边界保留。当前消息传输以页首 v0.6 为准。


模拟架构历史修订号：0.6（不是应用 v0.6，模拟 API 仍为 0.3.0）；实现基线为模拟 v0.3，主体更新于 2026-10-11，适用范围于 2026-11-02 核对。

用户已授权开发并新增注册/登录/管理员要求。实际认证与权限见[认证设计](auth-design.md)；本页早期演示账户描述被新要求覆盖。当前代码集中在 backend 包；v0.2 增加 api 契约/生成 TS、订单分页/单笔/按键查询、dataset_id 与浏览器请求恢复，见[增量设计](../07-history/v0.2-design.md)。v0.3 完成分页/公共成交历史/离线管理 CLI/指标/性能与故障证据，见[完成设计](../07-history/v0.3-design.md)。快照与分区属于可选演进；Go 自动路由生成暂不采用，契约以生成 TS/真实响应校验保证。

用户追加充分注释要求，已纳入 goal.md/开发规范并落实 Go、前端、测试、脚本和部署配置。现有实现阅读见[代码阅读指南](../03-development/code-reading-guide.md)，实际验证见[报告](../reports/2026-10-10.md)。当前执行细节以 v0.3 增量设计和公开契约为准；下方快照/生产扩展保留独立范围。

测试完善落实响应所有权：核心 Order、首次幂等记忆、对外 Result.Order 三者独立；外围在回包前复制 Result 的指针/切片，使调用者与异步投影各持自己的数据。测试接口/用例/执行清单见[测试手册](../04-testing/testing-guide.md)、[本轮报告](../reports/2026-10-11-test-hardening.md)，其中同时更正上一版 Linux 精确窗口漏收集的问题。

## 1. 目标与范围

面向大三学生的 Go 后端面试项目：能够讲清楚价格时间优先、金额精度、状态一致性、单线程业务模型、持久化与恢复，并用真实接口和故障实验提供证据。原项目仅作为问题分析与业务参考，重新组织实现，不继承其链上转账和共享指针结构。

遵循用户补充的 LMAX 思路：**所有可变业务状态由一个核心 goroutine 独占；HTTP、WebSocket、序列化、磁盘、数据库、日志与监控输出均在外围执行。** 撮合核心不使用 mutex/RWMutex，不访问网络和文件，不依赖当前时间和随机数。

| 第一版交付 | 后续扩展 | 本轮边界 |
| --- | --- | --- |
| Go 撮合引擎、精确金额、限价 GTC/IOC、市价 IOC、撤单、模拟账户、日志重放、REST、实时行情、注册/登录/管理员前后端、测试与部署文档、充分注释 | 快照加速、批量撮合优化、按市场分片、独立数据库或消息总线、链上充值提现 | 本地/容器、短时容量/恢复和精确进程崩溃窗口已验证；云/真实断电需外部环境 |

默认交易对 ETH/USDT；当前代码只开放一个市场，业务由一个核心管理。现货为模拟资产，已支持注册/登录和管理员，使用数据库会话 Cookie；模拟模式不接钱包；独立链模式已接EOA签单与测试代币原子结算，真实托管/出入金未实现。

## 2. 架构总览

```mermaid
flowchart LR
    UI[React 演示页面] --> API[HTTP 接入与严格校验]
    API --> IQ[有界接入队列]
    IQ --> JW[日志写入 goroutine\n定序与批量提交]
    JW --> JD[(journal.db\nSQLite WAL / FULL)]
    JW --> DQ[仅已持久化命令队列]
    DQ --> CORE[单 goroutine 核心\n账户 / 订单簿 / 撮合 / 幂等]
    CORE --> OQ[有界结果队列]
    OQ --> PROJ[投影 goroutine\n先回包，再投影提交]
    PROJ --> ACK[HTTP 结果回传]
    ACK --> API
    PROJ --> VD[(views.db\n订单 / 成交 / 账户 / 进度)]
    VD --> READ[REST 查询]
    READ --> UI
    VD --> HUB[外围行情采样 / WebSocket]
    HUB --> UI
```

三个 SQLite 文件职责不同：`journal.db` 的业务命令表是恢复的权威来源；`views.db` 是可以重建的查询投影；`auth.db` 是身份与会话权威，不能按投影方式删除。SQLite 的物理 WAL 用于原子提交和崩溃恢复，业务命令表用于应用重放；物理 WAL 的 checkpoint 不会删除业务命令历史。

当前 writer/core/projector 三阶段，回包和投影由外围 projector 顺序完成，未另建独立 ResultDispatcher。

不依赖 RabbitMQ、Redis、微服务或自制无锁环形缓冲区。先使用 Go 有界 channel 构成流水线。channel 和数据库底层可能使用同步机制；“去掉锁”准确指核心状态不需要业务锁，不声称整个运行时无锁。一个 goroutine 是一个逻辑写入者，不等于固定在某个 OS 线程或 CPU 核；不设置全局 `GOMAXPROCS=1`，不默认使用 `runtime.LockOSThread`。

### 2.1 组件职责与状态所有权

| 组件 | 所有权与职责 | 禁止事项 |
| --- | --- | --- |
| HTTP 接入 | 请求字节、参数校验、请求关联、接入限额 | 读取或修改核心订单指针 |
| JournalWriter | 命令序号、编码、输入日志事务、持久化水位 | 撮合、冻结资金、忽略提交错误 |
| Engine | 所有订单簿、账户、幂等结果、最后处理序号 | SQL、文件、网络、日志输出、时钟、随机数 |
| 回包阶段（当前合并在 Projector） | 接收不可变结果，回传响应，继续提交投影 | 丢弃成交或订单结果以缓解压力 |
| Projector | 按序更新查询表和 `applied_seq` | 用最终一致查询表做资金校验 |
| HTTP 查询 | 订单/用户/审计/成交有界分页、min_seq、行情一致读事务 | 用旧投影余额裁定交易；宣称独立订单/余额请求为同一瞬间 |
| WebSocketHub | 采样投影、编码和发包、连接生命周期 | 在核心线程执行编码或 socket write |
| Supervisor | 生命周期、异常停止、恢复及外围观测 | 核心发生内部错误后继续处理后续命令 |

跨组件发送的命令和结果按不可变值处理；结果含 ID、金额值、状态和事件；`Result.Order` 允许指向脱离核心原件的副本，不共享核心可变 `*Order`、链表节点或树指针。发送后禁止改写任何共享 slice backing array 或 map。第一版优先显式复制；确认基准后才考虑受控对象池。

## 3. 命令流水线与持久化屏障

### 3.1 处理顺序

1. HTTP 在外围限制 body 大小，解析十进制字符串，验证账户/市场格式和字段组合。无效语法请求直接返回，不进入日志。
2. 取得有界在途额度并放入接入队列。排队容量不足返回 `503 OVERLOADED`，尚未受理的请求没有业务效果。
3. Submit 在外围设置 Timestamp、schema_version 与业务摘要；JournalWriter 单独读取队列，按读取顺序赋予全局连续 seq。接收时间仅展示，不参与 FIFO，未保存名为 received_at 的字段。
4. JournalWriter 将一批带序号命令写入 commands 表的一个 SQLite 事务，使用 WAL 模式和 `synchronous=FULL` 提交。默认上限 64 条或等待 1ms（可配置），仅日志主动等待聚批；投影只合并已就绪结果。
5. 只有提交成功的命令才按序发送到核心队列。提交失败或结果不确定时停止接入和核心推进，由恢复过程核对日志；不能猜测事务成功，也不能跳过序号。
6. Engine 消费命令，完成状态相关校验、幂等、资金冻结、撮合/撤单/释放，生成一个完整 `Result`。
7. 结果分发到可靠投影队列并回传 HTTP。这里成功意味着**命令已持久化且核心已处理完成**，不意味着所有查询表和浏览器已同步。
8. Projector 对一个或一批连续结果开启事务，原子更新订单、成交、资金分录、余额及 `applied_seq`。外围行情线程读取投影并推送全量小型快照。

持久化屏障只控制命令何时可进入核心。核心本身没有等待磁盘 API，但受到流水线吞吐与背压限制；不能把纯内存 benchmark 当成完整请求吞吐。

### 3.2 Go 核心接口示意

```go
// Apply 已实现；ExportSnapshot 为可选 P8 接口示意，尚未实现。
type Engine interface {
    Apply(command Command) Result
    ExportSnapshot() Snapshot // 仅核心持有者调用，返回脱离核心的值
}
```

`Apply` 不接收请求 `context`，不执行外部调用。业务拒绝编码为有类型的结果，例如 `INSUFFICIENT_BALANCE`，不会 panic。外部取消 HTTP 请求仅取消等待，不撤销已经受理的命令。

外围事件循环通过 channel 顺序调用 `Apply`；核心处理函数本身可直接在测试中运行。实现上拆开业务计算和结果传递，不在业务方法中隐藏阻塞 IO。

### 3.3 队列和背压

当前 input/durable/results 三队列默认各 1024、在途额度 2048、batch 64/1ms；队列/在途/批大小/等待可配置，见运行手册。body 16KiB、match 1024、活动订单 100000 固定预算。预算不是吞吐承诺；投影合并已就绪结果同事务 FULL 提交。

队列限制条数；HTTP 限制 body 16KiB，核心限制单命令撮合工作量。内部 Go Submit 是可信调用边界，不额外提供通用命令字节上限校验，禁止无限 goroutine、无限结果缓存和无限等待。在途额度从接入前取得，直到该命令的投影提交后才释放；不能因 HTTP 已回包或断开就提前释放可靠工作额度。日志/核心/投影失败由监督停止接入，重启后依据持久化水位恢复，不沿用旧进程的内存额度。

匹配笔数超过上限时，在任何状态变更前用只读预扫描返回 `MATCH_LIMIT_EXCEEDED`，不允许执行半笔命令后失败。预扫描与执行都在同一个核心调用内，没有中间命令插入。

投影队列是可靠通道，满时结果分发停顿，最终停止核心消费并触发接入背压。已持久化命令继续由日志保障，不能丢弃订单事件。网络等待者断开不会阻塞可靠事件通路；请求关联表和响应 channel 在外围受控清理。

行情为可重建数据：慢客户端只保留最新完整行情快照或断开重连，不积压逐笔动画消息。公平性、超时和拒绝计数在外围观测。

## 4. 金额与市场规则

所有业务金额使用 `shopspring/decimal`，从 `NewFromString` 构造。HTTP 金额字段和持久化金额都是字符串，不走 `float64`；前端输入保留字符串，目前不引入 `decimal.js` 或做结算预估；后续需要预估时选用经过验证的十进制库，服务器为最终裁决者。

默认市场配置：

| 项目 | 第一版规则 |
| --- | --- |
| 市场 | `ETH-USDT` |
| 最小价格变动 | `0.01` USDT |
| 最小数量变动 | `0.0001` ETH |
| 价格范围 | 大于零且不超过 `1000000000000` |
| 数量范围 | 大于零且不超过 `1000000` |
| 内部 USDT 精度 | 6 位，能够精确存储该市场 price × quantity 的所有结果 |
| ETH 精度 | 4 位 |
| 手续费 | 首版为零；引入费用前设计费用账户和舍入规则 |

输入限定普通十进制形式，禁止指数、NaN、Infinity；限制字符串长度与小数位数，拒绝超精度，不静默四舍五入。价格必须是 tick 的整数倍，数量必须是 step 的整数倍。

价档键为经过精确整除和范围检查的 `int64 price_ticks`，此值仅用于索引与排序。价档中的价格、数量和资金仍为 decimal。这样 `"1.0"`、`"1.00"` 进入同一价档，也避免以包含内部指针的 decimal 值当 map key。新市场的精度必须保证成交计价能被资金精度精确容纳，不得热修改已存在日志的精度元数据。

VWAP 当前未实现；后续展示计算候选为 `sum(price × quantity) / sum(quantity)`，只在展示边界按指定精度舍入；不使用 VWAP 参与结算。

## 5. 订单簿与撮合

### 5.1 数据结构与复杂度

每个市场维护两个价档红黑树，复用 GoDS 稳定版红黑树；价档内部使用标准库 `container/list` 保证 FIFO，`map[OrderID]OrderRef` 保存活动订单对应的价档和节点。买盘最大价、卖盘最小价维护为核心私有缓存，价档增删时更新。

| 操作 | 预期复杂度 | 说明 |
| --- | --- | --- |
| 读取最佳买/卖价 | O(1) | 缓存有效最佳价档 |
| 创建/删除价档 | O(log P) | P 为价档数，复用红黑树 |
| 挂入已有价档 | O(log P) 查询 + O(1) 入队 | 可按实测决定是否补价档 map |
| 撤销订单节点 | O(1) 查索引与删节点 | 最后一单导致删价档时另加 O(log P) |
| 吃掉 M 笔订单、移除 L 个价档 | O(M + L log P) | 不包含金额运算成本及安全预扫描 |
| 获取前 K 档 | O(log P + K) 遍历 | 不每次 sort 全部价档 |

不把同价订单用随机时间排序；FIFO 由日志命令序号确定。订单索引只包含活动订单；终态摘要和幂等结果由专门结构保存，历史成交通过投影分页读取。

### 5.2 业务规则

限价买单匹配 `ask <= limit_price`，限价卖单匹配 `bid >= limit_price`，均优先最佳价格，再同价 FIFO。成交价取 resting maker 价格。例如卖盘 `100 × 2`，买入限价 `105 × 3`，成交 `100 × 2`，剩余 `1` 在 `105` 挂单。

| 订单类型 | 规则 | 剩余处理 |
| --- | --- | --- |
| LIMIT / GTC | 到限价范围内立即撮合 | 剩余按本次受理序号挂单 |
| LIMIT / IOC | 到限价范围内立即撮合 | 剩余取消，释放冻结 |
| MARKET / IOC | 必须提供保护价格；买单不高于保护价，卖单不低于保护价 | 剩余取消，永不挂单 |

市价单流动性不足但能够部分成交时，返回成交数量和取消余量；无任何可成交对手时仍返回正常订单响应，状态 `CANCELED`、零成交，`cancel_reason` 为 `NO_LIQUIDITY` 或 `PRICE_PROTECTION`，无冻结残留。接口不使用 panic 表达流动性不足。

自成交采用 `cancel_taker`：预扫描在价格时间顺序中遇到本账户订单，则停止继续扫盘；此前遇到的其他账户订单允许成交，taker 剩余以 `SELF_TRADE_PREVENTED` 取消，不跳过同价 maker，也不改变 resting maker。

### 5.3 生命周期

`OPEN → PARTIALLY_FILLED → FILLED`；活动单可转 `CANCELED`。即时单部分成交后取消仍记为 `CANCELED`，并保存非零 `filled_quantity` 和 `cancel_reason`；校验失败为 `REJECTED`。完全成交后撤单返回 `409 ORDER_TERMINAL`，不存在返回 `404 ORDER_NOT_FOUND`。同一幂等撤单重试返回首次结果，新幂等键重复撤单返回 `ORDER_TERMINAL`。

订单保存 original/remaining/filled/canceled 数量，始终满足：

`original_quantity = remaining_quantity + filled_quantity + canceled_quantity`。

一个命令完成后不能保留交叉挂单：有效 GTC 买盘最佳价应低于卖盘最佳价。同账户相遇的 taker 取消策略也避免交叉簿。

## 6. 模拟账户与结算

只做订单簿而不约束余额会允许无限买卖，因此首版包含最小模拟资金闭环。注册先提交用户到 auth.db，再用 CREDIT 初始化 ETH/USDT；初始化也进命令日志，固定幂等键避免重复启动/登录注资。身份与资金初始化不在跨库事务里，登录会重试补齐中断步骤；详细边界见认证设计。

账户按 `(account_id, asset)` 保存 `available` 和 `frozen`：

- 限价买单冻结 `limit_price × original_quantity`；市价买单冻结 `protection_price × original_quantity`。采取最坏成本资金检查，资金不足直接拒绝，不按可见深度临时放宽额度。
- 卖单冻结 `original_quantity` ETH；买卖双方均不得出现负余额。
- 成交时买方冻结减少 `reservation_price × fill_quantity`，卖方冻结减少 ETH 成交数量；买方可用 ETH 增加成交数量，卖方可用 USDT 增加 `maker_price × fill_quantity`。
- 买方将 `(reservation_price - maker_price) × fill_quantity` 退到可用 USDT。卖出 taker 的价格不参与买方 reservation，买方 reservation 按买方订单本身计算。
- 撤单/IOC 余量/自成交阻止时释放余量对应冻结。校验或预扫描拒绝时不产生冻结和成交。

以 `price=105、quantity=3` 的买单为例，初始冻结 315；在 100 成交 2 后，消耗冻结 210，卖方收到 200，买方释放 10，剩余冻结 105。

核心先验证，再一次性完成命令的业务变更，外部只能看到完整结果。资金变化输出成不可变的账户分录，使用稳定 `(command_seq, entry_index)` ID。每笔成交每种资产的全账户变化相加为零；冻结/释放为同一账户可用和冻结的转移。初始化外部注入使用明确的发行源账户或供应记录，不伪装成交易收入。

## 7. 序号、ID 与幂等

JournalWriter 是全局定序者，序号在事务内连续写入 commands；持久化高水位来自已提交日志末尾，未另设日志进度表，重启恢复后从该位置继续。第一版使用有符号 64 位正序号并在耗尽前拒绝，避免 SQLite 整数边界问题。

新订单 ID 取首次有效下单命令的 `command_seq`，允许因为撤单、拒绝或查询以外的命令产生间隙。成交 ID 使用 `(command_seq, match_index)`；HTTP 的 ID 和序号都编码为字符串，避免 JS 安全整数限制。时间仅用于展示与外围延迟测量，不决定排序。

写接口要求 `Idempotency-Key`，业务幂等键为 `(account_id, key)`，同账户不同写接口也共享键域。外围计算规范化业务载荷摘要，忽略服务器接收时间和本次序号；价格 `1.0` 与 `1.00` 规范化后相同。核心第一次处理保存载荷摘要与完整业务结果；相同键、相同内容返回首次结果，相同键、不同内容返回 `409 IDEMPOTENCY_CONFLICT`。

并发重试可以被记录成多条输入命令，但不会创建多笔订单或冻结两次。每条输入仍产生自己的“处理完成”投影 envelope 以推进序号；重复结果引用首次订单及业务序号。响应区分 `processed_seq`（本次 envelope）与 `result_seq`（首次业务结果）。业务拒绝也被幂等记住，余额改变后希望再试需使用新键。

第一版核心保留全部幂等摘要/结果和必要终态摘要，内存随命令量增长，明确作为演示数据量限制和压测观测项；不偷偷设置过期时间破坏重试保证。长期运行的有界去重方案需设计调用期限和持久化查验，列入后续 ADR。

HTTP 在日志提交后超时，表示客户端不知道结果，不表示命令撤销。`504 RESULT_UNKNOWN` 或网络断开后以相同键、相同内容重试；已经入队的请求若在提交前连接断开，也可能继续被受理。前端不自动换键重复下单。

## 8. 持久化模型、查询与恢复

### 8.1 实际数据表

| 文件 / 表 | 实际内容 |
| --- | --- |
| journal / metadata、commands | engine_version=1、dataset_id；seq 与 JSON payload（schema/摘要/时间） |
| auth / users、sessions、auth_audit | 身份/密码摘要、会话 token 摘要/CSRF/期限、状态审计 |
| views / orders、balances、levels | 订单、精确资产、按 ticks 聚合价档 |
| views / trades、ledger、results | 确定性成交 ID、(seq,idx) 分录、每个 envelope 结果 |
| views / progress、credit_audit、projection_metadata | 单行水位、管理资金执行结论、可幂等迁移标记 |

价格排序、分页依赖 `price_ticks`、序号和复合索引；禁止 SQLite 把金额 TEXT cast 成 REAL 后参与结算。数据库包含变更版本，DDL 由外围迁移执行。

输入日志和投影各自仅一个写入者，当前每库最多一条连接，读写竞争连接；每条新连接设置相应 `foreign_keys`、`busy_timeout`、`synchronous` 等连接级配置。选用实际内嵌 SQLite 已修复 WAL-reset 问题的驱动版本；至少 3.51.3 或官方修复回移版本，记录运行时 `sqlite_version()`。

### 8.2 查询一致性

行情/订单/成交/命令结果从 views 只读事务取得数据及 applied_seq；余额仍返回数组，不与订单请求构成同瞬间快照；用户/认证审计来自 auth。下单返回 `processed_seq=120` 而查询只有 `applied_seq=118`，这是明确可观测的投影滞后。

查询可带 `min_seq=120`。外围最多等待 2s，超时返回 `503 PROJECTION_LAG`（当前响应不含水位），不返回冒充最新的数据。该机制满足“下单后读到自己的写入”，不让查询线程触碰核心。账户是否能下单只由核心余额裁定。

### 8.3 重启恢复

1. 启动时先不开放写接口，执行迁移、元数据和 SQLite 完整性检查；只允许一个应用实例占用同一数据目录，由成熟文件锁库完成外围进程互斥。
2. 读取输入日志，从 1 起依次向新建核心重放，不再生成新序号和时间，不调用 HTTP/链上服务，也不发送历史业务响应。
3. Projector 读取自己的 `applied_seq=N`。重放结果中 `seq<=N` 不再应用，`seq>N` 按序应用；如果投影缺失，从零重建。业务结果的可选摘要用于回归比对。
4. 检查最后核心序号、日志高水位和投影水位一致，验证订单簿、数量与资金不变量后开放 readiness 和接入。

不要求日志和投影做跨数据库事务：投影允许落后而不能超前，缺失部分可由已提交输入重算。去重效果及拒绝结果同样由确定性重放恢复。输入日志不能从查询投影反推重建。

### 8.4 故障窗口

| 故障点 | 恢复行为 |
| --- | --- |
| 命令尚未提交日志 | 不保证受理；事务未提交内容由 SQLite 回滚，相同幂等键可重试 |
| 日志提交成功，尚未撮合 | 重启重放一次业务效果 |
| 撮合后未回包 | 重放恢复业务与幂等结果；客户端同键重试返回首次结果 |
| 核心完成，投影未提交 | 重放补齐未应用 envelope |
| 投影事务中途崩溃 | 表更新及水位一起提交或一起回滚 |
| 投影损坏或缺失 | 备份损坏文件供诊断，停止服务，从输入日志重建 |
| 输入日志损坏、提交状态不确定 | 停止写入，保留原始文件，完整性检查和备份恢复；不自行截尾或跳过交易 |

`FULL` 提交的耐久性依赖本地文件系统和存储对同步写的正确实现；本地磁盘损坏仍需备份。`kill -9` 只能验证进程崩溃窗口，不能声称完成真实断电验证。

### 8.5 快照（第二阶段）

第一版保留全部输入，从头重放提供最小可靠闭环。达到恢复耗时目标后再实现快照：核心在两个完整命令之间导出不含共享引用的状态副本，外围编码与持久化；副本包含最后处理序号、市场配置、活动订单及 FIFO、账户、幂等和终态摘要。

外围快照文件包含版本、序号和校验摘要，完成写入、fsync、原子重命名和父目录同步后才发布 manifest。快照失败保留上一个快照并继续保留日志。首版快照不删除输入历史；未来压缩需同时证明恢复、幂等、审计和备份覆盖。复制可能暂停核心，必须记录暂停时长，不能宣称快照完全无成本。

## 9. REST 与 WebSocket 契约草案

v0.3 契约以 api/openapi.json 为源，生成 TS 并以 kin-openapi 校验真实响应；Go DTO/ServeMux/fetch 保留手写。表中业务路由均已实现；metrics 位于独立 loopback 诊断监听，业务监听返回 404。用户/审计也已分页，详见[完成设计](../07-history/v0.3-design.md)。

| 路由 | 用途 |
| --- | --- |
| `GET /api/v1/markets` | 市场精度与规则 |
| `POST /api/v1/orders` | 下单，必须有幂等键 |
| `POST /api/v1/orders/{id}/cancel` | 撤单，Cookie 会话账户与幂等键 |
| `GET /api/v1/orders` | 当前会话账户订单页，limit/cursor/min_seq |
| `GET /api/v1/orders/{id}` | 单笔订单及当前投影水位 |
| `GET /api/v1/balances` | 当前会话账户余额 |
| `GET /api/v1/markets/{symbol}/book?depth=20` | 聚合价档，限制 depth |
| `GET /api/v1/markets/{symbol}/trades?limit=50` | 成交，限制 limit、稳定游标 |
| `GET /api/v1/commands/by-key?key=...` | 当前会话账户首次投影结果；found=false 不证明未受理 |
| `GET /api/v1/stream` | WebSocket 全量行情快照 |
| `GET /health/live`、`GET /health/ready` | 进程和恢复就绪状态 |
| `GET /metrics` | 独立 loopback 诊断端口，业务端口返回 404 |

下单示例：

```http
POST /api/v1/orders
Idempotency-Key: demo-a-buy-001
X-CSRF-Token: <登录返回的csrf_token>
Cookie: exchange_session=<会话凭证>
Content-Type: application/json

{"market":"ETH-USDT","side":"BUY","type":"LIMIT","time_in_force":"GTC","price":"2500.00","quantity":"0.1000"}
```

响应的 `order` 对象含 `id`、状态、数量分解，另含 `processed_seq`、`result_seq` 和 `replayed`。新建订单返回 201，幂等重试返回 200；即时部分成交并取消属于已成功处理的订单响应。统一错误 envelope：

```json
{"error":{"code":"INSUFFICIENT_BALANCE","message":"USDT 可用余额不足"},"processed_seq":"120","result_seq":"120","replayed":false}
```

语法错误 400，未登录 401，权限/CSRF/Origin 拒绝 403，核心业务拒绝含资源预算为 422，幂等/终态/数据集冲突 409，不存在 404，认证频率限制 429，接入/WS 容量与投影故障为 503，受理后等待超时 504；恢复完成前尚未监听，不能假称恢复期一直能返回 503。日志前错误没有业务序号。当前空买卖盘以 `bids:[]`、`asks:[]` 表示，不返回伪造的零价订单。

撤单先通过服务端会话认证，再由核心检查订单归属，避免误撤其他账户；两层保证各司其职。

外围采样器每 100ms 从一个投影读事务生成 `Snapshot`，字段直接为 dataset_id、`applied_seq`、前 20 档和最近 50 笔成交，没有额外 `type/market` 包装。连接通过定时 tick 读取最新采样快照，首次发送及水位变化时发送；前端首次挂载另外请求 HTTP snapshot，WS 重连等待最新 tick，不保证立即 REST 拉取。快照序号允许跳跃，客户端在同 dataset_id 丢弃旧快照，新 dataset_id 接受低序号；不设计增量 delta 的连续性协议，也不承诺浏览器收齐每笔成交，当前订单 REST 已支持游标，成交历史/用户/审计分页已完成。采样器整体替换最新快照，各连接不积压逐笔事件；网络写超时 2s 后断开。快照内同 seq 成交按文本 ID 排序，完整成交历史另用 rowid 游标，不能假称文本 ID 是数字下标倒序。

## 10. 前端设计与联调

React + TypeScript + Vite；`gsap` + `@gsap/react`，按 frontend-design、gsap-core、gsap-performance、gsap-react 技能约束落地。用户要求中的 `gzap-skills` 按 GSAP 动画技能理解。

使用已建立的 IBM Carbon White 配色，直接引用既有 token：背景 White `#ffffff`、分区 Gray 10 `#f4f4f4`、边线 Gray 30 `#c6c6c6`、正文 Gray 100 `#161616`、操作 Blue 60 `#0f62fe`、错误 Red 60 `#da1e28`、成功 Green 60 `#198038`。颜色服务操作与交易状态，不另创调色板。后续对具体文字/底色组合检查对比度，买卖含文字标识，不只靠红绿颜色。

禁止渐变和圆角方框，所有控件与面板 `border-radius:0`；用直线分隔的紧凑交易工作台。IBM Plex Sans/本地中文无衬线作为界面文字，IBM Plex Mono 作为价格数量字体，数字右对齐且使用等宽数字。

```text
ETH / USDT                         演示账户 A     已连接
──────────────────────────────────────────────────────
盘口                         下单                  余额
卖价 / 数量                  买入 / 卖出          ETH
最佳卖价                     限价 / 市价          USDT
最佳买价                     价格 / 数量
买价 / 数量                  买入
──────────────────────────────────────────────────────
当前订单：价格 / 数量 / 已成交 / 状态 / 撤单
──────────────────────────────────────────────────────
最近成交：时间 / 价格 / 数量
```

小屏按下单、盘口、订单、成交顺序堆叠；保留键盘焦点、label 和错误关联。界面文案简短：价格、数量、可用、冻结、买入、卖出、撤单、已连接；架构术语和日志水位放开发文档，正常页面不展示实现细节。

GSAP 只用于必要的行情变化提示和面板进入，150–250ms 候选时长；优先 transform/opacity，盘口量条使用 `scaleX` 而非 width。批量刷新 DOM，动画只作用于可见项；频繁同属性变化复用 quickTo/覆盖旧 tween。通过 `useGSAP` 作用域和 `contextSafe` 管理交互动画及清理，`matchMedia` 尊重 reduced-motion，不常驻无限动画或给全部节点设置 will-change。

开发用 Vite 代理 `/api` 和 WebSocket，生产由 Go 静态资源服务或反向代理同源分发。写操作先存 sessionStorage 保留原内容/稳定键直到明确结果，同标签页刷新可恢复；成功后查询携带 `min_seq`，遇到投影滞后显示“更新中”。交付时记录真实浏览器下单、成交、撤单、余额变化、断线重连证据。

## 11. 工程结构

```text
cmd/server/                 服务装配、诊断与生命周期
cmd/exchangectl/             离线初始化/检查/备份/恢复/投影重建
backend/engine.go、types.go  单写者核心与领域值
backend/runtime.go          提交屏障、队列、监督与排空
backend/store.go、query*.go  持久化投影和查询（另有 admin/market_query）
backend/auth.go、http.go     身份/权限与接入，observability.go 诊断
backend/maintenance.go      离线运维与对账
api/openapi.json            嵌入契约，生成前端类型
frontend/                   React 工作台、生成类型、真实浏览器测试
scripts/、deploy/           验证/性能/打包与云/容器配置
.github/workflows/          待推送运行的 CI 定义
docs/                       设计、规范、实验、部署和面试
```

采用紧凑 backend 包以保持学生项目可读；静态核心依赖测试限制核心文件引入 IO/锁，运行时所有权仍与目录名字无关。没有把初稿中的 internal 多目录拆分当成必须重构工作。

## 12. 性能、演进与验收

先证明正确性，再测性能；重点报告纯核心吞吐/分配、日志提交延迟、端到端 p50/p95/p99、各队列深度、投影滞后、恢复时长及内存。初步场景目标为 100 命令/秒下可顺畅演示，端到端 p99 小于 100ms，10 万命令重放小于 30s；本版已取得短时 100/500/1000 请求/秒和 10万命令恢复证据，见报告；不对外承诺最大容量/百万 TPS。

可用 group commit 摊销同步写，但始终保留持久化屏障；应用队列解耦并不会消除磁盘瓶颈。若 profiling 证明 decimal 或 GC 为瓶颈，记录优化实验，不能未经讨论就替换用户指定的金额模型。按市场并行需要先解决跨市场共用资金的分区，不简单多开 goroutine。

单机容量估算、Redis 外围优化候选、多单写者分区及生产系统差距的深入说明见[详细面试 Q&A](../06-interview/interview-qa.md)。模拟模式未接Redis；链模式已接Redis缓存/限流，分区仍未实施；单机容量与恢复现有分层实测，边界见本版报告。

验收包含精确金额、价格时间顺序、可成交限价单、流动性不足正常返回、同键并发只生效一次、撤单和撮合竞态、恢复及投影重建、资金守恒、真实前端 API 调用、云服务器和容器两种路径。详细方案见[测试设计](../04-testing/test-design.md)、[部署设计](../05-deployment/deployment.md)。

## 13. 当前已采用决策

| 决策 | 建议 | 理由 |
| --- | --- | --- |
| 单写者粒度 | 全局一个核心 goroutine | 订单簿和共享账户同时消除业务锁 |
| 第一版资金 | 模拟 ETH/USDT，零手续费 | 可独立运行，交易和恢复闭环清晰 |
| 输入持久化 | 外围 SQLite WAL 日志库，FULL 批量提交 | 复用成熟事务与崩溃恢复，不自制日志文件格式 |
| 查询持久化 | 独立可重建 SQLite 投影 | 核心不做查询 IO，允许明确最终一致 |
| 快照 | 第二阶段实现，首版从头重放 | 先减少恢复协议复杂度 |
| 行情协议 | 小型全量快照，REST 查完整历史 | 前后端联调可靠，避免增量漏包协议扩大范围 |

用户已授权连续实现；当前选择已落地。后续业务或取舍变更仍须同步设计与验证，不把可选 P8 作为已实现能力。

## 文档一致性补充

实现中的核心规则由 engine_version 与编译期常量共同约束，并未把可热改市场规则保存成配置表。成功响应前已 FULL 提交输入并 Apply，响应与去重/投影各自拥有独立对象；额度释放要等投影整批提交，详见[阅读指南](../03-development/code-reading-guide.md)。

实际 HTTP 状态、游标、数据集与未知结果处理见[接口使用指南](../03-development/api-guide.md)，权威数据、离线重放成本与恢复限制见[数据生命周期](../05-deployment/data-lifecycle.md)。最近正确性成绩见[测试完善报告](../reports/2026-10-11-test-hardening.md)；历史 v0.3 负载数字不能替代修复后性能复测。

## Windows 本地运行增量

新增原生 Windows 一键构建/启动工具及回环本地管理员别名；变更仅在外围身份/配置/前端登录，不改变单写者核心、日志、资金与投影。常规密码规则保持，显式本地初始化允许 8–72 字节并约束回环；别名仍对应规范邮箱身份。设计与验证见[Windows 说明](../05-deployment/windows-local-run.md)与[报告](../reports/2026-10-11-windows-launcher.md)。

## 面向真实业务的后续架构评估

[从演示架构走向真实业务](production-architecture.md)对照源码分析产品闭环、状态权威、链索引、对账、Tx Manager、可用性与交付门槛。阶段 A 已在 v0.5 完成，B–D 仍待实现，发售已在 v0.6 落地；本页模拟模式协议不因此改变，历史测试结论保留原日期。

## v0.5 外围模块边界

撮合继续走 FULL 日志→纯 Apply→投影/outbox；index.go 维护已确认链事件，reconcile.go 重放独立 Engine 检查全量快照。索引、结算、采样各自调度且可停止，均不取得运行核心指针。事务只能在一个库内原子，跨库依靠幂等和延迟分类。

独立读池：日志/投影的 WAL 读取与唯一写连接分开，每读池1连接；SQLite读池query_only，PG任务Reader独立1连接，owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令，避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本，需要超时和后续增量策略。
