Initial standalone crypto_okx with one-click deploy.

Add deploy/manage.sh bootstrap for git.bz121.com/dekun/crypto_okx and point docs at this repo.

Co-authored-by: Cursor <cursoragent@cursor.com>

lib/market/__init__.py

@@ -0,0 +1 @@
+"""Standalone market helpers (formerly lib.hub)."""

lib/market/market_precision_lib.py

@@ -0,0 +1,41 @@
+"""Exchange amount/price precision helpers for hedge and local trading."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def _decimals_from_precision_value(value: Any) -> Optional[int]:
+    if value in (None, ""):
+        return None
+    try:
+        p = float(value)
+    except (TypeError, ValueError):
+        return None
+    if p >= 1 and abs(p - round(p)) < 1e-9 and p <= 12:
+        return int(round(p))
+    if 0 < p < 1:
+        s = f"{p:.12f}".rstrip("0")
+        if "." in s:
+            return min(12, len(s.split(".", 1)[1]))
+    return None
+
+
+def _decimals_from_ccxt_str(text: str) -> int:
+    s = str(text or "").strip()
+    if not s or "." not in s:
+        return 0
+    frac = s.split(".", 1)[1]
+    if not frac:
+        return 0
+    return min(12, len(frac.rstrip("0") or frac))
+
+
+def amount_decimals_from_exchange(exchange: Any, exchange_symbol: str) -> int:
+    try:
+        return _decimals_from_ccxt_str(exchange.amount_to_precision(exchange_symbol, 1.23456789))
+    except Exception:
+        market = exchange.market(exchange_symbol)
+        prec = (market.get("precision") or {}).get("amount")
+        d = _decimals_from_precision_value(prec)
+        return d if d is not None else 4

lib/market/ohlcv_lib.py

@@ -0,0 +1,693 @@
+"""ccxt OHLCV helpers for charts and market data."""
+
+
+from __future__ import annotations
+
+import math
+import os
+import time
+from typing import Any, Callable, Optional
+
+CHART_TIMEFRAMES = frozenset(
+    {
+        "1m",
+        "5m",
+        "15m",
+        "1h",
+        "2h",
+        "4h",
+        "1d",
+        "1w",
+    }
+)
+CHART_TIMEFRAME_ORDER = (
+    "1m",
+    "5m",
+    "15m",
+    "1h",
+    "2h",
+    "4h",
+    "1d",
+    "1w",
+)
+DAILY_PLUS_TIMEFRAMES = frozenset({"1d", "1w"})
+
+# 入库 / 同步真源(各周期直拉交易所,不做本地聚合)
+STORED_TIMEFRAMES = frozenset(CHART_TIMEFRAMES)
+PERMANENT_STORED_TIMEFRAMES = frozenset({"1d", "1w"})
+YEAR_ROLLING_STORED = frozenset({"5m", "15m", "1h", "2h", "4h"})
+
+# 行情区不做展示周期聚合;保留空映射供兼容读取
+CHART_DISPLAY_AGGREGATE_FROM: dict[str, str] = {}
+
+SMALL_DISPLAY_TFS = frozenset({"1m", "5m", "15m"})
+MID_DISPLAY_TFS = frozenset({"1h", "2h", "4h"})
+
+HUB_KLINE_1M_MAX_BARS = max(1000, int(os.getenv("HUB_KLINE_1M_MAX_BARS", "10000")))
+HUB_KLINE_5M_1H_RETENTION_DAYS = max(30, int(os.getenv("HUB_KLINE_5M_1H_RETENTION_DAYS", "365")))
+HUB_KLINE_SEED_BARS = max(100, int(os.getenv("HUB_KLINE_SEED_BARS", "500")))
+
+# 交易所无原生周期时的远程拉取 fallback(行情区当前无映射)
+OHLCV_AGGREGATE_FROM: dict[str, str] = {}
+
+TIMEFRAME_MS: dict[str, int] = {
+    "1m": 60_000,
+    "5m": 5 * 60_000,
+    "15m": 15 * 60_000,
+    "1h": 60 * 60_000,
+    "2h": 2 * 60 * 60_000,
+    "4h": 4 * 60 * 60_000,
+    "12h": 12 * 60 * 60_000,
+    "1d": 24 * 60 * 60_000,
+    "1w": 7 * 24 * 60 * 60_000,
+}
+
+
+def normalize_chart_timeframe(raw: str | None, default: str = "5m") -> str:
+    tf = (raw or default).strip().lower()
+    return tf if tf in CHART_TIMEFRAMES else default
+
+
+def normalize_perpetual_symbol(symbol: str) -> str:
+    """BTC/USDT → BTC/USDT:USDT(与三所 ccxt swap 行情一致)."""
+    sym = (symbol or "").strip().upper()
+    if not sym:
+        return ""
+    if ":" in sym:
+        return sym
+    if "/" in sym:
+        base, quote = sym.split("/", 1)
+        quote_clean = quote.split(":")[0]
+        return f"{base}/{quote_clean}:{quote_clean}"
+    return sym
+
+
+def sync_timeframe_for_display(timeframe: str) -> str:
+    """展示周期对应的入库 / 同步周期."""
+    tf = normalize_chart_timeframe(timeframe)
+    return CHART_DISPLAY_AGGREGATE_FROM.get(tf, tf)
+
+
+def aggregation_source_for_display(timeframe: str) -> str | None:
+    tf = normalize_chart_timeframe(timeframe)
+    return CHART_DISPLAY_AGGREGATE_FROM.get(tf)
+
+
+def aggregate_ratio(display_tf: str, source_tf: str) -> int:
+    d = normalize_chart_timeframe(display_tf)
+    s = normalize_chart_timeframe(source_tf)
+    return max(1, int(TIMEFRAME_MS[d] // TIMEFRAME_MS[s]))
+
+
+def chart_initial_limit(timeframe: str) -> int:
+    tf = normalize_chart_timeframe(timeframe)
+    if tf in SMALL_DISPLAY_TFS:
+        return 2000
+    if tf in MID_DISPLAY_TFS:
+        return 1000
+    if tf in DAILY_PLUS_TIMEFRAMES:
+        return 500
+    return 500
+
+
+def chart_chunk_limit(timeframe: str) -> int:
+    tf = normalize_chart_timeframe(timeframe)
+    if tf in SMALL_DISPLAY_TFS:
+        return 500
+    if tf == "1w":
+        return 150
+    if tf in MID_DISPLAY_TFS:
+        return 300
+    return 200
+
+
+def chart_memory_cap(timeframe: str) -> int:
+    tf = normalize_chart_timeframe(timeframe)
+    if tf in SMALL_DISPLAY_TFS:
+        return 5000
+    if tf == "1w":
+        return 500
+    return 1000
+
+
+def bar_limit_for_timeframe(timeframe: str) -> int:
+    return chart_memory_cap(timeframe)
+
+
+def storage_retention_days(storage_tf: str) -> int | None:
+    """None 表示不按天截断(1m 按根数;1d/1w 永久)."""
+    tf = normalize_chart_timeframe(storage_tf)
+    if tf in YEAR_ROLLING_STORED:
+        return HUB_KLINE_5M_1H_RETENTION_DAYS
+    return None
+
+
+def history_cutoff_ms_for_storage(storage_tf: str, now_ms: int | None = None) -> int:
+    days = storage_retention_days(storage_tf)
+    if days is None:
+        return 0
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    return max(0, now - int(days) * 86400000)
+
+
+def seed_bar_target(storage_tf: str) -> int:
+    tf = normalize_chart_timeframe(storage_tf)
+    if tf == "1m":
+        return HUB_KLINE_1M_MAX_BARS
+    if tf in YEAR_ROLLING_STORED:
+        period = TIMEFRAME_MS[tf]
+        return min(
+            int(86400000 * HUB_KLINE_5M_1H_RETENTION_DAYS / period) + 20,
+            150000,
+        )
+    return HUB_KLINE_SEED_BARS
+
+
+def retention_policy_meta() -> dict[str, Any]:
+    year = {"mode": "days", "days": HUB_KLINE_5M_1H_RETENTION_DAYS}
+    return {
+        "1m": {"mode": "bars", "max_bars": HUB_KLINE_1M_MAX_BARS},
+        "5m": dict(year),
+        "15m": dict(year),
+        "1h": dict(year),
+        "2h": dict(year),
+        "4h": dict(year),
+        "1d": {"mode": "permanent"},
+        "1w": {"mode": "permanent"},
+        "aggregate_from": {},
+    }
+
+
+def last_closed_bar_open_ms(timeframe: str, now_ms: int | None = None) -> int:
+    """上一根已收盘 K 的 open_time(毫秒 UTC)."""
+    tf = normalize_chart_timeframe(timeframe)
+    period = TIMEFRAME_MS[tf]
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    current_open = (now // period) * period
+    return int(current_open - period)
+
+
+def window_start_ms(timeframe: str, need: int, retention_days: int, now_ms: int | None = None) -> int:
+    """本地库清理/读库窗口:不超过 retention_days."""
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    period = TIMEFRAME_MS[normalize_chart_timeframe(timeframe)]
+    retention_cutoff = now - max(1, int(retention_days)) * 86400000
+    want = now - max(1, int(need)) * period
+    return max(retention_cutoff, want)
+
+
+def chart_fetch_start_ms(timeframe: str, need: int, now_ms: int | None = None) -> int:
+    """行情展示拉取起点:按 need 根回看(日线 500 / 日内 1000),不受 DB 保留天数限制."""
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    period = TIMEFRAME_MS[normalize_chart_timeframe(timeframe)]
+    return max(0, now - max(1, int(need)) * period)
+
+
+def _positive_float(value: Any) -> Optional[float]:
+    if value in (None, ""):
+        return None
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return None
+    return v if v > 0 else None
+
+
+def _price_tick_from_market_info(info: dict) -> Optional[float]:
+    """从 market.info 解析 tick(含币安 PRICE_FILTER.filters)."""
+    for key in ("tickSize", "tickSz", "price_increment", "order_price_round", "quote_increment"):
+        v = _positive_float(info.get(key))
+        if v is not None:
+            return v
+
+    for key in ("pricePrecision", "price_precision"):
+        raw = info.get(key)
+        if raw in (None, ""):
+            continue
+        try:
+            p = float(raw)
+        except (TypeError, ValueError):
+            continue
+        if p >= 1 and abs(p - round(p)) < 1e-9 and p <= 12:
+            return 10 ** (-int(p))
+        if 0 < p < 1:
+            return p
+
+    filters = info.get("filters")
+    if isinstance(filters, list):
+        for f in filters:
+            if not isinstance(f, dict):
+                continue
+            if str(f.get("filterType") or "").upper() != "PRICE_FILTER":
+                continue
+            v = _positive_float(f.get("tickSize"))
+            if v is not None:
+                return v
+    return None
+
+
+def round_price_to_tick(value: Any, tick: Optional[float]) -> Optional[float]:
+    """按交易所 tick 对齐价格(K 线/标记线与坐标轴一致)."""
+    t = normalize_price_tick(tick)
+    if t is None:
+        return None
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return None
+    n = round(v / t) * t
+    d = _decimals_from_tick(t)
+    return float(f"{n:.{d}f}")
+
+
+def round_ohlcv_bars_to_tick(bars: list[dict[str, Any]], tick: Optional[float]) -> None:
+    t = normalize_price_tick(tick)
+    if t is None:
+        return
+    for b in bars:
+        for key in ("open", "high", "low", "close"):
+            if key in b:
+                rounded = round_price_to_tick(b.get(key), t)
+                if rounded is not None:
+                    b[key] = rounded
+
+
+def price_tick_from_market(exchange, exchange_symbol: str) -> Optional[float]:
+    """最小价格变动单位(与交易所 tick / price_to_precision 一致)."""
+    try:
+        if not getattr(exchange, "markets", None):
+            exchange.load_markets()
+        market = exchange.market(exchange_symbol)
+    except Exception:
+        return None
+
+    info = market.get("info") or {}
+    if isinstance(info, dict):
+        tick = _price_tick_from_market_info(info)
+        if tick is not None:
+            return tick
+
+    limits = market.get("limits") or {}
+    price_limits = limits.get("price") or {}
+    if price_limits.get("min") not in (None, ""):
+        try:
+            v = float(price_limits["min"])
+            if v > 0:
+                return v
+        except (TypeError, ValueError):
+            pass
+
+    try:
+        sample = exchange.price_to_precision(exchange_symbol, 12345.678901234)
+        s = str(sample).strip()
+        if "." in s:
+            frac = s.split(".", 1)[1]
+            if frac:
+                return 10 ** (-len(frac))
+        return 1.0
+    except Exception:
+        pass
+
+    prec = (market.get("precision") or {}).get("price")
+    if prec is not None:
+        try:
+            p = float(prec)
+            if p >= 1 and abs(p - round(p)) < 1e-9 and p <= 12:
+                return 10 ** (-int(p))
+            if 0 < p < 1:
+                return p
+        except (TypeError, ValueError):
+            pass
+    return None
+
+
+def normalize_price_tick(tick: Optional[float]) -> Optional[float]:
+    """将 tick 对齐为 10^-n,避免浮点噪声导致前端 lightweight-charts unexpected base."""
+    if tick is None:
+        return None
+    try:
+        t = float(tick)
+    except (TypeError, ValueError):
+        return None
+    if t <= 0:
+        return None
+    if t >= 1:
+        return t
+    try:
+        exp = int(round(-math.log10(t)))
+    except (ValueError, OverflowError):
+        return None
+    exp = max(0, min(12, exp))
+    return 10 ** (-exp)
+
+
+def _decimals_from_tick(tick: float) -> int:
+    if tick >= 1:
+        return 0
+    s = f"{tick:.12f}".rstrip("0")
+    if "." in s:
+        frac = s.split(".", 1)[1]
+        if frac:
+            return min(12, len(frac))
+    return max(0, min(12, int(round(-math.log10(tick)))))
+
+
+def format_price_by_tick(value: Any, tick: Optional[float]) -> str:
+    if value in (None, ""):
+        return "-"
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return str(value)
+    if v == 0:
+        return "0"
+    if tick and tick > 0:
+        return f"{v:.{_decimals_from_tick(float(tick))}f}"
+    av = abs(v)
+    if av >= 10000:
+        d = 2
+    elif av >= 100:
+        d = 3
+    elif av >= 1:
+        d = 4
+    elif av >= 0.01:
+        d = 6
+    else:
+        d = 8
+    text = f"{v:.{d}f}"
+    return text.rstrip("0").rstrip(".") if "." in text else text
+
+
+def exchange_supports_timeframe(exchange, timeframe: str) -> bool:
+    tf = normalize_chart_timeframe(timeframe)
+    tfs = getattr(exchange, "timeframes", None) or {}
+    if not tfs:
+        return True
+    return tf in tfs
+
+
+def _median_bar_step_ms(bars: list[dict[str, Any]]) -> Optional[int]:
+    if len(bars) < 2:
+        return None
+    steps: list[int] = []
+    for i in range(1, min(len(bars), 64)):
+        step = int(bars[i]["open_time_ms"]) - int(bars[i - 1]["open_time_ms"])
+        if step > 0:
+            steps.append(step)
+    if not steps:
+        return None
+    steps.sort()
+    return steps[len(steps) // 2]
+
+
+def bars_spacing_matches_timeframe(
+    bars: list[dict[str, Any]], timeframe: str, *, tolerance: float = 0.08
+) -> bool:
+    if len(bars) < 2:
+        return True
+    period = TIMEFRAME_MS[normalize_chart_timeframe(timeframe)]
+    step = _median_bar_step_ms(bars)
+    if step is None:
+        return False
+    return abs(step - period) <= period * tolerance
+
+
+def align_bar_open_ms(open_time_ms: int, period_ms: int) -> int:
+    return (int(open_time_ms) // period_ms) * period_ms
+
+
+def snap_to_bar_grid(ts_ms: int, origin_ms: int, step_ms: int) -> int:
+    step = max(1, int(step_ms))
+    origin = int(origin_ms)
+    if ts_ms <= origin:
+        return origin
+    idx = (int(ts_ms) - origin + step - 1) // step
+    return origin + idx * step
+
+
+def fill_missing_ohlcv_bars(
+    bars: list[dict[str, Any]],
+    period_ms: int,
+    start_ms: int | None = None,
+    end_ms: int | None = None,
+) -> list[dict[str, Any]]:
+    """细周期缺口用上一根收盘价填平,保证聚合后 K 线时间轴连续."""
+    by_ts: dict[int, dict[str, Any]] = {}
+    for b in bars or []:
+        try:
+            by_ts[int(b["open_time_ms"])] = b
+        except (KeyError, TypeError, ValueError):
+            continue
+    if not by_ts:
+        return []
+    keys = sorted(by_ts.keys())
+    step_ms = max(1, int(period_ms))
+    origin = keys[0]
+    aligned_start = snap_to_bar_grid(
+        int(start_ms if start_ms is not None else keys[0]), origin, step_ms
+    )
+    aligned_end = max(
+        int(end_ms if end_ms is not None else keys[-1]),
+        keys[-1],
+    )
+    out: list[dict[str, Any]] = []
+    last: dict[str, Any] | None = None
+    for ts_key in keys:
+        if ts_key <= aligned_start:
+            last = by_ts[ts_key]
+    ts = aligned_start
+    while ts <= aligned_end:
+        cur = by_ts.get(ts)
+        if cur is not None:
+            last = cur
+            out.append(cur)
+        elif last is not None:
+            c = float(last["close"])
+            out.append(
+                {
+                    "open_time_ms": ts,
+                    "open": c,
+                    "high": c,
+                    "low": c,
+                    "close": c,
+                    "volume": 0.0,
+                    "filled": True,
+                }
+            )
+        ts += step_ms
+    return out
+
+
+def aggregate_ohlcv_bars(
+    bars: list[dict[str, Any]], target_timeframe: str
+) -> list[dict[str, Any]]:
+    """将细周期 OHLCV 聚合为目标周期(UTC 对齐 bucket)."""
+    tf = normalize_chart_timeframe(target_timeframe)
+    period = TIMEFRAME_MS[tf]
+    buckets: dict[int, dict[str, Any]] = {}
+    for b in bars or []:
+        try:
+            key = align_bar_open_ms(int(b["open_time_ms"]), period)
+            o = float(b["open"])
+            h = float(b["high"])
+            l = float(b["low"])
+            c = float(b["close"])
+            v = float(b.get("volume") or 0)
+        except (KeyError, TypeError, ValueError):
+            continue
+        cur = buckets.get(key)
+        if cur is None:
+            buckets[key] = {
+                "open_time_ms": key,
+                "open": o,
+                "high": h,
+                "low": l,
+                "close": c,
+                "volume": v,
+            }
+            continue
+        cur["high"] = max(float(cur["high"]), h)
+        cur["low"] = min(float(cur["low"]), l)
+        cur["close"] = c
+        cur["volume"] = float(cur.get("volume") or 0) + v
+    return [buckets[k] for k in sorted(buckets.keys())]
+
+
+def _next_since_from_batch(batch: list, period_ms: int) -> int:
+    last_ts = int(batch[-1][0])
+    if len(batch) >= 2:
+        step = int(batch[-1][0]) - int(batch[-2][0])
+        if step > 0:
+            return last_ts + step
+    return last_ts + period_ms
+
+
+def _paginate_fetch_ohlcv(
+    exchange,
+    ex_sym: str,
+    timeframe: str,
+    *,
+    want: int,
+    since_ms: int | None,
+    period_ms: int,
+    chunk_max: int = 300,
+) -> list[dict[str, Any]]:
+    tf = normalize_chart_timeframe(timeframe)
+    collected: list = []
+    if since_ms is not None and int(since_ms) > 0:
+        since = int(since_ms)
+    else:
+        since = max(0, int(time.time() * 1000) - want * period_ms)
+
+    now_ms = int(time.time() * 1000)
+    guard = 0
+    prev_since = None
+    while len(collected) < want and guard < 80:
+        guard += 1
+        if since >= now_ms:
+            break
+        req_limit = min(chunk_max, want - len(collected))
+        try:
+            batch = exchange.fetch_ohlcv(
+                ex_sym, timeframe=tf, since=since, limit=req_limit
+            )
+        except Exception as e:
+            err = str(e).lower()
+            if collected and (
+                "from" in err
+                and "to" in err
+                or "invalid request parameter" in err
+            ):
+                break
+            raise
+        if not batch:
+            break
+        collected.extend(batch)
+        next_since = _next_since_from_batch(batch, period_ms)
+        if next_since >= now_ms:
+            break
+        if prev_since is not None and next_since <= prev_since:
+            break
+        prev_since = since
+        since = next_since
+
+    bars = _bars_to_dicts(collected)
+    uniq: dict[int, dict[str, Any]] = {}
+    for b in bars:
+        uniq[int(b["open_time_ms"])] = b
+    merged = [uniq[k] for k in sorted(uniq.keys())]
+    if len(merged) > want:
+        merged = merged[-want:]
+    return merged
+
+
+def _bars_to_dicts(ohlcv: list) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for bar in ohlcv or []:
+        if not bar or len(bar) < 6:
+            continue
+        try:
+            out.append(
+                {
+                    "open_time_ms": int(bar[0]),
+                    "open": float(bar[1]),
+                    "high": float(bar[2]),
+                    "low": float(bar[3]),
+                    "close": float(bar[4]),
+                    "volume": float(bar[5]),
+                }
+            )
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def fetch_ohlcv_for_hub(
+    *,
+    symbol: str,
+    timeframe: str,
+    since_ms: int | None = None,
+    limit: int = 500,
+    normalize_symbol_input: Callable[[Any], str],
+    normalize_exchange_symbol: Callable[[str], str],
+    ensure_markets_loaded: Callable[[], None],
+    exchange,
+    friendly_error: Callable[[Exception], str] | None = None,
+) -> dict[str, Any]:
+    """从 ccxt 拉 OHLCV,供本地图表与行情接口使用."""
+    tf = normalize_chart_timeframe(timeframe)
+    sym = normalize_symbol_input(symbol)
+    if not sym:
+        return {"ok": False, "msg": "symbol 不能为空"}
+    try:
+        ensure_markets_loaded()
+        ex_sym = normalize_exchange_symbol(sym)
+        want = max(1, min(int(limit or bar_limit_for_timeframe(tf)), 1500))
+        period = TIMEFRAME_MS[tf]
+        merged: list[dict[str, Any]] = []
+        src_tf = OHLCV_AGGREGATE_FROM.get(tf)
+
+        if exchange_supports_timeframe(exchange, tf):
+            candidate = _paginate_fetch_ohlcv(
+                exchange,
+                ex_sym,
+                tf,
+                want=want,
+                since_ms=since_ms,
+                period_ms=period,
+            )
+            if candidate and bars_spacing_matches_timeframe(candidate, tf):
+                merged = candidate
+
+        if (
+            not merged
+            and src_tf
+            and exchange_supports_timeframe(exchange, src_tf)
+        ):
+            src_period = TIMEFRAME_MS[normalize_chart_timeframe(src_tf)]
+            ratio = max(1, int(math.ceil(period / src_period)))
+            src_want = min(1500, want * ratio + ratio * 4)
+            src_bars = _paginate_fetch_ohlcv(
+                exchange,
+                ex_sym,
+                src_tf,
+                want=src_want,
+                since_ms=since_ms,
+                period_ms=src_period,
+            )
+            if not src_bars or not bars_spacing_matches_timeframe(src_bars, src_tf):
+                return {
+                    "ok": False,
+                    "msg": f"无法获取 {tf} K 线(细周期 {src_tf} 数据异常)",
+                }
+            merged = aggregate_ohlcv_bars(src_bars, tf)
+            if len(merged) > want:
+                merged = merged[-want:]
+
+        if not merged:
+            try:
+                tail = exchange.fetch_ohlcv(
+                    ex_sym, timeframe=tf, limit=min(want, 300)
+                )
+                merged = _bars_to_dicts(tail or [])
+                if len(merged) > want:
+                    merged = merged[-want:]
+            except Exception:
+                pass
+        if not merged:
+            return {"ok": False, "msg": "交易所未返回 K 线"}
+
+        tick = normalize_price_tick(price_tick_from_market(exchange, ex_sym))
+        round_ohlcv_bars_to_tick(merged, tick)
+
+        return {
+            "ok": True,
+            "symbol": sym,
+            "exchange_symbol": ex_sym,
+            "timeframe": tf,
+            "price_tick": tick,
+            "bars": merged,
+        }
+    except Exception as e:
+        msg = friendly_error(e) if friendly_error else str(e)
+        return {"ok": False, "msg": f"K线加载失败:{msg}"}

lib/market/position_metrics_lib.py

@@ -0,0 +1,311 @@
+"""ccxt position mark/metrics helpers."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Callable
+
+
+def _finite_or_none(x: Any) -> float | None:
+    try:
+        f = float(x)
+        return f if math.isfinite(f) else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_float(*values: Any) -> float | None:
+    for v in values:
+        if v is None or v == "":
+            continue
+        px = _finite_or_none(v)
+        if px is not None and px > 0:
+            return px
+    return None
+
+
+# OKX ccxt: ETH/USD:USD-260806-1875-C ; instId: ETH-USD-260806-1875-C
+_OPTION_SYM_RE = re.compile(
+    r"(?:^|[/:])[A-Z0-9]+(?:-USD)?(?::USD)?-\d{6}-\d+-(?:C|P|CALL|PUT)$",
+    re.IGNORECASE,
+)
+
+
+def is_option_like_position(pos: dict[str, Any] | None) -> bool:
+    """识别期权仓(子代理/中控浮盈合计须排除,避免按永续线性公式误算)."""
+    if not isinstance(pos, dict):
+        return False
+    info = pos.get("info") if isinstance(pos.get("info"), dict) else {}
+    inst_type = str(
+        info.get("instType")
+        or info.get("inst_type")
+        or pos.get("type")
+        or ""
+    ).upper()
+    if inst_type in ("OPTION", "OPT"):
+        return True
+    sym = str(
+        pos.get("symbol")
+        or info.get("instId")
+        or info.get("instrument_name")
+        or info.get("contract")
+        or ""
+    ).strip()
+    if not sym:
+        return False
+    if _OPTION_SYM_RE.search(sym.replace(" ", "")):
+        return True
+    su = sym.upper()
+    if su.endswith("-C") or su.endswith("-P") or su.endswith("-CALL") or su.endswith("-PUT"):
+        # 永续多为 BTC/USDT:USDT;期权常带到期日段
+        if re.search(r"-\d{6}-\d+-(?:C|P|CALL|PUT)$", su):
+            return True
+    return False
+
+
+CONTRACTS_QTY_DECIMALS = 2
+
+
+def normalize_contracts_qty(qty: Any, *, decimals: int = CONTRACTS_QTY_DECIMALS) -> float:
+    """张数统一精度(OKX 等线性永续默认两位小数)."""
+    try:
+        q = float(qty)
+    except (TypeError, ValueError):
+        return 0.0
+    if not math.isfinite(q):
+        return 0.0
+    return round(abs(q), decimals)
+
+
+def contracts_qty_is_open(qty: Any, *, decimals: int = CONTRACTS_QTY_DECIMALS) -> bool:
+    return normalize_contracts_qty(qty, decimals=decimals) > 0
+
+
+def position_contracts(p: dict[str, Any]) -> float:
+    info = p.get("info") or {}
+    if not isinstance(info, dict):
+        info = {}
+    # OKX 等:info.pos 为交易所张数,优先于 ccxt contracts(加仓后后者可能滞后)
+    for k in ("pos", "positionAmt", "positionamt", "size"):
+        if k in info:
+            try:
+                v = float(info[k])
+                if v != 0:
+                    return normalize_contracts_qty(v)
+            except (TypeError, ValueError):
+                pass
+    raw = p.get("contracts")
+    if raw is not None:
+        try:
+            v = float(raw)
+            if v != 0:
+                return normalize_contracts_qty(v)
+        except (TypeError, ValueError):
+            pass
+    return 0.0
+
+
+def position_side_from_ccxt(p: dict[str, Any], contracts: float | None = None) -> str:
+    s = (p.get("side") or "").lower()
+    if s in ("long", "short"):
+        return s
+    c = contracts if contracts is not None else position_contracts(p)
+    if c > 0:
+        return "long"
+    if c < 0:
+        return "short"
+    return "long"
+
+
+def parse_position_entry_price(p: dict[str, Any]) -> float | None:
+    """三所 ccxt 持仓开仓均价."""
+    if not isinstance(p, dict):
+        return None
+    info = p.get("info") or {}
+    if not isinstance(info, dict):
+        info = {}
+    return _coerce_float(
+        p.get("entryPrice"),
+        p.get("entry_price"),
+        p.get("average"),
+        info.get("entryPrice"),
+        info.get("entry_price"),
+        info.get("avgPx"),
+        info.get("avgEntryPrice"),
+        info.get("avg_entry_price"),
+        info.get("avgPrice"),
+        info.get("openAvgPx"),
+    )
+
+
+def estimate_linear_swap_upnl_usdt(
+    side: str,
+    entry: float | None,
+    mark: float | None,
+    contracts: float | None,
+    contract_size: float | None = None,
+) -> float | None:
+    """U 本位线性永续:浮盈 = (标记价 - 开仓价) × 张数 × contractSize(空头取反)."""
+    e = _finite_or_none(entry)
+    m = _finite_or_none(mark)
+    c = _finite_or_none(contracts)
+    if e is None or m is None or c is None or c <= 0:
+        return None
+    mult = _finite_or_none(contract_size)
+    if mult is None or mult <= 0:
+        mult = 1.0
+    diff = (m - e) if (side or "long").strip().lower() == "long" else (e - m)
+    return round(diff * abs(c) * mult, 2)
+
+
+def resolve_position_display_upnl(
+    side: str,
+    entry: float | None,
+    mark: float | None,
+    contracts: float | None,
+    contract_size: float | None,
+    exchange_upnl: float | None,
+) -> float | None:
+    """展示用浮盈:优先与标记价/张数一致的推算;与交易所值偏差过大时用推算值."""
+    computed = estimate_linear_swap_upnl_usdt(
+        side, entry, mark, contracts, contract_size
+    )
+    if computed is None:
+        return exchange_upnl
+    if exchange_upnl is None:
+        return computed
+    ref = max(abs(computed), 1.0)
+    if abs(exchange_upnl - computed) / ref > 0.2:
+        return computed
+    return exchange_upnl
+
+
+def _coerce_signed(*values: Any) -> float | None:
+    """解析可正可负的数值(未实现盈亏等)."""
+    for v in values:
+        if v is None or v == "":
+            continue
+        f = _finite_or_none(v)
+        if f is not None:
+            return f
+    return None
+
+
+def parse_position_unrealized_pnl(p: dict[str, Any]) -> float | None:
+    """三所 ccxt 持仓统一解析未实现盈亏(Gate/OKX/Binance 字段名不一致)."""
+    if not isinstance(p, dict):
+        return None
+    info = p.get("info") or {}
+    if not isinstance(info, dict):
+        info = {}
+    return _coerce_signed(
+        p.get("unrealizedPnl"),
+        p.get("unrealisedPnl"),
+        p.get("unrealized_pnl"),
+        p.get("unrealised_pnl"),
+        info.get("unrealised_pnl"),
+        info.get("unrealized_pnl"),
+        info.get("unrealisedPnl"),
+        info.get("unrealizedPnl"),
+        info.get("upl"),
+        info.get("uplLast"),
+    )
+
+
+def enrich_ccxt_position_metrics_out(
+    position: dict[str, Any],
+    out: dict[str, Any],
+    *,
+    contract_size: float = 1.0,
+    funds_decimals: int = 2,
+) -> dict[str, Any]:
+    """
+    三所 parse_ccxt_position_metrics 产出后统一:
+    - 标记价用 hub 兜底
+    - 未实现盈亏 = resolve(交易所值, entry/mark/张数/contractSize 推算)
+    """
+    if not isinstance(position, dict) or not isinstance(out, dict):
+        return out
+    mark = _finite_or_none(out.get("mark_price"))
+    if mark is None or mark <= 0:
+        mp = parse_position_mark_price(position)
+        if mp is not None and mp > 0:
+            out["mark_price"] = round(mp, 8)
+            mark = mp
+    exchange_upnl = parse_position_unrealized_pnl(position)
+    if exchange_upnl is None:
+        exchange_upnl = _coerce_signed(out.get("unrealized_pnl"))
+    c = position_contracts(position)
+    if abs(c) < 1e-12:
+        return out
+    side = position_side_from_ccxt(position, c)
+    entry = parse_position_entry_price(position)
+    if entry is not None and entry > 0:
+        out["entry_price"] = round(entry, 8)
+    cs = contract_size if contract_size and contract_size > 0 else 1.0
+    upnl = resolve_position_display_upnl(
+        side, entry, mark, abs(c), cs, exchange_upnl
+    )
+    if upnl is not None:
+        out["unrealized_pnl"] = round(upnl, funds_decimals)
+    return out
+
+
+def parse_position_mark_price(p: dict[str, Any]) -> float | None:
+    """三所 ccxt 持仓统一解析标记价(与 crypto_monitor_* parse_ccxt_position_metrics 口径一致)."""
+    if not isinstance(p, dict):
+        return None
+    info = p.get("info") or {}
+    if not isinstance(info, dict):
+        info = {}
+    mark = _coerce_float(
+        p.get("markPrice"),
+        p.get("mark_price"),
+        p.get("mark"),
+        info.get("markPx"),
+        info.get("mark_price"),
+        info.get("markPrice"),
+    )
+    if mark is not None:
+        return mark
+    contracts = position_contracts(p)
+    if abs(contracts) >= 1e-12:
+        notional = _finite_or_none(p.get("notional"))
+        if notional is not None and abs(notional) > 0:
+            return abs(notional) / abs(contracts)
+    return None
+
+
+def build_position_marks_list(
+    positions: list,
+    *,
+    format_mark_display: Callable[[str, float], str] | None = None,
+) -> list[dict[str, Any]]:
+    """从 fetch_positions 结果生成 position_marks,供 price_snapshot / 中控合并."""
+    out: list[dict[str, Any]] = []
+    for p in positions or []:
+        if not isinstance(p, dict):
+            continue
+        c = position_contracts(p)
+        if abs(c) < 1e-12:
+            continue
+        mark = parse_position_mark_price(p)
+        if mark is None or mark <= 0:
+            continue
+        sym = (p.get("symbol") or "").strip()
+        side = position_side_from_ccxt(p, c)
+        row: dict[str, Any] = {
+            "symbol": sym,
+            "side": side,
+            "mark_price": mark,
+        }
+        if format_mark_display and sym:
+            try:
+                row["mark_price_display"] = format_mark_display(sym, mark)
+            except Exception:
+                row["mark_price_display"] = f"{mark:g}"
+        else:
+            row["mark_price_display"] = f"{mark:g}"
+        out.append(row)
+    return out

lib/market/price_snapshot_lib.py

@@ -0,0 +1,124 @@
+"""price_snapshot 共用:订单行情价兜底,避免 get_price 失败时整单不入 order_prices."""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from lib.market.position_metrics_lib import parse_position_mark_price
+
+
+def resolve_order_snapshot_price(
+    symbol: str,
+    prices: Mapping[str, float],
+    *,
+    position_row: Optional[dict[str, Any]] = None,
+    order_leverage=None,
+    parse_position_metrics_fn: Callable[..., dict[str, Any] | None] | None = None,
+    get_mark_price_fn: Callable[[str], float | None] | None = None,
+    fallback_entry: float | None = None,
+) -> float | None:
+    """
+    解析下单监控轮询用的现价/标记价,优先级:
+    1. 已批量拉取的 ticker last
+    2. get_symbol_mark_price(含 mark)
+    3. 交易所持仓 mark(parse_ccxt_position_metrics / parse_position_mark_price)
+    4. 计划成交价 trigger_price
+    """
+    sym = (symbol or "").strip()
+    if not sym:
+        return None
+
+    cached = prices.get(sym)
+    if cached is not None:
+        try:
+            v = float(cached)
+            if v > 0:
+                return v
+        except (TypeError, ValueError):
+            pass
+
+    if get_mark_price_fn is not None:
+        try:
+            mp = get_mark_price_fn(sym)
+            if mp is not None and float(mp) > 0:
+                return float(mp)
+        except Exception:
+            pass
+
+    if position_row:
+        mark = None
+        if parse_position_metrics_fn is not None:
+            try:
+                metrics = parse_position_metrics_fn(
+                    position_row, order_leverage=order_leverage
+                )
+                if isinstance(metrics, dict) and metrics.get("mark_price") is not None:
+                    mark = float(metrics["mark_price"])
+            except Exception:
+                mark = None
+        if mark is None or mark <= 0:
+            try:
+                mp = parse_position_mark_price(position_row)
+                if mp is not None and mp > 0:
+                    mark = float(mp)
+            except Exception:
+                mark = None
+        if mark is not None and mark > 0:
+            return mark
+
+    if fallback_entry is not None:
+        try:
+            entry = float(fallback_entry)
+            if entry > 0:
+                return entry
+        except (TypeError, ValueError):
+            pass
+    return None
+
+
+def seed_prices_from_positions(
+    prices: dict[str, float],
+    order_rows: Sequence[Any],
+    all_positions: Sequence[dict[str, Any]],
+    *,
+    resolve_ex_sym_fn: Callable[[Any], str],
+) -> None:
+    """用持仓标记价补全 prices 字典(symbol 与 order_monitors 行对齐)."""
+    if not all_positions or not order_rows:
+        return
+    try:
+        from lib.market.symbol_lib import symbols_match
+    except Exception:
+        symbols_match = None
+    for r in order_rows:
+        try:
+            sym = str(r["symbol"] or "").strip()
+        except (KeyError, TypeError, IndexError):
+            sym = ""
+        if not sym or sym in prices:
+            continue
+        try:
+            ex_sym = resolve_ex_sym_fn(r)
+        except Exception:
+            ex_sym = sym
+        try:
+            direction = str(r["direction"] or "long").lower()
+        except (KeyError, TypeError, IndexError):
+            direction = "long"
+        for p in all_positions:
+            if not isinstance(p, dict):
+                continue
+            ps = p.get("symbol") or ""
+            if not ps:
+                continue
+            matched = ps == sym or ps == ex_sym
+            if not matched and symbols_match is not None:
+                matched = symbols_match(sym, ps) or symbols_match(ex_sym, ps)
+            if not matched:
+                continue
+            side = (p.get("side") or "").lower()
+            if side and side != direction:
+                continue
+            mp = parse_position_mark_price(p)
+            if mp is not None and mp > 0:
+                prices[sym] = float(mp)
+                break

lib/market/reconcile_flat_lib.py

@@ -0,0 +1,98 @@
+"""Sync order_monitors after an external/market flat."""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+
+def reconcile_hub_external_close_impl(
+    conn,
+    symbol: str,
+    direction: str,
+    *,
+    exchange_configured: Callable[[], bool],
+    not_configured_msg: str,
+    symbols_match: Callable[[str, str], bool],
+    get_opened_at_value: Callable[[Any], str],
+    resolve_monitor_exchange_symbol: Callable[[Any], str],
+    get_live_position_contracts: Callable[[str, str], float | None],
+    cancel_conditional_orders: Callable[[str], None],
+    resolve_synced_flat_close: Callable[..., tuple],
+    finalize_stopped_monitor: Callable[..., None],
+    sync_trade_records: Callable[..., None] | None = None,
+    reconcile_flat_streak: dict | None = None,
+    to_ms_with_fallback: Callable[..., int | None] | None = None,
+    prefer_manual_resolve: bool = False,
+    order_row_monitor_type: Callable[[Any], str] | None = None,
+) -> dict[str, Any]:
+    if not exchange_configured():
+        return {"ok": False, "msg": not_configured_msg, "synced": 0}
+    sym_req = (symbol or "").strip()
+    dir_l = (direction or "").strip().lower()
+    if dir_l not in ("long", "short"):
+        return {"ok": False, "msg": "side 须为 long 或 short", "synced": 0}
+    synced = 0
+    streak = reconcile_flat_streak if reconcile_flat_streak is not None else {}
+    rows = conn.execute(
+        "SELECT * FROM order_monitors WHERE status IN ('active', 'error')"
+    ).fetchall()
+    for r in rows:
+        if not symbols_match(str(r["symbol"] or ""), sym_req):
+            continue
+        if (r["direction"] or "").strip().lower() != dir_l:
+            continue
+        oid = int(r["id"])
+        if r["status"] == "error":
+            opened_at_chk = get_opened_at_value(r)
+            mtype = order_row_monitor_type(r) if order_row_monitor_type else r["monitor_type"]
+            existing = conn.execute(
+                "SELECT id FROM trade_records WHERE symbol=? AND opened_at=? AND monitor_type=? LIMIT 1",
+                (r["symbol"], opened_at_chk, mtype),
+            ).fetchone()
+            if existing:
+                conn.execute("UPDATE order_monitors SET status='stopped' WHERE id=?", (oid,))
+                synced += 1
+                continue
+        exchange_symbol = resolve_monitor_exchange_symbol(r)
+        live_contracts = get_live_position_contracts(exchange_symbol, r["direction"])
+        if live_contracts is None:
+            continue
+        if live_contracts > 0:
+            time.sleep(0.6)
+            live_contracts = get_live_position_contracts(exchange_symbol, r["direction"])
+        if live_contracts is None or live_contracts > 0:
+            continue
+        streak.pop(oid, None)
+        cancel_conditional_orders(exchange_symbol)
+        opened_at = get_opened_at_value(r)
+        opened_at_ms = None
+        if to_ms_with_fallback is not None:
+            keys = r.keys() if hasattr(r, "keys") else ()
+            opened_at_ms = to_ms_with_fallback(
+                r["opened_at_ms"] if "opened_at_ms" in keys else None,
+                opened_at,
+            )
+        resolve_kw = {"opened_at_ms": opened_at_ms}
+        if prefer_manual_resolve:
+            resolve_kw["prefer_manual"] = True
+        result, pnl_amount, closed_at, miss_reason = resolve_synced_flat_close(
+            r, opened_at, **resolve_kw
+        )
+        finalize_stopped_monitor(
+            conn,
+            r,
+            result=result,
+            pnl_amount=pnl_amount,
+            closed_at=closed_at,
+            miss_reason=miss_reason,
+        )
+        synced += 1
+    if sync_trade_records is not None:
+        try:
+            sync_trade_records(conn, force=True)
+        except Exception:
+            pass
+    return {"ok": True, "synced": synced}
+
+
+reconcile_external_close_impl = reconcile_hub_external_close_impl

lib/market/symbol_lib.py

@@ -0,0 +1,38 @@
+"""合约 symbol 匹配(持仓 vs 监控/挂单)."""
+
+
+def _symbol_base_coin(symbol: str) -> str:
+    s = (symbol or "").strip().upper()
+    if not s:
+        return ""
+    if "-SWAP" in s:
+        s = s.replace("-SWAP", "")
+    if "-" in s:
+        return s.split("-", 1)[0]
+    if "/" in s:
+        return s.split("/", 1)[0]
+    if ":" in s:
+        return s.split(":", 1)[0]
+    return s
+
+
+def symbols_match(position_symbol: str, order_symbol: str) -> bool:
+    a = (position_symbol or "").strip().upper()
+    b = (order_symbol or "").strip().upper()
+    if not a or not b:
+        return False
+    if a == b:
+        return True
+    ba, bb = _symbol_base_coin(a), _symbol_base_coin(b)
+    if ba and bb and ba == bb:
+        return True
+    for suf in (":USDT", "/USDT:USDT", "/USDT"):
+        a2 = a.replace(suf, "")
+        b2 = b.replace(suf, "")
+        if f"{a2}/USDT" == b or f"{a2}/USDT:USDT" == b:
+            return True
+        if f"{b2}/USDT" == a or f"{b2}/USDT:USDT" == a:
+            return True
+        if a2 == b2:
+            return True
+    return False

lib/market/volume_rank_lib.py

@@ -0,0 +1,599 @@
+"""行情区:各交易所 USDT 永续昨日成交额 Top N(每日 8:00 快照)."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Callable
+from zoneinfo import ZoneInfo
+
+
+def trading_day_from_dt(dt: datetime, reset_hour: int = 8) -> str:
+    """Hours < reset_hour belong to the previous calendar day."""
+    if dt.hour < reset_hour:
+        dt = dt - timedelta(days=1)
+    return dt.strftime("%Y-%m-%d")
+
+
+TOP_N_DEFAULT = 20
+CACHE_VERSION = 3
+LIQUIDITY_RANK_CACHE_VERSION = 1
+
+
+def volume_rank_reset_hour() -> int:
+    try:
+        return max(0, min(23, int(os.getenv("HUB_VOLUME_RANK_RESET_HOUR", "8"))))
+    except ValueError:
+        return 8
+
+
+def volume_rank_timezone() -> ZoneInfo:
+    name = (os.getenv("HUB_VOLUME_RANK_TZ") or "Asia/Shanghai").strip() or "Asia/Shanghai"
+    try:
+        return ZoneInfo(name)
+    except Exception:
+        return ZoneInfo("Asia/Shanghai")
+
+
+def rank_date_label(*, now: datetime | None = None, reset_hour: int | None = None) -> str:
+    """8 点更新后展示的「昨日」交易日(与 TRADING_DAY_RESET_HOUR 口径一致)."""
+    rh = volume_rank_reset_hour() if reset_hour is None else reset_hour
+    tz = volume_rank_timezone()
+    dt = now.astimezone(tz) if now else datetime.now(tz)
+    cur_td = trading_day_from_dt(dt.replace(tzinfo=None), rh)
+    cur = datetime.strptime(cur_td, "%Y-%m-%d").date()
+    return (cur - timedelta(days=1)).isoformat()
+
+
+def seconds_until_next_reset(
+    *,
+    now: datetime | None = None,
+    reset_hour: int | None = None,
+) -> float:
+    rh = volume_rank_reset_hour() if reset_hour is None else reset_hour
+    tz = volume_rank_timezone()
+    dt = now.astimezone(tz) if now else datetime.now(tz)
+    nxt = dt.replace(hour=rh, minute=0, second=0, microsecond=0)
+    if dt >= nxt:
+        nxt += timedelta(days=1)
+    return max(1.0, (nxt - dt).total_seconds())
+
+
+def default_cache_path() -> Path:
+    raw = (os.getenv("HUB_VOLUME_RANK_CACHE_PATH") or os.getenv("VOLUME_RANK_CACHE_PATH") or "").strip()
+    if raw:
+        return Path(raw)
+    return Path(__file__).resolve().parents[2] / "data" / "volume_rank.json"
+
+
+def _safe_float(v: Any) -> float | None:
+    try:
+        n = float(v)
+        return n if n == n else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _ticker_base(sym_text: str) -> str:
+    s = str(sym_text or "").upper().strip()
+    if ":" in s:
+        s = s.split(":", 1)[0]
+    if "/" in s:
+        return s.split("/", 1)[0].strip()
+    if "-" in s:
+        return s.split("-", 1)[0].strip()
+    if s.endswith("USDT"):
+        return s[:-4].strip()
+    return s
+
+
+def _hub_symbol_from_base(base: str, quote: str = "USDT") -> str:
+    b = str(base or "").strip().upper()
+    q = str(quote or "USDT").strip().upper()
+    return f"{b}/{q}" if b else ""
+
+
+def _hub_symbol_from_market(market: dict | None, fallback_symbol: str) -> str:
+    if market:
+        base = str(market.get("base") or "").strip().upper()
+        quote = str(market.get("quote") or "USDT").strip().upper()
+        if base:
+            return f"{base}/{quote}"
+    fb = str(fallback_symbol or "").upper().strip()
+    if ":" in fb:
+        fb = fb.split(":", 1)[0]
+    if "/" in fb:
+        return fb
+    base = _ticker_base(fb)
+    return f"{base}/USDT" if base else fb
+
+
+def _okx_turnover_usdt(row: dict | None) -> float | None:
+    """OKX SWAP:成交额(USDT) ≈ volCcy24h(基础币) × last."""
+    if not isinstance(row, dict):
+        return None
+    base_vol = _safe_float(row.get("volCcy24h"))
+    if base_vol is None or base_vol <= 0:
+        return None
+    last = _safe_float(row.get("last") or row.get("lastPx"))
+    if last is None or last <= 0:
+        return None
+    return float(base_vol * last)
+
+
+def _quote_volume_from_ticker(
+    ticker: dict | None,
+    market: dict | None,
+    *,
+    exchange_id: str = "",
+) -> float | None:
+    ex_id = str(exchange_id or "").lower()
+    t = ticker or {}
+    info = t.get("info") if isinstance(t.get("info"), dict) else {}
+
+    if ex_id == "okx":
+        row = dict(info)
+        if row.get("last") is None:
+            row["last"] = t.get("last")
+        qv = _okx_turnover_usdt(row)
+        if qv is not None and qv > 0:
+            return qv
+
+    qv = _safe_float(t.get("quoteVolume"))
+    if qv is not None and qv > 0:
+        return qv
+
+    if ex_id in ("gateio", "gate"):
+        for key in (
+            "volume_24h_quote",
+            "volume_24h_settle",
+            "quote_volume",
+            "vol_24h",
+            "turnover",
+        ):
+            qv = _safe_float(info.get(key))
+            if qv is not None and qv > 0:
+                return qv
+
+    for key in ("quoteVolume", "volCcy24h", "vol24h", "turnover24h", "amount24", "turnover"):
+        qv = _safe_float(info.get(key))
+        if qv is not None and qv > 0:
+            if key == "volCcy24h" and ex_id == "okx":
+                last = _safe_float(info.get("last") or info.get("lastPx") or t.get("last"))
+                if last:
+                    return qv * last
+            return qv
+
+    bv = _safe_float(t.get("baseVolume"))
+    lp = _safe_float(t.get("last")) or _safe_float(t.get("close"))
+    if bv is not None and lp is not None and bv > 0 and lp > 0:
+        return bv * lp
+
+    if info:
+        bv = _safe_float(info.get("volCcy24h") or info.get("vol24h") or info.get("volume"))
+        lp = _safe_float(info.get("last") or info.get("lastPx") or info.get("markPrice"))
+        if bv is not None and lp is not None and bv > 0 and lp > 0:
+            return bv * lp
+
+    return None
+
+
+def _is_usdt_linear_swap(market: dict | None, symbol: str) -> bool:
+    if not market:
+        su = str(symbol or "").upper()
+        return "USDT" in su and (":USDT" in su or "/USDT" in su or su.endswith("USDT"))
+    if not market.get("swap") and market.get("type") not in ("swap", "future"):
+        return False
+    if str(market.get("quote") or "").upper() != "USDT":
+        return False
+    if market.get("linear") is False:
+        return False
+    if market.get("active") is False:
+        return False
+    settle = str(market.get("settle") or "").upper()
+    if settle and settle != "USDT":
+        return False
+    return True
+
+
+def _lookup_ticker(tickers: dict, sym: str, market: dict | None) -> dict | None:
+    if not tickers:
+        return None
+    t = tickers.get(sym)
+    if t:
+        return t
+    if not market:
+        return None
+    base = market.get("base")
+    quote = market.get("quote") or "USDT"
+    settle = market.get("settle") or quote
+    candidates = [
+        sym,
+        f"{base}/{quote}:{settle}",
+        f"{base}/{quote}",
+        f"{base}{quote}",
+        market.get("id"),
+    ]
+    for key in candidates:
+        if not key:
+            continue
+        t = tickers.get(key)
+        if t:
+            return t
+    return None
+
+
+def _merge_scores(scored: dict[str, tuple[str, float]]) -> list[tuple[str, str, float]]:
+    rows = [(sym, base, vol) for base, (sym, vol) in scored.items() if sym and base and vol > 0]
+    rows.sort(key=lambda x: x[2], reverse=True)
+    return rows
+
+
+def _scores_from_okx(exchange) -> list[tuple[str, str, float]]:
+    by_base: dict[str, tuple[str, float]] = {}
+    if hasattr(exchange, "publicGetMarketTickers"):
+        try:
+            resp = exchange.publicGetMarketTickers({"instType": "SWAP"})
+            for row in (resp or {}).get("data") or []:
+                if not isinstance(row, dict):
+                    continue
+                inst = str(row.get("instId") or "").upper()
+                parts = inst.split("-")
+                if len(parts) < 3 or parts[-1] != "SWAP" or parts[1] != "USDT":
+                    continue
+                base = parts[0].strip()
+                if not base:
+                    continue
+                qv = _okx_turnover_usdt(row)
+                if qv is None or qv <= 0:
+                    continue
+                sym = _hub_symbol_from_base(base)
+                prev = by_base.get(base)
+                if prev is None or qv > prev[1]:
+                    by_base[base] = (sym, float(qv))
+            if by_base:
+                return _merge_scores(by_base)
+        except Exception:
+            pass
+
+    try:
+        tickers = exchange.fetch_tickers(params={"instType": "SWAP"})
+    except Exception:
+        tickers = exchange.fetch_tickers()
+    return _scores_from_markets(exchange, tickers or {}, "okx")
+
+
+def _scores_from_binance(exchange) -> list[tuple[str, str, float]]:
+    by_base: dict[str, tuple[str, float]] = {}
+    if hasattr(exchange, "fapiPublicGetTicker24hr"):
+        try:
+            rows = exchange.fapiPublicGetTicker24hr()
+            if isinstance(rows, list):
+                for row in rows:
+                    if not isinstance(row, dict):
+                        continue
+                    raw = str(row.get("symbol") or "").upper()
+                    if not raw.endswith("USDT"):
+                        continue
+                    base = raw[:-4]
+                    if not base:
+                        continue
+                    qv = _safe_float(row.get("quoteVolume"))
+                    if qv is None or qv <= 0:
+                        bv = _safe_float(row.get("volume"))
+                        lp = _safe_float(row.get("lastPrice") or row.get("weightedAvgPrice"))
+                        if bv and lp:
+                            qv = bv * lp
+                    if qv is None or qv <= 0:
+                        continue
+                    sym = _hub_symbol_from_base(base)
+                    prev = by_base.get(base)
+                    if prev is None or qv > prev[1]:
+                        by_base[base] = (sym, float(qv))
+                if by_base:
+                    return _merge_scores(by_base)
+        except Exception:
+            pass
+    return []
+
+
+def _scores_from_gate(exchange) -> list[tuple[str, str, float]]:
+    by_base: dict[str, tuple[str, float]] = {}
+    for method_name in ("publicFuturesGetSettleTickers", "publicFuturesGetUsdtTickers"):
+        fn = getattr(exchange, method_name, None)
+        if not callable(fn):
+            continue
+        try:
+            rows = fn({"settle": "usdt"})
+            if isinstance(rows, list):
+                for row in rows:
+                    if not isinstance(row, dict):
+                        continue
+                    contract = str(row.get("contract") or row.get("name") or "").upper()
+                    if not contract:
+                        continue
+                    base = contract.replace("_USDT", "").replace("USDT", "").strip("_")
+                    if not base:
+                        continue
+                    qv = _safe_float(row.get("volume_24h_quote") or row.get("volume_24h_settle"))
+                    if qv is None or qv <= 0:
+                        bv = _safe_float(row.get("volume_24h_base"))
+                        lp = _safe_float(row.get("last") or row.get("mark_price"))
+                        if bv and lp:
+                            qv = bv * lp
+                    if qv is None or qv <= 0:
+                        continue
+                    sym = _hub_symbol_from_base(base)
+                    prev = by_base.get(base)
+                    if prev is None or qv > prev[1]:
+                        by_base[base] = (sym, float(qv))
+                if by_base:
+                    return _merge_scores(by_base)
+        except Exception:
+            continue
+    return []
+
+
+def _scores_from_markets(
+    exchange,
+    tickers: dict,
+    exchange_id: str,
+) -> list[tuple[str, str, float]]:
+    by_base: dict[str, tuple[str, float]] = {}
+    markets = getattr(exchange, "markets", None) or {}
+    for sym, mk in markets.items():
+        try:
+            if not _is_usdt_linear_swap(mk, sym):
+                continue
+            ticker = _lookup_ticker(tickers, sym, mk)
+            qv = _quote_volume_from_ticker(ticker, mk, exchange_id=exchange_id)
+            if qv is None or qv <= 0:
+                continue
+            hub_sym = _hub_symbol_from_market(mk, sym)
+            base = _ticker_base(hub_sym)
+            if not base:
+                continue
+            prev = by_base.get(base)
+            if prev is None or qv > prev[1]:
+                by_base[base] = (hub_sym, float(qv))
+        except Exception:
+            continue
+    return _merge_scores(by_base)
+
+
+def _collect_scores(exchange, exchange_id: str) -> list[tuple[str, str, float]]:
+    ex_id = str(exchange_id or "").lower()
+    if ex_id == "okx":
+        return _scores_from_okx(exchange)
+    if ex_id == "binance":
+        return _scores_from_binance(exchange)
+    if ex_id in ("gateio", "gate"):
+        return _scores_from_gate(exchange)
+    tickers = exchange.fetch_tickers()
+    return _scores_from_markets(exchange, tickers or {}, ex_id)
+
+
+def _uses_lightweight_volume_scores(exchange_id: str) -> bool:
+    ex_id = str(exchange_id or "").lower()
+    return ex_id in ("okx", "binance", "gateio", "gate")
+
+
+def build_usdt_swap_volume_ranks(
+    exchange,
+    ensure_markets_loaded: Callable[[], None],
+    *,
+    exchange_id: str | None = None,
+) -> tuple[dict[str, int], int]:
+    """
+    全市场 USDT 永续 24h 成交额排名(base -> rank).
+    优先各所轻量 ticker API,避免 fetch_tickers() 拉全市场(Gate/Binance 内存优化).
+    """
+    ex_id = str(exchange_id or getattr(exchange, "id", "") or "").lower()
+    if not _uses_lightweight_volume_scores(ex_id):
+        ensure_markets_loaded()
+    scored = _collect_scores(exchange, ex_id)
+    ranks: dict[str, int] = {}
+    for idx, (_sym, base, _qv) in enumerate(scored, 1):
+        if base and base not in ranks:
+            ranks[base] = idx
+    return ranks, len(scored)
+
+
+def resolve_daily_volume_rank(
+    target_base: str,
+    cache: dict[str, Any],
+    *,
+    now_ts: float,
+    ttl_sec: float,
+    exchange,
+    ensure_markets_loaded: Callable[[], None],
+    exchange_id: str | None = None,
+    cache_version: int = LIQUIDITY_RANK_CACHE_VERSION,
+) -> tuple[int | None, int]:
+    """关键位门控:按 base 查 24h 成交额全市场排名;cache 带 TTL."""
+    cached_ok = (
+        cache.get("version") == cache_version
+        and cache.get("updated_at")
+        and now_ts - float(cache["updated_at"]) < ttl_sec
+    )
+    if not cached_ok:
+        try:
+            ranks, total = build_usdt_swap_volume_ranks(
+                exchange,
+                ensure_markets_loaded,
+                exchange_id=exchange_id,
+            )
+            if total > 0 and ranks:
+                cache["ranks"] = ranks
+                cache["total"] = total
+                cache["version"] = cache_version
+                cache["updated_at"] = now_ts
+        except Exception:
+            pass
+    ranks = cache.get("ranks") or {}
+    total = int(cache.get("total") or 0)
+    base = str(target_base or "").strip().upper()
+    return ranks.get(base), total
+
+
+def fetch_usdt_swap_volume_rank(
+    exchange,
+    ensure_markets_loaded: Callable[[], None],
+    *,
+    top_n: int = TOP_N_DEFAULT,
+    rank_date: str | None = None,
+    exchange_id: str | None = None,
+) -> dict[str, Any]:
+    """从 ccxt 拉全市场 USDT 永续 ticker,按 24h 成交额(USDT) 取 Top N."""
+    top_n = max(1, min(int(top_n or TOP_N_DEFAULT), 100))
+    ensure_markets_loaded()
+    ex_id = str(exchange_id or getattr(exchange, "id", "") or "").lower()
+
+    try:
+        scored = _collect_scores(exchange, ex_id)
+    except Exception as e:
+        return {"ok": False, "msg": str(e)}
+
+    items = []
+    for idx, (hub_sym, base, qv) in enumerate(scored[:top_n], 1):
+        items.append(
+            {
+                "rank": idx,
+                "symbol": hub_sym,
+                "base": base,
+                "volume_quote": round(qv, 4),
+            }
+        )
+    return {
+        "ok": True,
+        "rank_date": rank_date or rank_date_label(),
+        "items": items,
+        "total_symbols": len(scored),
+        "exchange_id": ex_id,
+        "fetched_at": datetime.now(volume_rank_timezone()).isoformat(timespec="seconds"),
+    }
+
+
+def format_volume_quote(value: float | None) -> str:
+    n = _safe_float(value)
+    if n is None or n <= 0:
+        return "—"
+    if n >= 1e9:
+        return f"{n / 1e9:.2f}B"
+    if n >= 1e6:
+        return f"{n / 1e6:.2f}M"
+    if n >= 1e3:
+        return f"{n / 1e3:.2f}K"
+    return f"{n:.0f}"
+
+
+def load_volume_rank_cache(path: Path | None = None) -> dict[str, Any]:
+    p = path or default_cache_path()
+    if not p.is_file():
+        return {"version": CACHE_VERSION, "exchanges": {}}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return {"version": CACHE_VERSION, "exchanges": {}}
+        if int(data.get("version") or 0) < CACHE_VERSION:
+            return {"version": CACHE_VERSION, "exchanges": {}}
+        data.setdefault("version", CACHE_VERSION)
+        data.setdefault("exchanges", {})
+        return data
+    except Exception:
+        return {"version": CACHE_VERSION, "exchanges": {}}
+
+
+def save_volume_rank_cache(data: dict[str, Any], path: Path | None = None) -> None:
+    p = path or default_cache_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    payload = dict(data)
+    payload["version"] = CACHE_VERSION
+    payload["updated_at"] = datetime.now(volume_rank_timezone()).isoformat(timespec="seconds")
+    p.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def merge_exchange_rank(
+    cache: dict[str, Any],
+    exchange_key: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    ex_k = str(exchange_key or "").strip().lower()
+    if not ex_k or not payload.get("ok"):
+        return cache
+    exchanges = dict(cache.get("exchanges") or {})
+    exchanges[ex_k] = {
+        "rank_date": payload.get("rank_date"),
+        "items": payload.get("items") or [],
+        "total_symbols": int(payload.get("total_symbols") or 0),
+        "fetched_at": payload.get("fetched_at"),
+        "error": None,
+    }
+    out = dict(cache)
+    out["exchanges"] = exchanges
+    out["rank_date"] = payload.get("rank_date") or cache.get("rank_date")
+    return out
+
+
+def _exchange_rank_row_stale(row: dict[str, Any] | None) -> bool:
+    if not row:
+        return True
+    items = row.get("items") or []
+    if len(items) < TOP_N_DEFAULT:
+        return True
+    total = int(row.get("total_symbols") or 0)
+    if total > 0 and total < TOP_N_DEFAULT:
+        return True
+    return False
+
+
+def cache_needs_refresh(
+    cache: dict[str, Any],
+    *,
+    expected_rank_date: str | None = None,
+    required_keys: list[str] | None = None,
+) -> bool:
+    expected = expected_rank_date or rank_date_label()
+    if int(cache.get("version") or 0) < CACHE_VERSION:
+        return True
+    exchanges = cache.get("exchanges") or {}
+    if not exchanges:
+        return True
+    if str(cache.get("rank_date") or "") != expected:
+        return True
+    keys = required_keys or list(exchanges.keys())
+    if not keys:
+        return True
+    for key in keys:
+        ex_k = str(key or "").strip().lower()
+        if not ex_k:
+            continue
+        if _exchange_rank_row_stale(exchanges.get(ex_k)):
+            return True
+    return False
+
+
+def get_cached_rank(
+    cache: dict[str, Any],
+    exchange_key: str,
+    *,
+    top_n: int = TOP_N_DEFAULT,
+) -> dict[str, Any]:
+    ex_k = str(exchange_key or "").strip().lower()
+    ex_data = (cache.get("exchanges") or {}).get(ex_k) or {}
+    items = list(ex_data.get("items") or [])[: max(1, int(top_n))]
+    stale = _exchange_rank_row_stale(ex_data)
+    return {
+        "ok": True,
+        "exchange_key": ex_k,
+        "rank_date": ex_data.get("rank_date") or cache.get("rank_date"),
+        "updated_at": cache.get("updated_at"),
+        "items": items,
+        "item_count": len(items),
+        "expected_count": int(top_n),
+        "total_symbols": int(ex_data.get("total_symbols") or 0),
+        "stale": stale,
+        "error": ex_data.get("error"),
+    }