当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。
历史 v0.4 变更记录(当前增量见页首 v0.5):独立契约api/web3-openapi.json(链服务GET /api/web3/openapi.json);config/state/tasks/单笔hash/orders/sync。金额订单字段为整数文本,数量投影在1e10上限内用JSON整数。POST需X-Dataset-ID与准确浏览器Origin,签名为授权;200/201只本地受理,202 sync等待周期扫描,503保留原签单。生成TS与真实响应测试新增检查。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。
更新:2026-10-11。适用当前 API 0.3.0、单市场 ETH-USDT 模拟账户。字段契约以 OpenAPI ↗ 为准,运行时 GET /api/v1/openapi.json 返回二进制内嵌同版契约。Go 路由/DTO/fetch 手写,TS 类型生成;类型不代替运行时校验。
1. 认证与请求边界#
公开接口为市场、盘口、成交历史、snapshot、stream,以及 live/ready;账户和管理接口要求 Cookie 会话。注册固定 USER;ADMIN 通过启动配置或停机 init-admin 创建,没有默认密码、公开提权或密码重置接口。
注册/登录返回 user/csrf_token/dataset_id,设置 HttpOnly、SameSite=Strict 的 exchange_session Cookie。会话为 24h 绝对期限,不访问续期。密码为 12–72 UTF-8 字节。网页登录 CSRF 只存内存;写请求必须带 X-CSRF-Token。浏览器 Origin 要与服务配置一致;脚本可以无 Origin,但仍须 Cookie/CSRF。代理部署不默认信任 X-Forwarded-For。
当前前端附带 X-Dataset-ID,API 响应也带这个头;业务写请求头与当前数据集不同时返回 409 DATASET_CHANGED。该头用于识别数据集,不是认证凭证;旧脚本省略它仍兼容。GET 请求由前端检查响应数据集,服务端游标也绑定数据集。
2. 一次真实联调#
先按 README ↗ 启动本地服务。以下 Python 示例只向本地服务注册一个新的测试用户,实际增加模拟初始资金并创建/撤销真实订单;它是联调演示,不是生产待确认请求存储器。请用于独立测试数据目录。凭证仅在进程内,不打印密码、Cookie 或 CSRF。
import getpass import http.cookiejar import json import urllib.request import uuid base = "http://127.0.0.1:8080/api/v1" client = urllib.request.build_opener( urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()) ) auth = None def call(path, method="GET", body=None, key=None): headers = {"Content-Type": "application/json"} if auth: headers["X-CSRF-Token"] = auth["csrf_token"] headers["X-Dataset-ID"] = auth["dataset_id"] if key: headers["Idempotency-Key"] = key request = urllib.request.Request( base + path, method=method, headers=headers, data=None if body is None else json.dumps(body).encode(), ) with client.open(request, timeout=15) as response: if auth and response.headers.get("X-Dataset-ID") != auth["dataset_id"]: raise RuntimeError("数据集变更,停止确认旧请求") return json.load(response) auth = call("/auth/register", "POST", { "email": input("新的测试邮箱: "), "password": getpass.getpass("密码: "), }) key = str(uuid.uuid4()) body = {"market": "ETH-USDT", "side": "BUY", "type": "LIMIT", "time_in_force": "GTC", "price": "0.01", "quantity": "0.0001"} first = call("/orders", "POST", body, key) again = call("/orders", "POST", body, key) # 同原键与原内容确认 assert again["replayed"] and again["result_seq"] == first["result_seq"] seq = again["processed_seq"] print(call("/orders?limit=20&min_seq=" + seq)) print(call("/balances?min_seq=" + seq)) # 示例假设这个低价挂单仍处于活动状态;若已成交,撤单返回终态冲突。 order_id = first["order"]["id"] canceled = call("/orders/" + order_id + "/cancel", "POST", key=str(uuid.uuid4())) print(call("/balances?min_seq=" + canceled["processed_seq"])) |
请求异常不会证明未执行。脚本中断后仍需原身份、原 key/body 才能确认,不要直接重新运行示例来重复原操作。实际页面通过 pending.ts ↗ 先保存再发送;恢复语义见下文。
3. 写操作与确认#
| 操作 | 内容与权限 | 成功响应 |
|---|---|---|
| POST /orders | 当前会话账户;market、side、type、time_in_force、price、quantity | 新下单 201,同键确认 200 |
| POST /orders/{id}/cancel | 只能撤当前账户单;无请求体 | 200;终态冲突 409 |
| POST /admin/credits | ADMIN;account_id、asset、amount、reason | 200;重试仍须同操作者/目标/原键/内容 |
| PATCH /admin/users/{id} | ADMIN;明确 disabled 布尔值,不能停用 ADMIN | 200;认证事务提交,不进入业务日志 |
| POST /auth/logout | 当前会话与 CSRF | 200;只注销本会话 |
下单/撤单/注资要求 Idempotency-Key:8–128 字符,只允许字母数字及 -_.,system. 前缀保留。普通交易按 (account_id,key) 去重,同账户跨下单/撤单共享键域;管理员注资由服务端加入管理员 ID 前缀,目标账户是业务命令账户。相同内容规范化后命中首次结果;同键不同内容返回 409。第一次业务拒绝也会记忆,后来余额增加不会把旧拒绝变为成功。
processed_seq 是本次处理的日志位置,result_seq 是首次业务结论位置;同键确认也新增输入 envelope。金额和序号都是字符串,比较序号用 BigInt;前端金额不经 Number。price 最多 2 位、quantity 最多 4 位,MARKET 必须 IOC,price 表示保护价;服务端拒绝指数/符号/前导零/超精度,不静默舍入。
成功表示输入已 FULL 提交并完成核心处理,投影可能尚未提交;订单创建不表示一定成交。GTC 可挂单,IOC 可部分成交并取消余量。管理员注资仅正向模拟资产增加,不提供提现或真实链上转账。
4. 读水位与分页#
| 查询 | 返回与限制 |
|---|---|
| GET /orders、/admin/orders | 页对象 items/dataset_id/applied_seq/next_cursor;limit 默认 100,范围 1–100,页面用 20 |
| GET /orders/{id} | 当前投影订单;不是下单时的首次结果快照 |
| GET /commands/by-key?key=… | 当前账户首次投影结果;found=false 不证明未受理 |
| GET /balances | 当前账户余额数组;与订单请求分别查询,不构成跨请求快照 |
| GET /admin/users | 页对象;创建 rowid 排序,状态为本页读取时的状态 |
| GET /admin/audit | AUTH 后 CREDIT 分组分页;独立上界,不按跨库全局时间排序 |
| GET /markets/ETH-USDT/book?depth=20 | snapshot 字段,盘口 depth 范围 1–20 |
| GET /markets/ETH-USDT/trades | 成交页对象,rowid 游标覆盖一条命令多笔成交 |
投影业务查询可带 min_seq,最多等待 2s,未追上返回 503 PROJECTION_LAG。它要求“至少看见该写水位”,不冻结恰好那个历史时刻,也不增加撮合锁。用户列表来自认证库,不受业务 min_seq 控制。
分页原样 URL 编码 next_cursor,为空即结束;不要手工构造或从别的数据集/账户/接口复用。游标是 Base64 JSON 定位信息,没有加密/签名,权限仍由会话和 SQL 限制。订单首屏固定创建序号上界,后续新增不混入,但原订单状态可变化;不能当成全遍历静态快照。
管理员注资不存在任意目标账户按键查询接口;不确定时重发原 POST,由后端权限和幂等规则确认。
5. 未知结果与错误处理#
| 状态/业务码 | 含义与动作 |
|---|---|
| 400 INVALID_ORDER/INVALID_REQUEST/INVALID_LIMIT/INVALID_CURSOR | 当前请求参数拒绝;修正新操作前先核查是否存在旧待确认请求 |
| 401 UNAUTHENTICATED | 会话过期/停用;恢复身份后继续确认原请求 |
| 403 FORBIDDEN/CSRF_REJECTED/ORIGIN_REJECTED | 权限或浏览器安全校验;当前拒绝不否定先前丢响应请求的效果 |
| 404 ORDER_NOT_FOUND | 当前单笔或撤单未找到;需要区分投影尚未追上 |
| 409 IDEMPOTENCY_CONFLICT/ORDER_TERMINAL/DATASET_CHANGED | 分别为原键内容冲突、订单终态、数据集变更 |
| 422 核心业务拒绝 | 如余额不足/资源预算;结果带两种序号,首次结论已记忆 |
| 503 OVERLOADED | 当前 Submit 未入队或服务不可用;不能否定更早同键请求 |
| 503 PROJECTION_LAG/QUERY_FAILED | 查询未追上或故障;保留已确认写结果,稍后重读 |
| 504 RESULT_UNKNOWN、断网、解码失败 | 写入是否执行未知;只能原键原内容确认 |
接入错误为 {error:{code,message}};已处理业务拒绝同时含 result 字段和 error。前端也把 5xx、401、429、安全校验失败与数据集变更保留为待确认状态,因为它们不能证明先前写未发生。
当前标签页的 sessionStorage 记录按数据集/账户/操作隔离;同步校验后恢复,不保存密码/Cookie/CSRF;存储失败阻止发送,移除失败保留原记录。关闭标签、清存储、换设备没有恢复保证;跨标签页不选主,由服务端幂等保障。数据集变更后停止自动确认旧操作,先核对备份/身份与当前数据。
6. 公共行情与诊断#
WS 地址 /api/v1/stream(HTTPS 用 wss),单市场不需要 market query;消息就是 Snapshot,无 type/market 包装。采样器每 100ms 读取前 20 档与最近 50 笔成交,各连接首次 tick/水位变化发送;写超时 2s 断开。前端初次挂载 REST 拉取一次,重连等待 WS tick,0.5s 至 10s 退避。
同数据集忽略倒退序号,新数据集允许低序号;完整快照可跳过中间序号,不保证浏览器收齐每笔成交。完整历史请用 trades 页接口。最近成交快照同 seq 采用文本 ID 排序,与完整历史 rowid 排序口径不同。
业务端口 /metrics 与 /debug/ 返回 404;诊断独立 loopback 监听且默认关闭,见部署手册与排障手册。
Windows 本地账号登录补充#
显式回环模式下登录 email 字段允许配置账号别名,如 pinkode;仅登录使用 LoginCredentials,注册仍 Credentials 邮箱格式与 12–72 字节密码。响应 user.email 仍为 pinkode@localhost。无本地模式时别名被拒绝。本地初始化支持用户指定八字节密码,权限/会话/CSRF 保持,见Windows 指南。
v0.5 链历史接口#
GET /api/web3/history/orders、/trades、/tasks、/events,参数 limit=1..100、wallet、cursor;返回 dataset_id、seq、items、next_cursor。空游标表示第一页,next_cursor 空表示末页。游标绑定筛选条件,新查询必须重置。GET /api/web3/tasks/{id} 返回状态、原因、时间、版本和两单详情,不包含 raw。GET /check 与 /metrics 只在回环诊断监听,不加入公开业务 OpenAPI。