# v0.4 后端中间件与链上结算架构

本页保留早期 Kafka 设计；当前 v0.6 的交易与发售均使用 RabbitMQ，配置和实际验证见[当前进度](../00-overview/current-progress.md)、[发售架构](../02-architecture/flash-sale-design.md)及[测试说明](../04-testing/sale-testing.md)。

> 历史版本设计保留；当前链模式新增历史分页、任务 CAS、持久索引、只读对账和告警，见 [v0.5 设计](v0.5-design.md) 与 [执行报告](../reports/2026-10-12-v0.5.md)。本页原版本测试成绩不代表新版本。

2026-10-12：已实现独立链上演示模式，验证结果见[执行报告](../reports/2026-10-12-v0.4.md)。原 v0.3 模拟模式保留：邮箱登录、管理员、模拟资金、GTC/IOC、市价保护、分页、WebSocket 和离线维护继续使用原数据及接口。链模式另起 `cmd/web3server`、`chaintrade`、钱包页面及独立数据目录；两个程序均可服务同一前端构建产物，但分别进入 `/` 与 `/?mode=web3`。

## 业务范围与信任边界

选择链下订单簿、EOA EIP-712 签名限价 GTC、链上两单原子结算。单 EVM 链、单市场、18位标准测试 WETH 与6位标准测试 USDT。原生 ETH 支付 Gas。价格为0.01 USDT的整数tick，数量为0.0001 WETH的整数lot；100 USDT×2 WETH对应10000tick×20000lot=200000000 quote原子单位，base为20000×10¹⁴原子单位。

Go 接入验证输入、签名、余额和allowance；核心安排匹配并预留本地可撮合量。用户资产留在钱包，approve只是许可转账，不是冻结；授权/余额改变可使结算失败。合约再次校验域、签名、方向、限价、过期、filled、cancelled、数量上限及settlementId，按maker价格执行两种代币transferFrom；任一失败整个EVM事务回滚。

指定relayer支付Gas且是合约唯一settle调用者，没有管理员增发/提款入口。平台仍控制排序、接入与活性；合约只能验证双方授权和价格约束，不能证明平台严格FIFO。MockToken公开mint仅用于测试，不是有储备的真实稳定币。模拟注册赠币/CREDIT从未映射到链上资产。

## 组件与所有权

```mermaid
flowchart LR
  UI[钱包页面：签单/approve/cancel] --> API[HTTP：域/验签/预检/有界接入]
  API --> J[外围writer：SQLite FULL日志]
  J --> E[唯一单写者：红黑树/FIFO/数量状态]
  E --> P[外围projector：订单/意图/outbox事务]
  P --> R[Redis：公共查询缓存/共享限流]
  P --> K[Kafka：至少一次分发]
  K --> T[PostgreSQL：任务/raw交易/nonce]
  T --> C[Relayer/RPC/Settlement合约]
  C --> S[receipt确认/活动订单轮询/块锚点检查]
  S --> J
```

核心 `Engine.Apply` 不访问SQL、RPC、JSON、系统时钟、随机数或业务锁。外围生命周期锁协调Submit/Close，目录flock防止本地双写，SQL专用会话锁防止第二relayer；它们不进入撮合核心。队列间交付结构体值副本，SignedOrder只有标量文本，Intent内嵌值对象，没有共享可变订单指针。

writer输入/持久队列/输出各1024；in-flight2048；HTTP签名预检并发16；日志最多64条同一FULL事务；projector逐命令事务。核心总历史最多100000订单，不删除去重记录。State/任务接口最多100项；单笔订单hash查询不受该窗口限制；活动轮询每轮最多200项、历史任务锚点每轮最多100项循环检查。不能将模拟模式的可配置批投影和容量成绩套用此运行时。

## 状态机与请求语义

`quantity = remaining + pending + filled + canceled`，四项非负。PLACE撮合仅从remaining移动到pending，Intent为READY；pending两单暂出簿，一订单最多一项任务。链失败终结两单余量，避免失效钱包生成无限任务；链成功将pending移动到filled，并允许继续撮合余量。maker余量放回档尾，等待期间无法保持原来全局时间优先，这是可说明的简化。

任务进度是 READY → SIGNED → BROADCAST → INCLUDED → CONFIRMED/FAILED。SIGNED须持久化raw、hash、发送nonce后才能广播。RPC广播异常或找不到receipt保留原交易并查询/重发；未确认时不释放pending。Receipt成功还需核对本合约Matched事件的settlementId、两单hash、价格、数量、规范块hash和确认深度。FAILED只来自已达到深度的链失败receipt。

用户取消使用自己的钱包调用cancel，HTTP sync只返回202提示等待周期扫描，不能替别人本地取消。pending和cancel在链上的顺序决定结果；本地INVALIDATE只移动remaining，不回滚已广播任务。

链模式成功HTTP回包发生在FULL日志、核心执行、订单/意图/outbox投影事务之后；它代表本地受理，绝不代表资产到账。取消HTTP等待不会撤销已入队命令。签单hash是ID，重试先验证签名再查询已有ID，过期/余额变化不改变已受理结果。nonce同钱包复用不同内容返回NONCE_CONFLICT。未记录在orders的业务拒绝再次请求仍可能返回拒绝；本版未实现每个拒绝结果永久去重。

## 持久化与中间件

| 数据 | 权威/用途 | 失败与恢复 |
| --- | --- | --- |
| chain-journal.db | 命令、domain/dataset/schema版本、扫描锚点 | 全量内存重放，校验连续seq、签名、摘要、命令种类；版本不兼容拒绝 |
| chain-views.db | 可派生订单/意图、outbox、水位 | 同事务投影；尾部可重放，删除视图需保留任务库且停机 |
| PG chain_tasks/chain_metadata，或显式本地chain-tasks.db | 外部任务、raw交易、nonce、最终块hash、完整域 | 不可当投影删除；域含dataset，拒绝换错库 |
| Redis | 公共State缓存250ms，50次/秒/IP固定窗口限流 | 缓存故障回源；限流故障保守拒绝；固定20位seq比较防回退，水位无TTL |
| Kafka | outbox至少一次投递，单分区/单副本开发topic | SQL唯一任务ID去重，持久任务后commit offset；SQL失败保留原批重试，不Poll跨过失败记录；同topic按dataset过滤 |

settlementId是 `0x + 32位dataset + 32位seq`。随机dataset外围一次持久生成，一条命令最多一个新意图，重放ID不变。Redis/Kafka不裁定资金、余额、订单ID或nonce。

PG专用sql.Conn持会话advisory lock，业务池另一连接运行SQL；发送前检查锁仍有效，锁连接断开不自动重新竞争。此互斥不是跨主机fencing/自动HA。链nonce账户不可由别的程序同时发交易。Kafka发布标记与SQL任务备份必须协调；任务库落后恢复或Kafka记录过期可能丢任务，需人工按outbox、任务和链事实对账，不能自动视为空白新库安全。

## 链确认、恢复与故障

确认深度配置1–128，本地默认2。它是块数策略，不是所有链通用的数学最终性。当前实现是固定确认块hash的活动订单cancel/过期轮询以及receipt跟踪；不是全量事件游标补拉索引器。每轮先验证旧扫描锚点，再持久新块锚点，以块hash查询合约；重启保留轮询进度。浅重组使任务继续pending，复用原交易；已采纳扫描块或最终receipt消失/hash改变停止服务并拒绝ready。

历史receipt按100项循环巡检，检测延迟随历史增长，启动先检查扫描锚点及一批receipt；没有无限瞬时审计保证。RPC暂不可用也可能保守停服务，恢复后先查事实。深重组停机后人工重建和对账，没有自动回滚已终结订单功能。

日志/投影失败封闭接入，保留已持久尾部，下次恢复。任务发送前验证SQL存储的raw交易签名sender、chain、目标、value、nonce、hash和调用数据；坏Kafka消息拒绝消费，不直接广播。日志校验是完整性检查，不是恶意管理员防篡改证明。

## 页面、契约与部署

独立 `api/web3-openapi.json` 生成TS类型。钱包每次写操作重查链/地址，监听切换后断开页面状态；原签单先写sessionStorage，保存dataset/chain/contract并恢复验签。明确400/422拒绝可清除；503、网络错误或数据集变化保留原内容等待核对。最近订单窗口之外使用单笔hash接口确认。

新增Linux host-network容器模板与非root/只读scratch运行镜像，RPC HTTPS包含CA证书；Windows独立依赖脚本保留原模拟一键入口。详见[开发与运行](../03-development/web3-development.md)、[测试设计与操作](../04-testing/web3-testing.md)、[链模式部署和恢复](../05-deployment/web3-deployment.md)。主网、公共测试网、云实例、硬件断电、真实钱包扩展兼容性和合约安全审计未执行；EIP-1271、fee-on-transfer、rebase、跨链、金库、自动HA、严格全局FIFO、批量链结算仍为后续。

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

[从演示架构走向真实业务](../02-architecture/production-architecture.md)对照当前源码分析产品闭环、状态权威、链索引、对账、Tx Manager、可用性与交付门槛，并给出分阶段范围。此分析属于待实现设计，不改变本文已实现状态或v0.4测试结论。
