历史版本设计保留;当前链模式新增历史分页、任务 CAS、持久索引、只读对账和告警,见 v0.5 设计 与 执行报告。本页原版本测试成绩不代表新版本。
2026-10-12 v0.4更新:本页为v0.2模拟接口与恢复协议设计记录,主体语义保留。当前v0.4另增链模式独立契约/钱包原签单恢复,不混用模拟幂等键、会话或余额。 当前链实现见v0.4架构,操作见开发、测试、部署,证据见本轮报告。
阅读说明:本页保留该阶段设计/审计背景;当前实现以总体架构、v0.3 设计及测试完善报告为准,候选与计划不等于当前交付。
日期:2026-10-11。首版已经形成单写者撮合/模拟资金/日志恢复/注册登录/管理员/真实前端闭环,本版补齐接口一致性、历史订单访问和浏览器未知请求恢复。具体执行见本版报告。
1. 本版范围与架构决策#
| 缺口 | 本版解决 | 保持的业务边界 |
|---|---|---|
| Go/TS 字段手写容易漂移 | OpenAPI 3.0.3 + openapi-typescript 固定版生成 TS + kin-openapi 真实响应校验 | Go 领域 DTO 保留内部投影字段,未生成 Go 路由/完整客户端 |
| 最近 100 单以外无法访问 | 用户/管理员订单 seek 游标分页、单笔订单查询 | SQL 在外围,不能触碰核心状态或用查询余额裁定交易 |
| 超时后无法只读确认 | 当前账户按幂等键查首次投影结果 | found=false 不证明没受理,不能换键盲重下 |
| 待确认请求刷新丢失 | 先写 sessionStorage,刷新后原请求确认 | 每标签页独立,不保证关闭标签/清空存储后的恢复 |
| 数据目录重置后序号下降 | 持久 dataset_id、写入数据集检查、行情分数据集比较 | 不是集群 fencing token,也不解决旧备份丢失已确认历史 |
业务核心 Engine.Apply 不改变撮合、价格/FIFO、结算、自成交或幂等语义;只读能力通过 views.db 扩展。继续使用 Go 有界 channel;不增加 Redis、分区或核心锁。
2. 接口契约#
源文件:api/openapi.json ↗。JSON 是标准 OpenAPI 输入,字段说明用 description;手写源码继续保留充分中文注释。契约通过 Go embed 随二进制发布,可从 GET /api/v1/openapi.json 获取;Docker 构建必须复制 api/ 目录。
生成命令:
npm --prefix frontend run api:generate npm --prefix frontend run api:check |
api:generate 生成并格式化 frontend/src/generated/api.ts ↗;文件头说明不可手改。api:check 在独立临时目录重生成,再格式化并逐字比较,失败要求同步契约/生成文件。生成 TS 只有类型,无运行时校验或网络依赖;手写 HTTP 请求/超时/error 逻辑在 api.ts ↗。
后端测试使用 kin-openapi 加载/验证契约,并校验真实 HTTP 成功及代表性错误响应。覆盖注册、会话、市场/行情、下单/幂等/冲突/撤单、订单页/单笔/按键查询、管理员、健康探针及公开契约。测试依赖不进入生产热路径。它检验实际字段、类型、必填项和额外字段,但不等于覆盖所有状态码/所有场景,TypeScript 类型也不能替代服务端业务校验。
本次有明确 API 兼容变更:GET /api/v1/orders 与 /admin/orders 从裸数组变为 OrderPage。前后端必须作为同一版发布。余额、用户及审计暂继续返回数组,不能把订单分页能力说成所有查询已分页。
3. 订单分页与单笔查询#
GET /api/v1/orders?limit=20&min_seq=120 Cookie: exchange_session=<当前会话> |
{ "dataset_id": "<持久数据集标识>", "applied_seq": "120", "items": [], "next_cursor": "<有下一页才提供>" } |
limit 默认为 100、范围 1–100,页面使用 20。第一屏只读事务先读取投影进度 upper,然后按唯一订单创建序号降序查 seq <= upper、最多 limit+1 行。多出的那一行只用于判断 next_cursor;游标中 before 取本页最后一单创建序号。
下一屏使用 seq <= upper AND seq < before ORDER BY seq DESC LIMIT limit+1。假设首屏可见最高序号 120,返回 120/117/110;之后新增 121,继续翻页查 <110 且 <=120,121 不进入这次遍历。刷新首屏才显示新订单。没有 OFFSET,也不为了下一页进行全表 COUNT。
游标为严格解析的 Base64URL JSON,包含格式版本、dataset、account、all、upper、before;长度上限 1024。未知字段、额外 JSON、非法序号、不同账户/数据集/权限域均拒绝为 400 INVALID_CURSOR。它是定位信息而非授权 token,不加密/签名;篡改为有效边界最多改变自己已授权范围的遍历位置,SQL 的 account 仍来自服务端会话。管理员 SQL 的 all=true 只由受保护入口注入。
orders(account_id,seq) 及 orders(seq) 索引支持对应范围读取。首屏及每个后续页的 items/applied_seq 来自同一事务。固定上界稳定的是订单集合,不是长时间一致历史快照:已存在订单可在翻页间成交/撤单,因此其状态是各页查询当下状态;不保持跨多个 HTTP 请求的长读事务。返回的 applied_seq 表示当前页版本,未必等于首屏 upper。
GET /api/v1/orders/{id} 返回 OrderView(dataset_id、applied_seq、order),支持 min_seq。只允许当前账户订单,他人订单和不存在均为 404。原首次命令结果与当前订单状态的区别必须明确:下单结果可能仍 OPEN,而单笔订单现已 CANCELED。
4. 按幂等键查询#
GET /api/v1/commands/by-key?key=<原键>&min_seq=<已知处理水位,可选>
|
查询绑定当前会话账户,按 results(account_id,key,seq) 索引取最早一条结果。后续重试或不同载荷冲突不会覆盖首次结论;首次拒绝也 found=true。查询不往输入日志添加命令,也不触发冻结/成交/注资。
{"dataset_id":"<标识>","applied_seq":"120","found":false}
|
上面只说明水位 120 的投影没有该键,可能尚未受理、在日志队列中、已提交未执行或已执行未投影。不能因此换新键重发。本版 UI 的“确认”仍发送原键/原内容,核心摘要校验同内容后返回首次结果;不根据 lookup 缺失自动创建新业务。
该接口的 account 范围是普通业务账户。管理员注资内部键为 admin.<actor_id>.<key>,且 account 为目标账户;本版管理员通过原 POST 请求确认,未增加任意目标账户按键查询接口。不能用普通账户查询接口绕开 RBAC 查看他人操作。
5. dataset_id 与旧库升级#
journal.db.metadata.dataset_id 保存 32 字节安全随机值的十六进制字符串,只有新目录或旧库首次升级时生成;重启和只删除投影不会改变它。版本/完整性校验仍执行,损坏标识拒绝启动。随机/SQL 在外围,不修改历史 Command,不改变 engine_version=1 的业务语义。
Auth、Snapshot、OrderPage、OrderView、CommandLookup 返回 dataset_id;HTTP 响应头 X-Dataset-ID 同样提供。已登录前端写入 X-Dataset-ID,服务器发现不同在进入业务/日志前返回 409 DATASET_CHANGED。旧脚本不带此头仍兼容,因此这不是强制保护所有客户端的全局协议。
行情 (dataset_id,applied_seq) 共同表示版本。同数据集只接受不倒退水位,新数据集可以接受更小序号;初始 HTTP 响应不能在已收到 WS 之后覆盖当前流,避免旧数据集响应晚到反复切换。公共行情变更后私有查询检测头不一致,会退出旧身份并要求重登录,不继续等待旧 min_seq。
数据集 ID 不是主节点租约、不提供共享卷多实例协调或跨主机防双主。完整复制/恢复日志也复制 ID:恢复到旧备份可能丢失备份后的已确认业务,不能靠 ID 自动保证那部分历史。回滚/备份仍必须遵循维护窗口、日志耐久与对账要求。
6. 浏览器待确认请求状态机#
实现:pending.ts ↗。每种操作(place/cancel/credit)最多一个记录,存储 key 为 exchange.pending.v1.<dataset>.<account>.<scope>。value 只保存版本/数据集/账户/原幂等键/固定相对路径/原内容,没有密码、Cookie、CSRF 或角色凭证。
flowchart LR INPUT[表单内容] --> SAVE[保存原请求到 sessionStorage] SAVE --> SEND[带 Cookie / CSRF / Dataset 发送] SAVE -->|存储失败| BLOCK[阻止发送并提示] SEND -->|确定成功或业务拒绝| CLEAR[清理记录] SEND -->|断网 / 超时 / 5xx / 身份失效| KEEP[保留待确认] KEEP --> RELOAD[同标签页刷新恢复] RELOAD --> CONFIRM[用户确认原 key / body] CONFIRM --> SEND |
存储恢复在组件初始化同步进行,避免 effect 晚到时用户先下了新单。记录校验当前账户、dataset、版本、键格式、固定操作路径、请求体字段/类型;核心仍负责金额/枚举/权限与摘要裁定。若存储读取或写入失败,停止新写并说明原因,不能假称具有刷新恢复保证。
等待未知结果时下单/注资表单锁住,按钮变“确认原订单/确认原操作”。撤单独立呈现“确认原撤单”,即使原单已结束或不在当前历史页,也能原键确认。确认响应后按 processed_seq 读取,回到首屏显示当前业务结果。存储删除失败时不隐式换键,仍保留记录允许同键确认。
已确定的服务器业务拒绝可以清理;断网、5xx、401、429、CSRF_REJECTED、ORIGIN_REJECTED、DATASET_CHANGED 都不证明先前业务不存在,因此保留。例如原请求已成功但响应丢失,确认重试又被 CSRF 校验拒绝,不能因此删除原记录。登录同一账户可重新恢复;不同账户/不同数据集不会加载旧操作,也不自动删除旧记录。关闭标签页、浏览器清理存储、XSS/篡改、旧备份历史回退不是本方案的耐久保证。没有自动过期淘汰,避免未知执行因为 TTL 到期被当作新订单。
7. 本版验收与后续#
新增 Go 场景检验 23 单遍历期间新增订单无重复遗漏、账户隔离、非法 limit/cursor、单笔订单归属、首次结果稳定、查询不写日志、旧库 dataset 升级与写入拒绝;契约用真实响应验证。
新增 Playwright 先让后端处理再 abort 响应,验证下单/撤单/注资刷新恢复、原 key/body 不变、订单只有一单/资金只增加一次;另测 UI 翻页、存储禁用不发请求、行情同数据集乱序拒绝及不同数据集低序号接受。这些结果以报告实际执行为准,不代表全部故障矩阵、真实断电、容量压测或真实云部署。
后续建议优先加入可重现容量基线与阶段指标,再决定是否需要投影批提交、快照和外围 Redis。Go 自动路由/类型生成、用户/审计分页、线上备份 CLI、密码找回与生产高可用仍保留独立范围。