# v0.2 接口契约与请求恢复

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

> 2026-10-12 v0.4更新：本页为v0.2模拟接口与恢复协议设计记录，主体语义保留。当前v0.4另增链模式独立契约/钱包原签单恢复，不混用模拟幂等键、会话或余额。 当前链实现见[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)。


阅读说明：本页保留该阶段设计/审计背景；当前实现以[总体架构](../02-architecture/architecture.md)、[v0.3 设计](v0.3-design.md)及[测试完善报告](../reports/2026-10-11-test-hardening.md)为准，候选与计划不等于当前交付。

日期：2026-10-11。首版已经形成单写者撮合/模拟资金/日志恢复/注册登录/管理员/真实前端闭环，本版补齐接口一致性、历史订单访问和浏览器未知请求恢复。具体执行见[本版报告](../reports/2026-10-11-v0.2.md)。

## 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](../../api/openapi.json)。JSON 是标准 OpenAPI 输入，字段说明用 description；手写源码继续保留充分中文注释。契约通过 Go embed 随二进制发布，可从 `GET /api/v1/openapi.json` 获取；Docker 构建必须复制 api/ 目录。

生成命令：

```bash
npm --prefix frontend run api:generate
npm --prefix frontend run api:check
```

`api:generate` 生成并格式化 [frontend/src/generated/api.ts](../../frontend/src/generated/api.ts)；文件头说明不可手改。`api:check` 在独立临时目录重生成，再格式化并逐字比较，失败要求同步契约/生成文件。生成 TS 只有类型，无运行时校验或网络依赖；手写 HTTP 请求/超时/error 逻辑在 [api.ts](../../frontend/src/api.ts)。

后端测试使用 kin-openapi 加载/验证契约，并校验真实 HTTP 成功及代表性错误响应。覆盖注册、会话、市场/行情、下单/幂等/冲突/撤单、订单页/单笔/按键查询、管理员、健康探针及公开契约。测试依赖不进入生产热路径。它检验实际字段、类型、必填项和额外字段，但不等于覆盖所有状态码/所有场景，TypeScript 类型也不能替代服务端业务校验。

本次有明确 API 兼容变更：`GET /api/v1/orders` 与 `/admin/orders` 从裸数组变为 `OrderPage`。前后端必须作为同一版发布。余额、用户及审计暂继续返回数组，不能把订单分页能力说成所有查询已分页。

## 3. 订单分页与单笔查询

```http
GET /api/v1/orders?limit=20&min_seq=120
Cookie: exchange_session=<当前会话>
```

```json
{
  "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. 按幂等键查询

```http
GET /api/v1/commands/by-key?key=<原键>&min_seq=<已知处理水位，可选>
```

查询绑定当前会话账户，按 `results(account_id,key,seq)` 索引取最早一条结果。后续重试或不同载荷冲突不会覆盖首次结论；首次拒绝也 `found=true`。查询不往输入日志添加命令，也不触发冻结/成交/注资。

```json
{"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](../../frontend/src/pending.ts)。每种操作（place/cancel/credit）最多一个记录，存储 key 为 `exchange.pending.v1.<dataset>.<account>.<scope>`。value 只保存版本/数据集/账户/原幂等键/固定相对路径/原内容，没有密码、Cookie、CSRF 或角色凭证。

```mermaid
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、密码找回与生产高可用仍保留独立范围。
