# 从演示架构走向真实业务项目：v0.5 已落地与后续路线

v0.6 已实现独立限量发售和 RabbitMQ 切换。全项目现状见[开发进度](../00-overview/current-progress.md)，可运行范围见[发售设计](flash-sale-design.md)、[验收](../04-testing/sale-acceptance.md)和[测试](../04-testing/sale-testing.md)。下文 B–D 是交易主线的后续设计，历史报告保留当时成绩。

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

阶段 A 保留 v0.5 协议；v0.6 新增独立发售，Settlement 协议不变。HA、交易替换和公共生产上线仍是后续，不能把已完成本地验收等同生产交付。

项目定位继续保持：主要展示Go后端、高并发与中间件，辅以有真实授权和原子资产交换意义的小合约。推荐先交付一个可长期运行的单链非托管限价交易系统，保留当前模拟模式作教学；先完善单市场业务闭环，再按证据扩容。

## 1. 真实项目应回答的五个问题

1. 用户提交订单后，能否查到受理结果、完整历史、部分成交、费用、失败原因与交易凭据？
2. 系统能否区分“慢”“结果未知”“可重试失败”“业务永久拒绝”，避免删除数据或无限重试才能继续运行？
3. 每种状态的权威在哪里，日志、SQL、消息与链出现差异时，以何种证据对账？
4. 部署、升级、备份、迁移、恢复由谁执行，能否给出可复现的RPO/RTO与演练记录？
5. 容量和可用性指标是否覆盖用户最终结果，而不仅是核心Apply速度？

已有优势包括核心单写者、整数金额、FULL日志、outbox、raw交易持久化、链上原子交换及故障测试。下一版应把这些保证连接成完整产品和运维流程；多服务、Kubernetes、多种中间件的数量本身不能回答以上问题。

## 2. 对照现有源码的具体差距

| 当前实现与入口 | 已完成或现有限制 | 后续工作 | 状态 |
| --- | --- | --- | --- |
| history.go / Web3History.tsx | 四类历史分页、钱包筛选与任务详情已实现；State 的 100 项只是首页窗口 | 按规模评估查询成本，不再把完整历史列为未实现 | 阶段 A 完成 |
| tasks.go | schema 2 迁移、CAS、终态/raw/nonce 保护已实现；仍使用 JSON payload | 显式迁移工具、结构化 attempts 索引、角色最小权限 | A 完成，B 待做 |
| index.go | 持久已确认事件、块锚点、父块与事务游标已实现 | 部署起始块、多合约域与网络确认策略；不宣称已支持发售事件 | A 完成，泛化待做 |
| reconcile.go | 固定水位全量重放及任务/事件/原交易核验已实现 | 备份恢复清单、受控修复计划、规模化增量对账 | A 完成，运维待补 |
| observability.go / deploy | 请求 histogram、索引/任务/outbox/差异指标与规则已实现 | nonce/Gas/分阶段耗时、告警实际送达与负责人 | A 完成，运营待补 |
| cmd/web3server/main.go | 索引与采样已独立调度，结算/活动订单扫描仍同一循环；致命错误停进程 | 按需要拆外围 worker，设计历史查询保活与角色健康 | 部分完成 |
| engine.go | 每订单最多一个 pending，确认后余量档尾重挂；失败取消双方余量 | priority/reservation、有限并行与有证据的失败恢复 | B 待做 |
| chain.go | 单 sender 顺序处理，未知广播复用原 raw；无提价替换 | attempts、有限 nonce 窗口、同 nonce 提价与拥塞背压 | B 待做 |
| middleware.go / messaging | RabbitMQ confirm/手动 ack/持久队列；发售 SQL 隔离、交易死信 | 受控重放工具、生产 TLS/权限/多节点 | 已实现，生产治理待补 |
| 钱包与账户 | 发售一次性登录挑战、Cookie/CSRF、私有资格与 owner 导入 | EIP1271、邮箱钱包绑定、完整运营 UI | 发售已实现 |
| 限量发售 | PG/SQLite 库存、凭证、FlashSale、独立索引/回收与页面 | 防机器人、生产密钥、长期容量与公共链 | 本地验收已实现 |
| 公共链 / 云 / HA | 既有本地链、中间件与容器证据，不覆盖公共环境 | 测试网/云/恢复演练；复制与 fencing 另立专项 | C–D 待做 |
| Windows 回归 | 早期目录同步/CLI、恢复进程、静态路径失败已修复并回归 | 文件 Sync 与 Unix 目录 fsync 的断电语义差异仍需明确 | 当前全 Go 测试通过 |

本表按实际功能而非中间件安装数量判断进度。历史成绩见 v0.5 报告，本轮执行范围见 2026-11-02 报告；未用旧覆盖率、漏洞扫描或压测数字充当新结果。

## 3. 推荐的模块和部署边界

先使用一个仓库和清晰模块接口，可在一个进程启动；模块边界不必立即成为网络边界。业务计算维持单写者，阻塞操作保留外围。逐步形成三种运行角色：交易接入与writer、外围结算/索引worker、只读查询API。

```mermaid
flowchart LR
  U[用户钱包/交易页面] --> A[API：身份/验签/风控/接入预算]
  A --> J[外围日志writer：定序/持久化]
  J --> M[单写者市场核心：订单/优先级/预留]
  M --> P[外围投影：订单/成交意图/outbox]
  P --> Q[查询模型与Redis]
  Q --> U
  P --> K[RabbitMQ业务事件]
  K --> I[SQL inbox与结算任务]
  I --> T[Tx Manager与受控Signer]
  T --> C[Settlement/EVM]
  C --> X[Chain Indexer：cursor/事件/块hash]
  X --> J
  X --> D[Reconciler：跨权威对账]
  I --> D
  P --> D
  D --> O[运维后台：差异/修复计划/审计]
```

模块职责：

- Identity：账户、钱包绑定、会话、运营角色。模拟账户资产与链资产保持独立。
- Market：市场精度、最小额、交易状态和规则版本，变更经有序命令生效。
- Matching：唯一业务状态所有者，处理PLACE/CANCEL/RESERVE/SETTLEMENT_RESULT等确定输入。
- Journal/Projection：外围持久输入、派生查询和outbox，不让SQL进入Apply。
- Settlement/Tx Manager：结算任务、发送nonce、raw、attempts、Gas预算与错误分类。
- Chain Indexer：规范链块/事件、取消事实、最终性水位，不直接修改撮合内存。
- Reconciliation：比较不同权威的证据，产生差异与修复计划；不是另一份资金权威。
- Query/Operations：分页历史、行情、诊断、管理操作与审计。
- Sale：独立活动、资格、库存与凭证；PG 事务是发售业务权威，不能与撮合日志争用同一状态所有权。

上图是交易主线目标分工，包含未完成的 attempts 和修复后台；当前运行图见[进度](../00-overview/current-progress.md)，发售独立路径见[实现设计](flash-sale-design.md)。发售 inbox 已实现，二级任务按稳定 ID 去重。

初期可把API、writer与核心放同进程，Tx Manager、Indexer用不同调度循环，避免同一周期互相耗尽超时。之后先拆查询API和外围worker；跨进程结果必须经持久消息/命令入口和去重，不能靠调用另一进程内存函数。

## 4. 先把业务闭环补齐

### 4.1 用户、钱包与授权

如需把邮箱账户和钱包关联，可采用EIP-4361 SIWE式挑战：服务生成一次性nonce，签名绑定域、URI、chainID、过期时间；验证后原子消费nonce并建立会话。绑定、解绑与权限变更都记录审计，钱包转移控制权时提供可解释的恢复策略。

会话用于个人历史、偏好、通知和管理权限；下单仍需独立EIP-712订单授权。登录签名不能被当作无限额度交易签名。明确链上订单是公共活动，个人历史接口的认证不等于链数据保密。模拟ADMIN和链运营角色分别配置，管理员不得改变用户签名内容或制造链上余额。

### 4.2 产品应展示的业务对象

建议明确区分：Order、Match/Reservation、Settlement、TransactionAttempt、ChainObservation、ReconciliationCase。一个订单可部分成交，多项settlement可对应一个订单；一个settlement可因提价对应多条txHash；事件的observed、canonical、finalized不应混成一个布尔值。

订单状态展示必须可回答：本地已受理、可撮合余量、等待结算量、链确认成交量、取消量、失败原因和关联链凭据。提供分页订单/成交、任务详情、操作历史、市场深度与状态提示；UI不能用“已受理”让用户误以为已到账。

### 4.3 手续费与结算凭据

真实业务常需最小名义金额、费率、Gas成本、平台停牌和任务积压规则。可先统计relayer Gas支出及交易成本，不立即引入复杂手续费合约。若增加用户手续费，签单需约束费率/fee recipient或明确不可变规则，否则平台改变收费可能超出原签名授权；合约、金额守恒、前端显示和签名版本必须一起升级。

非托管模式的用户代币权威在链上，平台记录成交/费用/Gas凭据和必要的运营账务，不凭空创建一份可提现的“钱包余额账本”。只有引入金库、用户负债或托管出入金时，才需要完整借贷复式账本、充值提现与负债/储备对账；这属于另一项资金架构决策。

## 5. 明确唯一权威与恢复协议

| 对象 | 权威 | 派生或传输 | 核对依据 |
| --- | --- | --- | --- |
| 受理顺序、订单/预留状态 | 版本化命令日志＋单写者状态机 | SQL订单查询、Redis行情 | 分区seq、命令hash、完整重放 |
| 交易任务、nonce分配、签名attempt | 结算任务SQL | RabbitMQ投递、页面任务状态 | settlementId、sender/nonce、payload hash、attempt记录 |
| 实际资产交换、filled/cancelled | 按网络策略采纳的规范链状态 | Indexer事件表、确认命令 | chainID、contract、blockHash、txHash、logIndex |
| 账户绑定与运维权限 | 身份SQL | 会话缓存、页面 | 挑战消费记录、权限版本和审计 |

任何缓存/消息重试不能推翻这张表。State的remaining/pending可以确定性重放，但本地预留仍不冻结钱包。独立对账检查：日志seq与投影水位、意图与inbox/task、已发attempt与链nonce/receipt、最终settlement与两单数量、合约filled与本地确认成交量。

建议提供只读 `check`、停机 `backup/restore`、`rebuild-index`、受控 `reconcile-plan/apply` 工具。修复计划记录差异、证据、版本、影响数量、批准与执行结果；补发确认命令或恢复任务须幂等，不直接UPDATE数量绕过单写者。

特别限制：若raw/nonce任务备份丢失，不能只看RabbitMQ或outbox里有Intent，就重新签新nonce广播。先还原原交易证据，或核实链状态与所有原attempt，再制定恢复；证据不足时停止发送。对账不是“查一遍settled=false”就消除旧交易未来可能入链的风险。

## 6. 让撮合与链延迟合理分离

### 6.1 选择可交付的市场体验

当前方案更适合低频、测试资产、可容忍链确认等待的订单交易产品。若目标是交易所级高频且确定可履约，需考虑合约金库/独立资金预留、批次协议或其他不同资金模型；不能只靠单写者和RabbitMQ把公网链确认变快。为了继续“后端为主＋小合约”，优先完善非托管模式的有界预留和失败处理，明确它仍可能结算失败。

### 6.2 预留记录与优先级

建议为每份预留保存settlementId、双方orderId、数量、价格、原始prioritySeq和状态，允许每订单有限项pending任务。保持 `quantity = remaining + pending + filled + canceled`；新匹配不得占用已预留数量。匹配过程中使用外围采纳的链事实，核心不调用RPC。

多个pending会提高链任务排队能力，同时增加取消竞态和履约风险：同钱包跨订单可能争余额/allowance，取消会影响所有未执行任务。必须限制用户/订单/市场pending规模，设置结算积压阈值及钱包风险状态；仅提高并发窗口不能产生钱包真实冻结。

明确FIFO规则：是按原始受理顺序恢复余量，还是失败后重新排队。原prioritySeq可保留用于档内排序，但链外不可用订单何时退出、恢复也要通过命令定序；不能一边恢复档头一边声称全局公平。即使平台实现严格自身顺序，现有合约仍无法证明它没有跳过更早订单。

### 6.3 失败分类

区分链RPC暂不可用、交易未入块、链已确认revert、签单取消/过期、钱包资产不足、合约参数错误和系统数据损坏。链上revert不一定直接说明哪一方应承担责任；若需恢复有效对手单，外围采纳可验证原因和当前事实，再提交确定恢复命令。不确定原因保留待核对，不能把所有失败一律重撮，也不能因钱包RPC读成功就宣称资金稳定可用。

## 7. 把relayer做成可维护的交易管理器

建议持久表至少表达：

- settlements：业务结算、双方订单、数量/价格、状态/版本/原因。
- tx_attempts：sender、chainID、nonce、raw、txHash、payloadHash、Gas参数、创建/广播/入块/确认时间。
- nonce_allocations：发送者维度的分配序列和占用情况；提交任务/分配nonce在本库事务中协调。
- chain_events/blocks/cursors：事件唯一键、块hash/parentHash、规范性、最终性与扫描水位。
- inbox/outbox：事件ID、schemaVersion、分区/seq、消费状态、重试与隔离原因。

从JSON包裹状态逐步过渡到结构化索引和外键/唯一约束，仍可保存原payload作为证据。按状态版本CAS更新，避免多个外围worker把确认状态覆盖成旧广播状态。数据库改动使用显式迁移、兼容窗口、回滚与备份验证，不依赖线上启动自动建表完成升级。

发送可从一项等待改为一个小的nonce窗口，但同sender分配仍只有一个所有者；nonce缺口、网络mempool差异和任务超时必须处理。EIP-1559提价用同nonce、同业务payload生成新attempt，持久新raw后广播；原txHash继续保留并查询，谁在规范链执行以事实为准。

不能把“提价后的hash”覆盖原hash，更不能用新nonce实现同一笔转账重试。一般也不能在未知交易尚可能执行时直接释放pending或随意换一笔不同业务payload。业务settlementId与transaction attempt分别幂等。

密钥可先用受限环境/独立signer模块，再视部署升级外部签名服务或KMS/HSM；需实际验证以太坊secp256k1、签名编码和Gas交易兼容，不因选了KMS名称就默认可用。

## 8. 补全Indexer与中间件故障行为

### 8.1 持久链索引

链范围由chainID＋contract＋部署起始块确定，持久扫描cursor与blockHash/parentHash。分段补拉日志；每批块/事件/cursor同库事务提交，以 `(chainID, blockHash, txHash, logIndex)` 等字段标识观察到的事件，并独立表达canonical/finalized状态。WebSocket只能提示新块，断连后依靠cursor补拉，不作为唯一事实来源。

浅重组回到共同祖先，撤回未终结观察和派生候选，不撤回已经采用的最终业务事实。最终性策略按网络定义，可使用已验证支持的safe/finalized标签或确认深度；不能把同一个数字用于所有EVM链。深重组进入受控故障，保留只读查询和差异记录，继续采用新事实前做恢复计划。

RPC网络超时与“块hash确实改变”应分类：前者暂停采纳并报告lag，必要时停止新单但保持历史查询；后者触发重组协议。多个RPC要先核对链域、规范块与最终性，不能多数返回就随意组合不一致链事实。

### 8.2 RabbitMQ、Redis与SQL各自的业务价值

RabbitMQ 当前负责持久任务分发，outbox/SQL 负责重试与幂等。独立订阅需要独立队列及交换机绑定；不能用已 ack 消息承诺任意历史回放。FULL 命令日志继续是撮合输入权威，消息队列不进入核心 RPC/SQL 热循环。

消息包含eventId、schemaVersion、dataset/market/partition、sourceSeq、correlationId和payload，不把多种业务都放任意JSON。持久inbox吸收重复；格式/域错误先隔离并审计，语法坏消息不使无关服务永久停摆。但如果消息是资金状态必需的连续事实，隔离不能等于跳过该市场seq继续交易，应暂停对应分区并修复。retry/DLQ只有结合状态语义才安全。

Redis维护公共行情快照、会话外围缓存、共享接入预算；资金/nonce不交给Redis。按wallet/IP/身份组合限流，明确可信代理来源，固定窗口若边界突刺影响接入可换令牌桶；请求被缓存命中也仍有接入成本。缓存定义watermark与最大允许落后，写后确认走权威查询；查询API不能每次用fresh回源而宣称Redis已承担主要读流量。

PG持久外围任务、身份、历史/索引/对账，不让撮合核心等待PG。已部署RabbitMQ/Redis不要求核心使用分布式锁。

## 9. 从单机正确性逐步获得可用性

建议先保证安全停止、自动重启、完整恢复及已验证备份，再追求自动主备。当前PG锁不是跨进程写入epoch，也不能阻止旧leader在检查后失联又发送已签交易。

若需要自动切换：命令日志应提供满足业务RPO的复制/共识持久屏障，明确market leader与epoch；只在权威epoch允许下接受新命令和生成结算意图。外部signer和任务库也校验同一所有权版本。单纯增加leader租约或锁检查仍有检查后执行的竞态，必须明确执行端fencing边界。

已经签名的合法交易可能在切主后继续广播，不能靠收回租约令签名失效；它应继续对应持久且不冲突的同一业务任务。稳定settlementId防同任务重复，但不能阻止旧主生成另一个冲突任务ID。若需阻止旧epoch的业务执行，合约或签名执行端须显式支持相应协议，或先证明权威日志/发送流程使冲突意图不可能产生。

按独立市场增加单写者分区，每个partition保持自己的seq/日志/恢复水位；共享钱包资产或金库额度另有跨市场资金所有权问题。一个热门订单簿不能随机分给两个writer提高性能。查询与外围消费者可以先扩容，核心仍只保持一个合法写者。

## 10. 可观测、测试与交付门槛

| 指标或门槛 | 要证明的用户结果 |
| --- | --- |
| 受理延迟/拒绝率，日志提交与投影lag | 用户知道订单是否受理，队列没有无限积压 |
| pending最老年龄、结算最终确认时长/失败分类 | 订单卡住能及时定位到RPC、nonce、Gas或授权 |
| Indexer finalized lag、RPC错误/重组计数 | 本地链事实在可接受落后范围，并能暂停错误采纳 |
| RabbitMQ消费lag、outbox/inbox最老年龄 | 意图可被持久接收，坏消息被处理且无序号跳过 |
| nonce缺口、relayer Gas余额/花费 | 发送者不会因缺Gas或nonce占用无声停工 |
| 对账差异数、恢复耗时、备份年龄 | 不依靠人工删数据恢复，看得见证据缺口 |

为每类指标设明确告警负责人和处理步骤，日志串起orderHash→settlementId→attemptHash；Prometheus标签避免原始订单ID/钱包等高基数，详细身份放受控日志/追踪。trace/时钟/指标采集继续位于外围。

容量测试至少分别记录：不交叉受理、密集撮合、签名验证、任务积压、慢RPC/慢PG、Redis命中/回源与最终链成交。定义数据历史规模、成交比例、并发/RPS、p95/p99、拒绝/未知结果、运行时长、Gas与链确认策略。先测饱和点，再决定分区和批量，不能把纯Apply倒数用作端到端容量。

下一版故障测试应包含：任务库备份落后、坏消息与资金连续性、发送nonce被外部占用、同nonce提价旧hash入块、Indexer掉线补拉、浅重组事件撤回、权限变更、迁移失败恢复，以及长时订单/任务积压。模拟和链测试仍独立；测试网/云执行需新增真实证据，不继承本地Anvil成绩。

## 11. 面向当前项目的实施顺序

| 阶段 | 有限交付 | 验收与收益 |
| --- | --- | --- |
| A：业务与运维闭环，v0.5 已落实 | 链订单/成交/任务分页与详情；结构化任务状态/原因；链索引cursor；对账check；基础延迟/lag告警；SQL迁移 | 老订单可追溯；扫描可补拉；差异可发现；失败无需删库 |
| B：提升持续结算能力 | Tx Manager attempts/有限nonce窗口/提价；预留与priority规则；坏消息隔离及重放；独立外围调度 | 慢链/慢任务不无限拖垮接入；明确链确认与匹配吞吐差异 |
| C：正式测试网与部署证据 | 公共测试网、小额标准测试资产、云运行、备份恢复与故障演练、钱包兼容回归 | 展示真实环境边界和可重复RPO/RTO，而非只有容器启动 |
| D：负载驱动扩容 | 独立查询服务、外围worker、市场分区；必要时复制日志/epoch/fencing | 有明确SLO和压测证据证明需要扩容；先设计一致性再自动HA |
| S0–S4：限量发售已本地验收 | 钱包资格、PG 库存与 outbox、凭证、FlashSale、链索引、安全过期回收 | 独立并发/链故障/回收验证；链上交付后衔接二级交易 |

钱包账户绑定、运营后台和费用模型根据产品体验穿插A/B；金库/托管出入金是另一个专项，不作为本轮基础改造的隐藏依赖。给学生面试项目的合理完成目标是A＋B的选定能力＋C的可复查证据，D可以严谨讲设计而不是无依据地声称全部实现。

v0.5 已完成订单历史、链事实索引与跨系统对账。2026-11-02 新增的发售路线与 B 并行推进：先选固定价标准 ERC-20 与用户自行发送交易，避免把 attempts/平台代付或 NFT 当作首版强依赖。每个阶段单独验收，规划细节不计入现有功能。

## v0.5 对原差距表的落实

原表中的完整历史查询、任务版本、迁移、链索引、只读对账和基础指标已开发。核心仍保持无业务锁，Redis/RabbitMQ/PG 不进入 Apply。链索引仅持久已确认块，因此浅重组通过未确认 receipt 等待处理；深重组停止，不自动回滚最终成交。迁移在独占应用目录/PG 会话 owner 后运行，任务 schema 1→2，日志仍 schema 1。

本次仍没有费用/退款/运营工作流、钱包 SIWE 绑定、交易 attempts 与 fee bump、nonce 窗口、跨实例 fencing、快照和多市场分区。当前最老任务年龄是从入任务库起的端到端等待指标，不等于链广播到确认时长；每 30 秒全量重放对账有资源成本，规模扩展要独立读副本/增量对账。历史分页成员固定上界，状态仍更新，并非长事务跨页快照。
