# v0.3 当前架构完成设计

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

> 2026-10-12 v0.4更新：本页为保留的v0.3模拟架构，历史容量/发布证据不改写成当前链性能。v0.4新增独立链模式，中间件仅用于新模式；模拟离线CLI不维护链任务。 当前链实现见[v0.4架构](v0.4-design.md)，操作见[开发](../03-development/web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](../05-deployment/web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


日期：2026-10-11。本轮落实已有开发计划 P1–P7：在模拟单市场、单实例、单写者架构内补齐运维、历史访问、观测与验证。真实云主机执行需要可用服务器，快照/Redis/多分区/高可用/真实链上资产仍是 P8 或独立业务扩展。本版不把这些可选项改写成完成条件。

测试完善补充：首次幂等记忆、返回 Order 和核心订单分别保存副本；projector 回包前由外围 `copyResult` 分离全部可变指针/切片，避免调用者修改尚未落库数据。旧 `crash_windows_test.go` 被 Linux 当作 Windows 专用而漏测，本轮改名并实际通过六个精确窗口；当前证据与历史更正见[测试完善报告](../reports/2026-10-11-test-hardening.md)。

## 1. 已有行为与增量

核心 `Engine.Apply` 继续独占账户、订单簿、订单、幂等；decimal、红黑树价档、FIFO、价格保护、自成交取消 taker、资金分录不变。IO、网络、认证、摘要/JSON、时钟、监控均由外围负责。新增静态依赖测试，阻止核心引入 SQL/HTTP/文件/锁或浮点金额构造。

| 原缺口 | 本版落地 | 边界 |
| --- | --- | --- |
| 用户/审计固定上限 | 同契约生成的 UserPage/AuditPage、前端独立分页 | 各页状态是当时状态；审计分 AUTH/CREDIT 来源，不跨库时间排序 |
| 没有完整成交历史入口 | 市场盘口 depth、TradePage 游标历史 | 一个市场；行情 WS 仍为可跳序全量快照 |
| 审计日志易误称成功 | 管理 CREDIT 投影保存 code/replayed/结果 | 未投影请求暂不可见，查询不会争用 journal writer |
| 没有运维工具 | exchangectl init-admin/check/backup/restore/rebuild-views | 停服务获取同一目录锁，离线一致备份；无在线备份 |
| 恢复及投影逐条事务开销 | 有界批投影、恢复跳过已完成前缀/批补落后 | FULL 屏障与整批原子水位不变 |
| 缺少阶段/容量证据 | loopback metrics/pprof、分层 benchmark、开放到达率负载 | 短时本机实验不是最大 TPS/云资源承诺 |
| 故障窗口证据不足 | 测试二进制精确 SIGKILL 窗口、投影回滚、过载与取消 | 不模拟断电/真实磁盘满，生产没有 kill API |
| 工程检查/交付缺口 | verify/release/E2E/container 脚本、CI 文件、充分注释 | 本地检查实测，远程 CI 尚需推送仓库运行 |

## 2. 版本与兼容

OpenAPI/前端版本为 0.3.0。`GET /admin/users` 和 `/admin/audit` 从数组改为 `{dataset_id,items,next_cursor?}`；审计还带 `applied_seq`。前后端必须同版升级。订单页协议保持 v0.2。

新日志含 `schema_version:1`；省略字段的旧日志作为兼容 schema=0。摘要只表示业务内容，排除 schema_version/seq/time；因此旧键在新版再次确认仍返回原结果。未知 schema、输入表 seq 与 JSON seq 不同、摘要错误和不连续日志都拒绝启动；不在半恢复核心上继续运行。引擎业务版本仍为 1。

旧 views 首次增加 credit_audit、projection_metadata；恢复按真实历史结果补 CREDIT 审计，成功后设置 credit_audit_v1 标识。中断可原样再启动，INSERT OR IGNORE 不重复审计。已迁移且已投影前缀不再写投影，缺失后缀按最多 64 条事务补齐；schema/摘要仍逐条检查，整个内存核心仍从日志头重建。

## 3. 分页和审计

用户按 SQLite rowid 倒序 seek，解决 created_at 秒级时间相同导致的排序不稳定；身份仍是随机 ID。首屏固定创建 rowid 上界，之后新增不混入继续翻页。游标含版本/dataset/管理员身份/类型/上界/定位，严格长度与字段校验；SQL 和 RBAC 不信任游标授予权限。每页 1–100，UI 20。

审计保存两个固定上界：认证库 auth_audit ID，投影已应用序号；先遍历 AUTH，再遍历 CREDIT。跨来源边界即使落在同一页也有 limit+1 判断，不重复/遗漏。AUTH 来自认证事务，CREDIT 来自业务投影，单条资金记录与结果/水位同事务；不同数据库没有原子快照承诺。每笔 CREDIT 保留操作者/目标/数量/原因、code 和 replayed：首次成功显示增加资金，原键确认显示重复确认，冲突/业务拒绝显示注资拒绝。

历史成交按投影 rowid 定位；同一命令可能产生多笔成交，单用 seq seek 会漏掉同 seq 的余笔。完整重建投影仍按日志和命令内成交顺序插入，定位稳定；任意旧备份回退不能保证客户端当前历史仍存在。

新增路由：`GET /api/v1/markets/{symbol}/book?depth=1..20`、`/trades?limit=1..100&cursor=...`。盘口返回 Snapshot（trades 为空），成交返回 TradePage。`min_seq` 可等待投影，金额/ID 仍为字符串。管理订单/审计写后查询同样支持 min_seq。

## 4. 有界批投影

Projector 取一个结果后非阻塞收集已经就绪的结果，最多 RuntimeConfig.Batch；不为投影额外等 1ms。按原顺序给每个 HTTP 等待者回包，然后一个 FULL 事务更新整批订单/分录/余额/结果/审计与最终进度。只有整批成功才释放对应在途额度。

批内任意语句失败全部回滚并停机。已经回包的命令仍有先前成功提交的日志；重启补齐。取消 HTTP 只取消等待，不释放可靠工作额度。测试第二条投影失败证明第一条、水位也回滚；背压测试证明超时后的已受理命令仍执行，容量拒绝无日志效果。

## 5. 可观测性与资源预算

`EXCHANGE_DIAGNOSTICS_ADDR` 留空关闭；设置如 127.0.0.1:9090 后独立提供 Prometheus 文本 `/metrics` 与标准库 `/debug/pprof/`。启动强制监听 loopback IP，业务监听器对这些路径返回 404，不经公网反向代理。使用标准格式/标准库，不自写 profiling 或安装新中间件。

计数包括 accepted/overloaded/failures；水位 journal/core/projection 和 projection_lag；队列深度/容量/在途额度；active_orders、orders_retained、dedupe_keys；堆、goroutine、GC；journal/core/projection 累计耗时/次数/最大耗时，恢复秒数。只有固定阶段标签，无账号/订单/key 高基数标签。计时在外围 Apply 调用者中，核心不读时钟；独立原子采样不是业务事务快照，max 不是 p99，端到端百分位由负载脚本计算。

预算配置范围：queue 1–65536、inflight 1–131072、batch 1–4096、batch_wait 0–1s，关闭超时 1s–5min。默认 1024/2048/64/1ms/60s。FULL 不提供关闭选项。diagnostics 只在运行期开放，恢复先完成再监听；冷启动期间连接拒绝代表未就绪，不声称能查询启动中的进度。

## 6. 离线运维与恢复

工具入口：[cmd/exchangectl](../../cmd/exchangectl/main.go)。check/backup 要求三个现有正规 DB 文件，错输目录不会创建空库。全部操作共享 exchange.lock，服务运行时拒绝维护。

- init-admin：密码从 EXCHANGE_ADMIN_PASSWORD 读取，无命令行明文；仅创建新 ADMIN/保留已有 ADMIN，不提升 USER。模拟资金通过原系统幂等命令初始化。
- check：恢复内存/补落后投影；另在临时干净库重放并对订单、余额、档位、成交、分录、结果、资金审计和进度逐表排序计算摘要比较。检测同水位内容篡改，不能仅比较 progress。
- backup：check 成功后 checkpoint(TRUNCATE)，确认无 busy；复制三个 DB 到不存在的 0700 目录，文件 0600/fsync，最后发布 manifest（dataset/engine/水位/数量/投影摘要/各文件 SHA256），同步目录。SHA256 是完整性校验，不是恶意篡改防护签名。
- restore：先验证 manifest/白名单正规文件/字节摘要，再复制到不存在的新目录，重放对账并与 manifest 匹配；保持 dataset 与身份/会话，不覆盖原目录。
- rebuild-views：持原目录锁，只 checkpoint/复制 journal/auth 到 staging 重建；旧投影及 WAL/SHM 移入 views-preserved-时间戳保留，再安装新投影。权威数据不从坏 views 反推，也不删除旧坏文件。

完整备份复制 ID，恢复旧备份仍可能丢失之后业务，工具不提供自动防双主/RPO=0。check 及完整重放会随历史增长，维护应预留磁盘/内存和停机窗口；无快照/历史截断/去重 TTL。

## 7. 退出与验证

SIGTERM 先关闭 WS、关闭业务受理并排空，再结束 HTTP 等待者；Store 在 runtime 和行情采样结束后关闭。WebSocket 由自己的生命周期主动终止，因为标准 http.Server.Shutdown 不处理 hijacked 连接。超时的关闭返回错误，已提交日志由下一次恢复保障。

故障注入是未导出 hooks，由同包测试二进制设置。精确窗口：提交前、提交后未送核心、Apply 后、投影前、投影事务内、恢复时再次 SIGKILL；另验证事务错误、数据损坏/未知版本/日志缺口、目录双写拒绝、备份恢复、WS 关闭、序号耗尽、单笔成交预算及固定随机 seed 资金守恒。

浏览器完整场景包含分页/资金审计、真实 WS 关闭后自动重连、原交易、三种刷新恢复、存储拒绝和行情数据集切换。第一次新测试的文本空白差异与 Chromium offline 不关闭既有 socket 已修正；当前重连验证主动关闭真实 socket，不把它说成全网断网/慢网络矩阵。

性能数据、具体结果和外部环境限制见[本版报告](../reports/2026-10-11-v0.3.md)。交付完成矩阵见[开发计划](../00-overview/development-plan.md)；后续可选 P8 保留独立条件。

## 8. ADR-003：保留 Go 手写边界与紧凑包

背景：v0.2 的 Go 领域 Result 还包含只在内存传递的投影副本，HTTP 使用标准 ServeMux 和严格 decoder；直接把外部生成 DTO 变成核心类型会耦合传输/内部状态。候选是生成整个服务端路由并适配领域、仅生成 TS、或继续双端手写。

决定：当前保留 Go DTO/路由和 fetch，OpenAPI 生成 TS、api:check 比对生成物，kin-openapi 校验真实响应；backend 保持紧凑包，并用静态核心文件依赖测试限制 IO/锁。该选择已经沿用并覆盖新增全部接口，不把初稿的 Go 全生成/internal 目录当当前必须实现范围。

后果：Go 修改仍须同步契约和真实响应场景，TypeScript 类型不能替代运行时权限/金额校验；复杂度增加/更多市场或传输协议时再讨论包拆分与服务端生成。当前验证包括真实响应、类型生成、完整/race 与核心边界检查。

## 后续说明与实用手册

对象所有权修复、故障测试平台文件名更正及完整单元测试见[测试完善报告](../reports/2026-10-11-test-hardening.md)。文档与注释更新见[审阅报告](../reports/2026-10-11-documentation.md)；API/engine/schema 版本未因注释修订而改变。当前手册补齐[接口使用](../03-development/api-guide.md)、[数据生命周期](../05-deployment/data-lifecycle.md)、[故障排查](../05-deployment/operations-runbook.md)。历史发布产物及性能证据保留其原版本。
