订单跟踪系统 — 复杂度审计报告

审计范围：src/trading/executor.py · src/trading/websocket_order_manager.py
验证方式：静态分析 + 测试网实测（scripts/verify_order_tracking.py --coin ICP --size 10）

一、审计结论

发现 5 项复杂度问题，根源均为对 Hyperliquid API 响应结构的错误假设。
测试网验证推翻了两个核心前提：

直接后果：

• _backfill_order_price / _verify_fill_completeness 写入的字段永远是 0，是有网络开销的空操作
• _close_limit_leg_timeout 的 remaining 恒等于原始仓位量，平仓数量计算始终错误
• has_fill_price 字段与 filled_size > 0 语义完全重合，是冗余状态

二、问题清单

问题 A — 两个死函数（executor.py）

函数：_backfill_order_price（_{L698–724）、`_verify_fill_completeness`（}L726–766）

死因：两函数均调用 resp.get("avgPx") 和 resp.get("totalSz")，
而 query_order_by_oid 的响应对 filled 和 canceled 均无这两个字段。
每次调用只产生网络开销，不产生任何效果。

调用点（共 3 处，均为死代码）：

• _track_limit_order：if/else has_fill_price 分叉，两个分支分别调用两函数
• _close_limit_leg_timeout：else 分支调用 _backfill_order_price
• limit_open：调用 _backfill_order_price

净删除：~70 行 + 3 处调用

问题 B — _close_limit_leg_timeout 解析错误（executor.py）

位置：~L787–818

错误：

filled_sz = self._safe_pos_float(resp.get("totalSz"))  # → 永远 0
fill_px   = self._safe_pos_float(resp.get("avgPx"))    # → 永远 0

totalSz / avgPx 不在响应顶层，正确结构为 resp["order"]["origSz"] 和 resp["order"]["sz"]。

后果：filled_sz 恒为 0 → remaining = position_size（全量）→ 超时平仓总是按全量下单。
remaining == 0 的分支（L810–818）永远不会到达，是不可达代码。

正确解析：

inner     = resp.get("order", {})
orig_sz   = self._safe_pos_float(inner.get("origSz"))
remain_sz = self._safe_pos_float(inner.get("sz"))
filled_sz = max(0.0, orig_sz - remain_sz) if orig_sz > 0 else 0.0
fill_px   = self._safe_pos_float(inner.get("limitPx"))  # avgPx 不可用，limitPx 最优近似

问题 C — has_fill_price 冗余字段（websocket_order_manager.py）

字段：OrderTracking.has_fill_price: bool = False（L48）

冗余原因：has_fill_price 的语义等价于 filled_size > 0。
filled_size 在每次 fill 事件时累计，有 fill 则必然 > 0，无 fill 则必然 == 0。
两个字段表达同一个事实，无需单独维护。

引用点（共 4 处需处理）：

• OrderTracking 字段声明（L48）：删除
• _resolve() 内赋值（~L259）：删除
• _on_order_filled_event 内赋值（~L378）：删除
• _on_order_status_event 内条件判断（~L319）：替换为 filled_size > 0

保留 _grace_timer：验证显示正常路径两事件同时到达、timer 不启动。
但若 userFills WS 消息丢失，timer 是防止订单卡在 PENDING（直至 600s 超时）的唯一保障。
风险高于收益，不删除。

问题 D — _parse_order_response 解析错误（websocket_order_manager.py）

位置：~L537–568

错误：

avg_px   = _pos_float(resp.get("avgPx") or resp.get("avg_px"))    # → 永远 0
total_sz = _pos_float(resp.get("totalSz") or resp.get("total_sz")) # → 永远 0

后果：_http_check 通过 HTTP 检测到已成交/已撤销订单时，
resolve 写入 avg_price=0、filled_size=0，价格信息完全丢失。

正确解析：

inner    = resp.get("order", {})
total_sz = max(0.0, _pos_float(inner.get("origSz")) - _pos_float(inner.get("sz")))
avg_px   = _pos_float(inner.get("limitPx"))  # avgPx 不可用，limitPx 是最优近似

问题 E — _http_check 魔法字符串（websocket_order_manager.py）

位置：~L493–530

问题：函数返回 "open" / "resolved" / "stale" / "busy" / "error" 5 个字符串，
调用方用字符串比较做分支，类型不安全，可读性差，且 "stale" 语义含糊。

改动：返回值改为 Optional[bool]

签名：def _http_check(self, oid: int) -> bool | None:

调用方模式（2 处统一）：

result = self._http_check(oid)
if result is True:
    return
if result is False:
    self._resolve(oid, tracking, OrderStatus.TIMEOUT)
    return
# None → error/busy，继续重试逻辑

三、修改汇总

总净删除：约 85 行，无新增抽象层。

四、执行顺序

1. Fix A：先删函数体，再删 3 处调用点（避免遗漏）
2. Fix B：独立改写 _close_limit_leg_timeout 内解析逻辑
3. Fix C：搜索 has_fill_price 全部引用，逐一处理
4. Fix D：改写 _parse_order_response 两行
5. Fix E：改返回值签名 + 统一 2 处调用方

五、验证方法

python scripts/verify_order_tracking.py --coin ICP --size 10

附：API 响应结构说明

query_order_by_oid → query_order_status 解包后的结构：

{
  "order": {
    "origSz": "10.0",
    "sz": "10.0",
    "limitPx": "2.0542",
    "side": "B",
    "coin": "ICP",
    "oid": 48961810081
  },
  "status": "canceled"
}

不存在的字段：avgPx、totalSz（仅在下单即时响应 exchange.order() 中存在）

成交量计算：filled = origSz - sz（取消时两者相等，成交 = 0；部分成交再取消时两者不等）