# 接口使用与前后端联调指南

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

> 历史 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架构](../07-history/v0.5-design.md)，操作见[开发](web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](../05-deployment/web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


更新：2026-10-11。适用当前 API 0.3.0、单市场 ETH-USDT 模拟账户。字段契约以 [OpenAPI](../../api/openapi.json) 为准，运行时 `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](../../README.md) 启动本地服务。以下 Python 示例只向本地服务注册一个新的测试用户，实际增加模拟初始资金并创建/撤销真实订单；它是联调演示，不是生产待确认请求存储器。请用于独立测试数据目录。凭证仅在进程内，不打印密码、Cookie 或 CSRF。

```python
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](../../frontend/src/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 监听且默认关闭，见[部署手册](../05-deployment/deployment.md)与[排障手册](../05-deployment/operations-runbook.md)。

## Windows 本地账号登录补充

显式回环模式下登录 email 字段允许配置账号别名，如 pinkode；仅登录使用 LoginCredentials，注册仍 Credentials 邮箱格式与 12–72 字节密码。响应 user.email 仍为 pinkode@localhost。无本地模式时别名被拒绝。本地初始化支持用户指定八字节密码，权限/会话/CSRF 保持，见[Windows 指南](../05-deployment/windows-local-run.md)。

## 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。
