跳到主要内容

接口变更清单

适用范围：链读写与读侧接口（历史检索、实时行情、K 线、排行榜、/info 等）统一由同一节点 提供，本文汇总由此产生的全部对外接口变化。生产域名 https://rpc.auroran.io 与 https://api.auroran.io 指向同一套链节点接口，功能完全一致，可任选其一。 §9–§11 记录 zepto-server 链外运营接口（市场分类），基址 https://admin.auroran.io/api/，见 链外运营。本文是变更总清单：逐项列出「变前 → 变后」，破坏性项给出迁移指引。 未列出的端点、字段、枚举与协议视为不变（见 §7）。

8. 2026-08-24：可选 market_id 精确寻址 + 市场生命周期语义定案（增量）​

链节点升级生效（additive / 语义澄清，无破坏；所有旧请求字节不变）。

8.1 查询接口新增可选 market_id 参数​

getUserFills / getUserFillsSince / getLiquidatablePositions 新增可选 market_id； getMarket / getOrderbook / getRecentTrades / getCandles 原本已支持。

语义：携带 market_id 时优先于 symbol，可精确到已下市市场的历史（按 id 永久保留）； 仅 symbol 时解析到当前活市场（跳过 Delisted，重名场景取未下市最小 id）； 两者皆无 = 不过滤。不传 market_id 的旧请求行为与之前完全一致。

8.2 CreateMarket 自动追加 market_id​

请求 id 已被占用（含已下市市场）时不再报 MarketAlreadyExists：有效 id = max(请求 id, 现有最大 id + 1)，自动顺延，旧条目永不被覆盖。MarketAlreadyExists 仅剩「同一 symbol 已有未下市市场」场景。

8.3 Delisted 为标记性下市（ADR-0034）​

  • CompleteDelist / CancelMarket 只标记 Delisted，市场条目保留；market_id 不复用。
  • symbol 可重名：下市释放 symbol，重上同一产品用新 id。
  • getMarkets / getAllBBOs / getAllMarks 均不含 Delisted（不变）。
  • Filled 事件补文档：4 个 source 字段（taker/maker_source_trigger_id / taker/maker_source_tx_hash）标识触发来源。

7. 2026-08-18：撮合清算拒因与 reduce-only TIF（行为变更）​

链节点升级生效（属 STF 行为变更）。JSON-RPC 方法、Action wire、字段名不变；同一路由下部分成交/拒单结果会变。

7.1 新增 / 路径变化的 RejectReason​

变体变前变后
DustNotionalFill无此标签；qty>0 且 notional 截成 0 仍可能成交整单 kept-reject（unit 变体，无 payload）
FokRejected主要出现在 RuntimeReject.engine_reasonreduce-only FOK 盘口不足但仍有可平量时，走 Core::Rejected / result.reason
ReduceOnlyWouldOpenOrFlip文档常写作 ReduceOnlyRejectedwire 主标签为此名；仓位不够平的 FOK 仍用此因，不用 FokRejected

7.2 reduce-only 下单语义​

  • GTC：按可平量截成交，多出来的不挂簿。
  • IOC：空簿或部分成交 → OrderDone(IocExpired)（不再出现无 OrderDone 的幽灵挂单）。
  • FOK：见上表。

深度档位 qty 仍为该字段名，语义为 remaining 合计（非原始下单量）。

7.3 升级注意​

有交易历史的 journal 不能用新二进制无缝重放（state_root 可能对不上）。空链 / 仅 genesis 可升；已有账本视为隐式硬分叉，需清 journal+state 或重置链。节点须同步升级。客户端：补 DustNotionalFill；FokRejected 须能从 result.reason 解析，不能只认 RuntimeReject。

6. 2026-08-15：安全加固 + 读接口语义统一（批量）​

链节点升级生效（读接口变化 + 节点间协议变化；无状态格式变化，重置链部署无需迁移）。

6.1 JSON-RPC 读响应骨架​

  • result 新增 chain_height（链 tip）与 stale（height < chain_height）； result.height 语义从「index 快照高度」改为「本包数据高度」：历史分页端点 （getRecentTrades / getUserFills / getCandles / getAdminAuditLog）报 explorer 水印， 不再恒等于链 tip。

6.2 分页​

  • 分页 page 新增 next_cursor / has_more；请求参数新增可选 cursor （keyset 游标，getRecentTrades 支持；优先于 offset，深翻页不再吞行/重复）。

6.3 健康探针​

  • GET /api/v1/health：503 条件扩大为 halted / 回补中（recovering）/ state store dirty（degraded）；响应新增 store_dirty；status 新增 degraded 取值。
  • 新增 GET /api/v1/health/live（存活探针）：halt 才 503，回补/dirty 仍 200。 建议 k8s readiness → /health、liveness → /health/live。

6.4 WebSocket​

  • 每帧新增 seq 序号；新增 gap 帧（{"type":"gap","seq":N}，推送积压丢帧 时下发）。客户端收到 gap 应重连并重拉 HTTP 快照。
  • book.{symbol} 或 book.{symbol}.0 的深度语义从「无限」改为「默认 50 档」； 显式 depth 上限 500。

6.5 限流 / 超时 / batch​

  • /api/v1/action：per-IP 50 rps、per-signer 20 rps 限流，超限回 -32000。
  • /api/v1/query：单请求 10s 超时（含排队），超限回 -32000；batch 超过 20 条整批 回 -32600。

6.6 节点间 / 部署​

  • P2P join 协议增加 nonce + ed25519 签名（同版本二进制自动完成）；
  • config.json 新增可选 internal_bind（Leader）与 bootstrapper.join_address （Follower）：缺省兼容旧配置；配置后 join 路由仅走内网 listener。

5. 2026-08-14：symbol 解析跳过已下架市场（重上同名 symbol 可交易）​

行为变更（链节点升级生效，属 STF 变更）：

  • 写侧 symbol → market_id 解析跳过 Delisted 市场：下架后重上同名 symbol， 按 symbol 的交易/管理动作落到最老的未下架市场（最小 market_id）；若该 symbol 全部同名市场都已下架 → symbol 解析失败（客户端 MarketNotFound 语义）。
  • DelistPending 不跳过：公告期仍需按 symbol 减仓 / 撤单 / 清算。
  • 读侧（getMarket / getOrderbook / getRecentTrades / K 线 / WS 订阅 / explorer）同规则：下架市场只可经 market_id（getMarketById）访问；全部下架 时 symbol 点查返回 not-found。getMarkets 列表本就过滤 Delisted，不受影响。
  • 升级注意：共识行为变更，节点需同步升级（无状态格式变化，无需迁移/清链）。

4. 2026-08-14：下架不再强制等待 24h 公告期​

行为变更（链节点升级生效，属 STF 变更）：

  • RequestDelist / CompleteDelist 流程保留，但 CompleteDelist 不再校验 24h 时间锁：管理员签名后可在进入 DelistPending 后任意时刻强制清退（撤全部挂单 + 残余持仓按 mark 强平）并封存市场。
  • 删除 DelistTimelockNotElapsed 拒绝原因（kept-reject 枚举中不再出现）。
  • delist_requested_at_ms 字段保留，仅作审计 / 运营展示信息，不再参与放行校验。
  • 升级注意：本次为共识 STF 变更（错误枚举 / 状态语义），节点需同步升级；旧节点 仍会以 24h 时间锁拒绝提前 CompleteDelist。

3. 2026-08-14：硬切删除报价序号 —— 改为时间单调校验​

不兼容历史：一次性彻底删除 SubmitOracleQuote 的 sequence_id 机制 （含 OracleQuote.sequence_id、MarketStats.last_quote_seq、 MarketStateSnapshot.quoter_last_sequence、QuoteSequenceNotMonotonic 拒绝原因）。 升级需清空链数据重新初始化（快照版本 8→9、state store schema 3→4；STF 与 签名动作 wire 均变更）。

3.1 校验变更（链节点升级生效）​

  • SubmitOracleQuote 不再校验序号；改为时间单调：source_ts_ms 不得早于 上一笔被接受报价的 source_ts_ms（>= 放行，同一毫秒顺序由入块顺序决定）， 否则拒为 QuoteTimeNotMonotonic。
  • 超前时间戳在提交时严格拒绝（QuoteSourceTooFuture）：source_ts_ms 比 区块时间超前超过链级常量 MAX_QUOTE_AHEAD_MS = 13_000ms（13 秒）即拒，杜绝 未来时间戳抬升 last_quote_ts 或掩盖块末 stale 自动暂停。
  • 保留原有 max_quote_lag_ms 新鲜度、min_quote_interval_ms 间隔、 max_quote_change_bps 幅度、价格界与 spread 校验。
  • OracleQuoteAccepted 事件、OracleQuoteResponse、external_quote WS 推送、 getMarket 详情全部移除 sequence_id 字段；getMarket 也不再返回 quoter_last_sequence。
  • 删除 OracleQuoteRejected 事件与 OracleQuoteRejectReason（单笔/批量拒绝在 回滚路径下该事件不可能存活，拒绝信息由 Core::Rejected / BatchItemRejected 承载）。QuoteRejectStorm 改为批量路径在子项回滚点之后 累计拒绝计数，连续 5 次被拒真正触发风暴告警（此前计数被回滚撤销、永不生效）。

3.2 报价服务行为（zepto-server 升级生效）​

  • 删除全部序号初始化 / 补种 / 重同步逻辑：直接以当前毫秒时间作为 source_ts_ms 提交，链上以时间为权威。
  • 提交回执中被拒的子项（BatchItemRejected）不标记为已推送，下一周期用更新 的时间戳自动重试；原因写入日志。
  • 时间单调校验下「旧实例/时钟回退提交更早报价」会被链上直接拒绝，市场不会再 因报价时间被拖回而过期自动暂停。

2. 2026-08-14：Halted 分因 halt_reason 与报价自动恢复​

背景：此前「管理员 HaltMarket 暂停」与「块末报价过期自动暂停」都落在 lifecycle = Halted，无法区分；且任意新报价都会把管理员主动暂停的市场自动 恢复，违背运营意图。

2.1 读侧（向后兼容，非破坏）​

  • getMarkets 的 MarketListItem 与 getMarket / getMarketById 的 MarketDetailResponse 新增 halt_reason（枚举 "Admin" / "QuoteStale" / null）。依赖方按可选字段处理（旧节点不返回该字段）。

2.2 行为变更（链节点升级生效，属 STF 变更）​

  • HaltMarket → halt_reason = "Admin"：不再被后续报价自动恢复，必须显式 ResumeMarket；报价仍会被接受并刷新（恢复后立即可交易）。
  • 块末报价过期（lag > max_quote_lag_ms）→ halt_reason = "QuoteStale" + MarketHaltedQuoteStale；报价恢复新鲜后自动恢复（MarketResumedAfterQuote）， 自动恢复入口：SubmitOracleQuote 接受路径 + 块末新鲜度检查。
  • 旧链升级前已暂停的市场 halt_reason = null，语义等价于自动暂停（报价恢复后 自愈）；需要长期停盘请重新执行 HaltMarket 或使用 SetEmergencyHalt。

升级注意：本次是共识 STF 变更（MarketEntry.halt_reason 进 state_root 指纹、 快照版本 7→8、state store schema 2→3），节点需整体升级并重建 state store / 快照。

1. 2026-08-14：getMarkets 新增未平仓量字段；24h 成交量翻转时机修正​

1.1 读侧（向后兼容，非破坏）​

  • getMarkets 的 MarketListItem 新增 open_interest（未平仓量 = 多头总量，sz 精度） 与 open_interest_notional（未平仓名义值，SCALE_6），口径与 getMarketSummary 一致。
  • 升级注意：字段由链节点 getMarkets 返回；旧节点不返回这两个字段，依赖方应按 可选字段处理。

1.2 行为修正（24h 成交量，无需迁移）​

  • 24h 成交量（day_ntl_volume / day_base_volume）的 UTC 午夜翻转由块末移到 块开始：此前跨午夜后第一个块内已累加的成交额会被块末翻转误清零（既不算昨天也 不算今天），现已修正。对外语义不变：UTC 零点归零、日内累计。

0. 2026-08-12：市场管理支持 market_id 精确寻址​

背景：设计允许重名 symbol。此前所有读/写接口按 symbol 解析到第一个匹配市场， 重名市场无法从管理后台定位。本次为市场管理链路引入 market_id 精确寻址。

0.1 读侧（向后兼容，非破坏）​

  • 新增 getMarketById（读方法 45 → 46）：POST /api/v1/query，参数 { "market_id": u32 }， 响应与 getMarket 完全一致。
  • getMarket / getMarketSummary / getOrderbook / getRecentTrades / getCandles 新增可选参数 market_id：携带时优先按 id 解析，缺省行为与旧参数完全一致。

0.2 写侧（向后兼容，需同步升级链节点）​

  • 市场管理 Action 的 payload 新增可选字段 market_id： ActivateMarket / HaltMarket / ResumeMarket / RequestDelist / CompleteDelist / SetFeeRecipient / AmendMarketConfig / SetEmergencyHalt。
  • 新增 CancelMarket（master-only）：撤销未激活市场（仅 Created → Delisted， 无 DelistPending 过渡期与清退流程；发 MarketCancelled + MarketLifecycleChanged 事件）。 普通退市路径（RequestDelist / CompleteDelist）对 Created 市场仍拒绝。
  • 解析规则：market_id 优先；未携带（旧 envelope，字节不变）回退 symbol 解析； market_id 指向不存在的市场 → MarketNotFound 拒绝。
  • 升级注意：携带 market_id 的 envelope 需要链节点同步升级；旧节点会忽略该字段并按 symbol 解析（可能误操作到第一个市场），因此链节点与新版后台/客户端必须一起上线。

1. 合并概述​

  • 链读写与读侧接口由同一节点、同一组端点提供；对接时无需区分服务归属，任一生产域名均可访问全部接口。
  • 原两套接口中路径同名者（如 /api/v1/markets、/bbos、/marks）归属固定，见 §3.3。
  • 原读侧独立入口（如 WS /api/v1/ws/hl、裸 /health）已删除，统一到 §2 的入口路由。

2. 入口路由总表（变后）​

方法路径用途变化
POST/api/v1/query链读（JSON-RPC，46 方法）新增 getMarketById（见 §0.1）
POST/api/v1/action链写（JSON-RPC，44 Action）不变
GET/api/v1/health存活/就绪探针不变
GET/api/v1/wsWebSocket（链 10 主题 + 读侧主题）统一（见 §5）
GET/api/v1/status节点状态/水位语义微调 + 新增字段（见 §4.1）
GET/api/v1/markets 等 7 条 REST 别名见 §3.34 条改热读包装
GET/POST/api/v1/*（历史检索、热行情、K 线、/info）读侧 REST部分破坏性变化（见 §4）

3. Chain API（链读/写）​

3.1 读方法（46 个 JSON-RPC）​

方法名、{height, data, page?} 响应骨架、错误码（-32700…-32010）全部保持。 新增 getMarketById；getMarket / getMarketSummary / getOrderbook / getRecentTrades / getCandles 增加可选 market_id 参数（缺省行为不变，见 §0.1）。

3.2 写 Action（44 个）​

Action 枚举、L1 msgpack / EIP-712 签名、accepted / kept-reject 响应保持。 8 个市场管理 Action 的 payload 增加可选 market_id（旧 envelope 字节不变，见 §0.2）。

3.3 REST 缓存别名（7 条 → 3 条链别名 + 4 条热读路径）​

路径变前（链别名 {height,data}）变后破坏性
GET /api/v1/markets{height, data}热读包装 {chain_height, book_updated_at_ms, stale, ready, data}是
GET /api/v1/markets/{symbol}{height, data}不变（链骨架）否
GET /api/v1/markets/{symbol}/summary{height, data}热读包装是
GET /api/v1/orderbook/{symbol}?depth={height, data}不变（链骨架）否
GET /api/v1/bbos{height, data}热读包装是
GET /api/v1/marks{height, data}热读包装是
GET /api/v1/stats{height, data}不变（链骨架）否

迁移：需要链骨架的做市商改走 POST /api/v1/query（getMarkets / getMarketSummary / getAllBBOs / getAllMarks 仍返回 {height,data}）；需要热读元数据（stale/ready/ chain_height）的客户端读扁平 meta。

3.4 GET /api/v1/health​

不变（超集）：{status, height} 之外可带 backfill 明细；ok / recovering / degraded。

4. 读侧 REST​

4.1 GET /api/v1/status​

  • 语义：所有 watermark/lag 反映节点内索引 worker 的水位；node_tip 即当前节点 tip。
  • 新增字段：envelope_total。
  • 其余字段（watermark / block_count / derive_* / candle_* / stats_* / hot_feed.* / markets.*）不变。

4.2 分页契约（破坏性行为说明）​

项变前变后
page.total默认返回精确总数默认省略；显式 include_total=true 才计数
翻页offset/limit新增 keyset cursor + next_cursor / has_more
深分页无上限offset > 1000 返回 400，必须用 cursor
新增 cursor 的端点/orders、/bridge-flows、/positions、/referral/events、/rebate/events上述端点支持 cursor
原有 cursor 的端点/fills、/fund-flows、/account/events、/blocks、/envelopes不变

迁移：首屏 offset=0（可不带）；翻页回传 page.next_cursor；依赖精确总数加 include_total=true。

4.3 GET /api/v1/fills 字段变更（derive v4 · 合并前已生效，补记）​

变前字段变后
aggressor_side（必填）删除；taker 方向请用 Chain getUserFills / WS userFills
position_old_size / position_new_size删除；持仓变化用 GET /api/v1/positions
is_close删除；由 position_action（open_long/open_short/close_long/close_short）表达
position_action新增（可选）
trigger_id新增（可选，触发单来源）
realized_pnl / realized_pnl_pct不变

4.4 GET /api/v1/markets 响应包装（破坏性）​

  • 变前：裸数组 MarketInfo[]。
  • 变后：热读包装 {chain_height, book_updated_at_ms, stale, ready, data: MarketInfo[]}， 附 X-Chain-Height / X-Book-Updated-At-Ms / X-Market-Data-Stale header。
  • 内部前端无消费者；外部客户端改读 data 字段。

4.5 GET /api/v1/tx/{hash}​

  • source 恒为 "local"（索引与链读同源，不再有 "node" 回退语义）。

4.6 排行榜（GET /api/v1/leaderboard）​

  • 全部 metric × period 改为物化快照；equity + all 走节点热缓存（meta.source = "node"）。
  • meta.as_of_timestamp_ms 语义 = 快照/缓存刷新时间（非链上最新块时间）。

4.7 热行情 REST（/market/orderbook/{symbol}、/market/trades/{symbol}、/bbos、/marks、/markets/{symbol}/summary）​

  • 响应包装与 header 保持既有契约（扁平 meta + data）；数据与链读同源。
  • trades 订阅相关：REST 行为不变。

4.8 K 线（GET /api/v1/candles、POST /info）​

  • 不变：candleSnapshot / GET 参数 / Candle（t,T,s,i,o,c,h,l,v,n）/ interval 表 / 404 / 400 语义全部保持。

4.9 新增 GET /api/v1/search​

  • 新增端点（旧文档无）：按账户地址 / 交易 hash / 区块高度检索。

5. WebSocket 统一（破坏性）​

合并前存在两套 WS：链 WS（op/topics 订阅制）与读侧 WS （/api/v1/ws/hl，method/subscription + 自动推送）。合并后只有一套：

项变前（读侧 WS）变后（统一 /api/v1/ws）
入口/api/v1/ws/hl/api/v1/ws（与链 WS 同入口）
区块广播连接即自动推 event:"block_ingested"订阅 blocks.live 主题后每块推 topic:"blocks.live"
K 线{"method":"subscribe","subscription":{"type":"candle",...}}订阅 candles.{symbol}.{interval} 主题
行情帧HL 格式（channel:l2Book/trades/bbo/marks）统一主题 book.{symbol} / trades.{symbol} / bbo.{symbol} / marks（decimal-string 节点格式）
心跳应用层 {"method":"ping"}协议级 ping/pong（服务端 15s），客户端 Ping 帧亦可
订阅协议method + subscriptionop:"subscribe" + topics

链 WS 10 主题（block / book.{symbol}[.{depth}] / trades.{symbol} / account.{hex} / external_quote.{symbol} / bbo.{symbol} / userFills.{hex} / orderUpdates.{hex} / triggerUpdates.{hex} / marks）不变；同一连接可同时订阅链主题与新增的 blocks.live、 candles.{symbol}.{interval}。

已知差异：trades 主题订阅后无「最近 50 条」初始快照（l2Book / bbo / marks / account 有订阅即推快照）。

6. 数据/字段级变更汇总​

位置变化类型
GET /api/v1/fillsaggressor_side / position_old_size / position_new_size / is_close → position_action（+ trigger_id）破坏性
GET /api/v1/markets裸数组 → 热读包装破坏性
GET /api/v1/orders+ cursor / client_order_id / trigger_id；MAX_OFFSET=1000非破坏（新增字段）+ 深分页行为
GET /api/v1/status+ envelope_total；lag 语义本地化非破坏
GET /api/v1/leaderboard快照化；source="node" 场景；as_of_timestamp_ms 语义非破坏（语义说明）
GET /api/v1/tx/{hash}source 恒 "local"非破坏（合并后语义）
getUserFills / getOrderFillsoffset > 1000 返回 400（MAX_OFFSET=1000）；getOrderFills 的 limit 在 SQL 端生效破坏性（深分页行为）
CreateMarket / AmendMarketConfigmax_fills_per_quote == 0 拒绝（新错误 InvalidMaxFillsPerQuote）破坏性（校验收紧）
OrderDone.reason / WS orderUpdates.reason+ DoneReason 标签 "AmendClampedAtFilled"（改单剩余量被已成交量夹住）非破坏（新增标签）
getOrderStatus.close_reason / order_record.close_reason+ "amend_clamped_at_filled"；此前此类订单会落到 "cancelled"非破坏（新增枚举值）

7. 不变项（避免误判）​

  • Chain JSON-RPC 46 读方法、45 写 Action、签名（L1 msgpack / EIP-712）、错误码。
  • 链 REST 别名 3 条（/markets/{symbol}、/orderbook/{symbol}、/stats）。
  • 链 WS 协议与 10 主题。
  • 历史检索 DTO：BlockHeader / EnvelopeView / EventView / FundFlowRecord / BridgeFlowRecord / PositionHistoryRecord / Referral* / Rebate* / AccountStats / LeaderboardEntry。
  • K 线契约（/candles、/info、candle WS 数据载荷）。
  • 数值精度（decimal string）、地址/哈希格式、分页骨架 {data, page}。
  • POST /api/v1/query / action 的 batch / 代理行为。
  • Bridge Contract（EVM 合约）不涉及本次合并。

8. 迁移速查（破坏性项）​

客户端现状迁移动作
用旧读侧 WS（/api/v1/ws/hl、block_ingested、method/subscription、HL 帧）改用统一 /api/v1/ws：op/topics 订阅 blocks.live / candles.* / book.* 等；帧识别字段 topic
按链骨架解析 /markets、/markets/{symbol}/summary、/bbos、/marks改解析热读包装（或改走 POST /api/v1/query 同名方法）
依赖 /fills 的 aggressor_side / position_* / is_close改用 position_action；taker 方向走 Chain getUserFills / WS userFills
依赖 /markets 裸数组改读 data 字段
依赖默认 page.total显式 include_total=true；翻页用 cursor
依赖 GET /health（旧读侧探针）改用 GET /api/v1/health

9. 2026-08-13：市场精确分类（后台可配置，offchain）​

市场分类为运营元数据，由 zepto-server 存储，不涉及链上 Action / 状态 / 快照， 对链读写接口零影响。现行接口见 链外运营 · 市场分类； §11 已把分类来源改为 market_catalog。

9.1 新增公开只读接口（无鉴权）​

  • GET /api/public/market-categories：后台可配置的两级分类树（默认对齐 Hyperliquid perpCategories，仅返回启用项）。
  • GET /api/public/market-classifications：market_id → 分类关联列表 （§11 后不再是分类来源；路由仍在）。

生产基址 https://admin.auroran.io/api/；交易站反代 /market-classifications-api/* → /api/public/*。

9.2 新增管理接口（Bearer 鉴权）​

  • 分类树 CRUD：GET/POST /api/market-categories、PUT/DELETE /api/market-categories/{id}。
  • 市场分类关联：GET /api/market-classifications、 PUT/DELETE /api/market-classifications/{marketId}（§11 后为遗留路由）。

9.3 前端行为​

  • zepto-admin：新增「市场分类」管理页；市场列表增加分类列 / 筛选 / 行内设置； 从 Hyperliquid 创建市场时自动带分类（best-effort）。
  • zepto-web：市场选择器的 crypto / tradfi tab 改为按后台分类驱动， 未分类市场回退旧启发式（symbol 前缀），分类接口不可用不影响交易界面。

10. 2026-08-13：市场分类支持从 Hyperliquid 全量覆盖同步​

新增两个管理接口（Bearer 鉴权），点一次执行一次，无定时任务：

  • POST /api/market-categories/sync/preview：预览 HL perpCategories 中 尚未入库的分类及将被覆盖的 source=hl 分类（不写库，含预计影响市场数）。
  • POST /api/market-categories/sync/import：当时 body 为 { codes, apply_to_markets? }， 按 code upsert 覆盖分类；apply_to_markets=true（默认）时按 symbol → HL coin → category 给现有链上市场打标。

保护语义：source=manual（手工）与 source=seed（内置种子）分类不被覆盖； 未知 HL 分类挂兜底总分类 misc。当日打标范围仅 ExternalPeg。

§11 删除 apply_to_markets：现行 body 仅为 { codes }，同步写入 market_catalog （含未上架），不再给链上市场打 market_id 标。

zepto-admin「市场分类」页新增「从 Hyperliquid 同步」按钮：预览勾选 → 导入 → 展示新增/覆盖/跳过报告。

11. 2026-08-13：市场分类改为「分类大集合 + symbol 目录」​

分类与市场的关联从 market_id 改为 symbol 目录（market_catalog， symbol 统一小写、匹配忽略大小写），并支持管理员按 symbol 增删市场。

11.1 数据与接口​

  • 新增 market_catalog（symbol 主键 → category，含 source=hl/manual、 updated_by）；旧 market_classifications 历史数据迁移为 manual 条目后 不再作为分类来源（HTTP 路由仍挂着，见现行文档「遗留路由」）。
  • 新增 GET /api/public/market-catalog（公开大集合，含链上未上架市场）、 GET /api/market-catalog（管理端，含来源）、 POST /api/market-categories/{id}/markets（按 symbol 添加/移除）。
  • 同步导入不再依赖链上市场：每个同步分类把 HL 中该分类下全部市场 （含未上架）覆盖写入目录（manual 条目保留）；报告字段 markets_updated → markets_synced，预览字段 affected_markets → market_count。

11.2 分类体系​

  • 移除 preipo（上市前）：默认种子不再创建，HL 同步跳过且不会重建。

11.3 前端​

  • zepto-admin：市场列表按目录（忽略大小写）展示分类，行内编辑改为 把市场 symbol 加入/移出分类；分类页支持每个分类的「管理市场」（增删、来源标记）。
  • zepto-web：市场选择器改为拉取公开目录后与链上市场列表匹配（忽略大小写）， 未匹配回退旧启发式；Native 市场由管理员把 symbol 加入分类后自动匹配。

11.4 一键整理​

  • 新增 POST /api/market-categories/cleanup（Bearer）：白名单子分类归位到 对应总分类（股票/外汇/大宗商品/指数 → 传统金融），删除已移除分类 （preipo）及其目录市场；规范总分类（crypto/tradfi）缺失时自动重建。
  • zepto-admin「市场分类」页新增「一键整理」按钮，执行后展示归位/删除/清理报告。

11.5 市场选择器第二排子分类​

zepto-web 市场选择器模仿 Hyperliquid 增加第二排子分类：选中总分类 （如 传统金融）后显示该总分类下的子分类（股票/大宗商品/外汇/指数等）， 点击子分类仅展示归入该子分类的市场。