feat(instance): add exchange account ledger tab with SSE sync

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

lib/account_ledger/__init__.py

@@ -0,0 +1 @@
+"""实例账户流水(交易所资金/交易账户账单)."""

lib/account_ledger/account_ledger_db.py

@@ -0,0 +1,186 @@
+"""账户流水 SQLite 缓存."""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from lib.account_ledger.account_ledger_normalize import PAGE_SIZE, VALID_ACCOUNTS
+
+
+def ensure_account_ledger_tables(conn) -> None:
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS account_ledger_entries (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            account TEXT NOT NULL,
+            ccy TEXT NOT NULL,
+            amount REAL NOT NULL,
+            balance_after REAL,
+            kind TEXT,
+            raw_type TEXT,
+            symbol TEXT,
+            ref_id TEXT NOT NULL,
+            ts_ms INTEGER NOT NULL,
+            note TEXT,
+            synced_at REAL,
+            UNIQUE(account, ref_id, ccy, ts_ms)
+        )
+        """
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_account_ledger_acc_ts "
+        "ON account_ledger_entries(account, ts_ms DESC)"
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS account_ledger_meta (
+            key TEXT PRIMARY KEY,
+            value TEXT
+        )
+        """
+    )
+    conn.commit()
+
+
+def meta_get(conn, key: str, default: str = "") -> str:
+    row = conn.execute(
+        "SELECT value FROM account_ledger_meta WHERE key=?", (key,)
+    ).fetchone()
+    if not row:
+        return default
+    try:
+        return str(row[0] if not hasattr(row, "keys") else row["value"])
+    except Exception:
+        return default
+
+
+def meta_set(conn, key: str, value: str) -> None:
+    conn.execute(
+        "INSERT INTO account_ledger_meta(key, value) VALUES(?, ?) "
+        "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+        (key, str(value)),
+    )
+
+
+def upsert_entries(conn, rows: list[dict[str, Any]]) -> int:
+    if not rows:
+        return 0
+    now = time.time()
+    n = 0
+    for r in rows:
+        try:
+            conn.execute(
+                """
+                INSERT INTO account_ledger_entries(
+                    account, ccy, amount, balance_after, kind, raw_type,
+                    symbol, ref_id, ts_ms, note, synced_at
+                ) VALUES (?,?,?,?,?,?,?,?,?,?,?)
+                ON CONFLICT(account, ref_id, ccy, ts_ms) DO UPDATE SET
+                    amount=excluded.amount,
+                    balance_after=excluded.balance_after,
+                    kind=excluded.kind,
+                    raw_type=excluded.raw_type,
+                    symbol=excluded.symbol,
+                    note=excluded.note,
+                    synced_at=excluded.synced_at
+                """,
+                (
+                    r["account"],
+                    r["ccy"],
+                    float(r["amount"]),
+                    r.get("balance_after"),
+                    r.get("kind") or "other",
+                    r.get("raw_type") or "",
+                    r.get("symbol") or "",
+                    r["ref_id"],
+                    int(r["ts_ms"]),
+                    r.get("note") or "",
+                    now,
+                ),
+            )
+            n += 1
+        except Exception:
+            continue
+    conn.commit()
+    return n
+
+
+def query_entries(
+    conn,
+    *,
+    account: str,
+    start_ms: int,
+    end_ms: int,
+    page: int = 1,
+    page_size: int = PAGE_SIZE,
+    currencies: Optional[list[str]] = None,
+) -> dict[str, Any]:
+    acc = (account or "").strip().lower()
+    if acc not in VALID_ACCOUNTS:
+        return {"items": [], "total": 0, "page": 1, "page_size": page_size, "pages": 0}
+    page = max(1, int(page or 1))
+    page_size = max(1, min(50, int(page_size or PAGE_SIZE)))
+    start_ms = int(start_ms)
+    end_ms = int(end_ms)
+    params: list[Any] = [acc, start_ms, end_ms]
+    ccy_sql = ""
+    if currencies:
+        ccy_list = [c.strip().upper() for c in currencies if c and str(c).strip()]
+        if ccy_list:
+            placeholders = ",".join("?" for _ in ccy_list)
+            ccy_sql = f" AND ccy IN ({placeholders})"
+            params.extend(ccy_list)
+    total = conn.execute(
+        f"SELECT COUNT(*) FROM account_ledger_entries "
+        f"WHERE account=? AND ts_ms>=? AND ts_ms<=?{ccy_sql}",
+        params,
+    ).fetchone()[0]
+    total = int(total or 0)
+    pages = (total + page_size - 1) // page_size if total else 0
+    if pages and page > pages:
+        page = pages
+    offset = (page - 1) * page_size
+    rows = conn.execute(
+        f"""
+        SELECT account, ccy, amount, balance_after, kind, raw_type, symbol,
+               ref_id, ts_ms, note
+        FROM account_ledger_entries
+        WHERE account=? AND ts_ms>=? AND ts_ms<=?{ccy_sql}
+        ORDER BY ts_ms DESC, id DESC
+        LIMIT ? OFFSET ?
+        """,
+        params + [page_size, offset],
+    ).fetchall()
+    items = []
+    for r in rows:
+        if hasattr(r, "keys"):
+            d = {k: r[k] for k in r.keys()}
+        else:
+            d = {
+                "account": r[0],
+                "ccy": r[1],
+                "amount": r[2],
+                "balance_after": r[3],
+                "kind": r[4],
+                "raw_type": r[5],
+                "symbol": r[6],
+                "ref_id": r[7],
+                "ts_ms": r[8],
+                "note": r[9],
+            }
+        from lib.account_ledger.account_ledger_normalize import kind_label_zh
+
+        d["kind_label"] = kind_label_zh(d.get("kind") or "")
+        items.append(d)
+    return {
+        "items": items,
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+        "pages": pages,
+    }
+
+
+def prune_older_than(conn, min_ts_ms: int) -> None:
+    conn.execute("DELETE FROM account_ledger_entries WHERE ts_ms < ?", (int(min_ts_ms),))
+    conn.commit()

lib/account_ledger/account_ledger_normalize.py

@@ -0,0 +1,192 @@
+"""账户流水:交易所原始记录 → 统一行模型."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+ACCOUNT_FUNDING = "funding"
+ACCOUNT_TRADING = "trading"
+VALID_ACCOUNTS = frozenset({ACCOUNT_FUNDING, ACCOUNT_TRADING})
+
+PAGE_SIZE = 10
+
+
+def _safe_float(v: Any) -> Optional[float]:
+    if v is None or v == "":
+        return None
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_int(v: Any) -> Optional[int]:
+    if v is None or v == "":
+        return None
+    try:
+        n = float(v)
+        if n > 1e12:
+            return int(n)
+        if n > 1e9:
+            return int(n)
+        return int(n)
+    except (TypeError, ValueError):
+        return None
+
+
+def _ts_ms(v: Any) -> Optional[int]:
+    if v is None or v == "":
+        return None
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    if n > 1e12:
+        return int(n)
+    if n > 1e10:
+        return int(n)
+    return int(n * 1000.0)
+
+
+def kind_from_raw(raw_type: str, amount: Optional[float] = None) -> str:
+    t = (raw_type or "").strip().lower()
+    if not t:
+        return "other"
+    if "deposit" in t or t in ("1", "funding_deposit"):
+        return "deposit"
+    if "withdraw" in t or "withdrawal" in t:
+        return "withdraw"
+    if "transfer" in t or "dnw" in t or t in ("2", "18", "19"):
+        if amount is not None and amount < 0:
+            return "transfer_out"
+        if amount is not None and amount > 0:
+            return "transfer_in"
+        return "transfer"
+    if "funding" in t and "fee" in t:
+        return "funding_fee"
+    if t in ("funding_fee", "fundingfee", "8"):
+        return "funding_fee"
+    if "commission" in t or "fee" in t or t in ("commission", "5", "fee"):
+        return "commission"
+    if "realiz" in t or "pnl" in t or t in ("realized_pnl", "realizedpnl", "3"):
+        return "realized_pnl"
+    if "liqui" in t:
+        return "liquidate"
+    return "other"
+
+
+def kind_label_zh(kind: str) -> str:
+    return {
+        "deposit": "充值",
+        "withdraw": "提现",
+        "transfer": "划转",
+        "transfer_in": "划入",
+        "transfer_out": "划出",
+        "realized_pnl": "已实现盈亏",
+        "funding_fee": "资金费",
+        "commission": "手续费",
+        "liquidate": "强平",
+        "other": "其他",
+    }.get((kind or "").strip().lower(), "其他")
+
+
+def make_ref_id(*parts: Any) -> str:
+    bits = []
+    for p in parts:
+        if p is None:
+            continue
+        s = str(p).strip()
+        if s:
+            bits.append(s)
+    return "|".join(bits) if bits else ""
+
+
+def normalize_row(
+    *,
+    account: str,
+    ccy: str,
+    amount: Any,
+    ts_ms: Any,
+    ref_id: str,
+    raw_type: str = "",
+    balance_after: Any = None,
+    symbol: str = "",
+    note: str = "",
+    kind: str = "",
+) -> Optional[dict[str, Any]]:
+    acc = (account or "").strip().lower()
+    if acc not in VALID_ACCOUNTS:
+        return None
+    ccy_u = (ccy or "").strip().upper()
+    if not ccy_u:
+        return None
+    amt = _safe_float(amount)
+    if amt is None:
+        return None
+    ts = _ts_ms(ts_ms)
+    if ts is None or ts <= 0:
+        return None
+    rid = (ref_id or "").strip() or make_ref_id(acc, ccy_u, ts, amt, raw_type)
+    k = (kind or "").strip().lower() or kind_from_raw(raw_type, amt)
+    bal = _safe_float(balance_after)
+    return {
+        "account": acc,
+        "ccy": ccy_u,
+        "amount": amt,
+        "balance_after": bal,
+        "kind": k,
+        "kind_label": kind_label_zh(k),
+        "raw_type": (raw_type or "").strip()[:120],
+        "symbol": (symbol or "").strip()[:80],
+        "ref_id": rid[:200],
+        "ts_ms": int(ts),
+        "note": (note or "").strip()[:240],
+    }
+
+
+def from_ccxt_ledger_entry(entry: dict[str, Any], *, account: str) -> Optional[dict[str, Any]]:
+    if not isinstance(entry, dict):
+        return None
+    info = entry.get("info") if isinstance(entry.get("info"), dict) else {}
+    amount = entry.get("amount")
+    if amount is None:
+        amount = entry.get("change")
+    if amount is None:
+        amount = info.get("balChg") or info.get("change") or info.get("income") or info.get("amount")
+    ts = entry.get("timestamp") or entry.get("datetime")
+    if ts is None:
+        ts = info.get("time") or info.get("uTime") or info.get("ts") or info.get("create_time") or info.get("createDate")
+    ccy = entry.get("currency") or info.get("ccy") or info.get("asset") or info.get("currency") or "USDT"
+    raw_type = (
+        entry.get("type")
+        or entry.get("status")
+        or info.get("type")
+        or info.get("incomeType")
+        or info.get("change_type")
+        or info.get("subType")
+        or ""
+    )
+    if isinstance(raw_type, (int, float)):
+        raw_type = str(raw_type)
+    balance_after = entry.get("balance") or info.get("bal") or info.get("balance")
+    symbol = entry.get("symbol") or info.get("instId") or info.get("symbol") or info.get("contract") or ""
+    ref = (
+        entry.get("id")
+        or info.get("billId")
+        or info.get("tranId")
+        or info.get("id")
+        or info.get("trade_id")
+        or ""
+    )
+    note = entry.get("description") or info.get("info") or info.get("text") or ""
+    return normalize_row(
+        account=account,
+        ccy=str(ccy),
+        amount=amount,
+        ts_ms=ts,
+        ref_id=str(ref) if ref != "" else make_ref_id(account, ccy, ts, amount, raw_type),
+        raw_type=str(raw_type),
+        balance_after=balance_after,
+        symbol=str(symbol or ""),
+        note=str(note or ""),
+    )

lib/account_ledger/account_ledger_register.py

@@ -0,0 +1,208 @@
+"""三所统一:账户流水路由 + 后台同步安装."""
+from __future__ import annotations
+
+import os
+from typing import Any, Callable
+
+from flask import Flask, Response, jsonify, request, session, stream_with_context
+from jinja2 import ChoiceLoader, FileSystemLoader
+
+from lib.account_ledger.account_ledger_db import ensure_account_ledger_tables, query_entries
+from lib.account_ledger.account_ledger_normalize import (
+    ACCOUNT_FUNDING,
+    ACCOUNT_TRADING,
+    PAGE_SIZE,
+    VALID_ACCOUNTS,
+)
+from lib.account_ledger.account_ledger_sync import account_ledger_store
+from lib.common.history_window_lib import resolve_list_window
+
+
+def attach_account_ledger_templates(app: Flask, repo_root: str) -> None:
+    tpl_dir = os.path.join(repo_root, "lib", "account_ledger", "templates")
+    if not os.path.isdir(tpl_dir):
+        return
+    existing = app.jinja_loader
+    loaders = [FileSystemLoader(tpl_dir)]
+    if existing is not None:
+        if isinstance(existing, ChoiceLoader):
+            loaders = list(existing.loaders) + loaders
+        else:
+            loaders.insert(0, existing)
+    app.jinja_loader = ChoiceLoader(loaders)
+
+
+def _build_fetch_fn(exchange_key: str, app_module: Any) -> Callable:
+    ex_key = (exchange_key or "").strip().lower()
+    exchange = getattr(app_module, "exchange", None)
+    ensure_markets = getattr(app_module, "ensure_markets_loaded", None)
+
+    def _fetch(*, start_ms: int, end_ms: int):
+        if exchange is None:
+            return [], ["exchange missing"]
+        if ex_key == "okx":
+            from lib.exchange.okx_ledger_lib import fetch_okx_account_ledger
+
+            return fetch_okx_account_ledger(
+                exchange,
+                start_ms=start_ms,
+                end_ms=end_ms,
+                ensure_markets=ensure_markets,
+            )
+        if ex_key == "binance":
+            from lib.exchange.binance_ledger_lib import fetch_binance_account_ledger
+
+            return fetch_binance_account_ledger(
+                exchange,
+                start_ms=start_ms,
+                end_ms=end_ms,
+                ensure_markets=ensure_markets,
+            )
+        from lib.exchange.gate_ledger_lib import fetch_gate_account_ledger
+
+        return fetch_gate_account_ledger(
+            exchange,
+            start_ms=start_ms,
+            end_ms=end_ms,
+            ensure_markets=ensure_markets,
+        )
+
+    return _fetch
+
+
+def _currencies_for_exchange(exchange_key: str) -> list[str]:
+    if (exchange_key or "").strip().lower() == "okx":
+        return ["USDT", "USDC"]
+    return ["USDT"]
+
+
+def install_account_ledger(
+    app: Flask,
+    repo_root: str,
+    app_module: Any,
+    *,
+    exchange_key: str = "",
+) -> None:
+    ex = (exchange_key or "").strip().lower()
+    if not ex:
+        mod_name = getattr(app_module, "__name__", "") or ""
+        if "okx" in mod_name.lower():
+            ex = "okx"
+        elif "binance" in mod_name.lower():
+            ex = "binance"
+        else:
+            ex = "gate"
+    exchange_key = ex
+
+    attach_account_ledger_templates(app, repo_root)
+    get_db = app_module.get_db
+    login_required = app_module.login_required
+
+    # 初始化表
+    try:
+        conn = get_db()
+        try:
+            ensure_account_ledger_tables(conn)
+        finally:
+            conn.close()
+    except Exception:
+        pass
+
+    account_ledger_store.configure(
+        get_db=get_db,
+        fetch_fn=_build_fetch_fn(exchange_key, app_module),
+        exchange_key=str(exchange_key),
+    )
+    account_ledger_store.start()
+    app.extensions["account_ledger_exchange"] = str(exchange_key).lower()
+
+    def _list_window():
+        resolve = getattr(app_module, "_list_window_from_request", None)
+        if callable(resolve):
+            return resolve()
+        return resolve_list_window(request.args, session)
+
+    @app.route("/api/account_ledger")
+    @login_required
+    def api_account_ledger():
+        account = (request.args.get("account") or ACCOUNT_FUNDING).strip().lower()
+        if account not in VALID_ACCOUNTS:
+            account = ACCOUNT_FUNDING
+        try:
+            page = int(request.args.get("page") or 1)
+        except Exception:
+            page = 1
+        win = _list_window()
+        start_ms = int(win.get("start_ms") or 0)
+        end_ms = int(win.get("end_ms") or 0)
+        ccys = _currencies_for_exchange(app.extensions.get("account_ledger_exchange") or "")
+        conn = get_db()
+        try:
+            ensure_account_ledger_tables(conn)
+            data = query_entries(
+                conn,
+                account=account,
+                start_ms=start_ms,
+                end_ms=end_ms,
+                page=page,
+                page_size=PAGE_SIZE,
+                currencies=ccys,
+            )
+        finally:
+            conn.close()
+        st = account_ledger_store.status_dict()
+        return jsonify(
+            {
+                "ok": True,
+                "account": account,
+                "window": {
+                    "preset": win.get("preset"),
+                    "label": win.get("label"),
+                    "start_ms": start_ms,
+                    "end_ms": end_ms,
+                },
+                "currencies": ccys,
+                **data,
+                **st,
+            }
+        )
+
+    @app.route("/api/account_ledger/stream")
+    @login_required
+    def api_account_ledger_stream():
+        return Response(
+            stream_with_context(account_ledger_store.iter_sse()),
+            mimetype="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @app.route("/api/account_ledger/refresh", methods=["POST"])
+    @login_required
+    def api_account_ledger_refresh():
+        win = _list_window()
+        body = request.get_json(silent=True) or {}
+        start_ms = body.get("start_ms", win.get("start_ms"))
+        end_ms = body.get("end_ms", win.get("end_ms"))
+        try:
+            start_i = int(start_ms) if start_ms is not None else None
+            end_i = int(end_ms) if end_ms is not None else None
+        except Exception:
+            start_i, end_i = None, None
+        result = account_ledger_store.sync_once(
+            reason="manual", start_ms=start_i, end_ms=end_i
+        )
+        return jsonify(result)
+
+    @app.route("/account_ledger")
+    @login_required
+    def account_ledger_page():
+        from lib.instance.instance_embed_lib import redirect_to_embed_shell_if_enabled
+
+        redir = redirect_to_embed_shell_if_enabled("account_ledger")
+        if redir is not None:
+            return redir
+        return app_module.render_main_page("account_ledger")

lib/account_ledger/account_ledger_sync.py

@@ -0,0 +1,252 @@
+"""账户流水:后台定时拉取交易所 + SSE 版本推送."""
+from __future__ import annotations
+
+import json
+import os
+import queue
+import threading
+import time
+from collections.abc import Callable, Iterator
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from lib.account_ledger.account_ledger_db import (
+    ensure_account_ledger_tables,
+    meta_get,
+    meta_set,
+    prune_older_than,
+    upsert_entries,
+)
+
+ACCOUNT_LEDGER_POLL_SEC = float(os.getenv("ACCOUNT_LEDGER_POLL_SEC", "120"))
+ACCOUNT_LEDGER_LOOKBACK_DAYS = int(os.getenv("ACCOUNT_LEDGER_LOOKBACK_DAYS", "90"))
+ACCOUNT_LEDGER_SSE_HEARTBEAT_SEC = float(os.getenv("ACCOUNT_LEDGER_SSE_HEARTBEAT_SEC", "25"))
+
+
+class AccountLedgerStore:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.version = 0
+        self._subscribers: list[queue.Queue[str | None]] = []
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._syncing = False
+        self._get_db: Optional[Callable] = None
+        self._fetch_fn: Optional[Callable[..., tuple[list[dict[str, Any]], list[str]]]] = None
+        self._exchange_key = ""
+        self.last_sync_at: Optional[float] = None
+        self.last_error: str = ""
+        self.last_upserted: int = 0
+        self._last_manual_at: float = 0.0
+        self._manual_cooldown_sec = float(os.getenv("ACCOUNT_LEDGER_MANUAL_COOLDOWN_SEC", "30"))
+
+    def configure(
+        self,
+        *,
+        get_db: Callable,
+        fetch_fn: Callable[..., tuple[list[dict[str, Any]], list[str]]],
+        exchange_key: str,
+    ) -> None:
+        self._get_db = get_db
+        self._fetch_fn = fetch_fn
+        self._exchange_key = (exchange_key or "").strip().lower()
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        if not self._get_db or not self._fetch_fn:
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._loop, daemon=True, name=f"account-ledger-{self._exchange_key or 'x'}"
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._broadcast(close=True)
+
+    def lookback_bounds_ms(self, start_ms: Optional[int] = None, end_ms: Optional[int] = None) -> tuple[int, int]:
+        now = datetime.now(timezone.utc)
+        end = int(end_ms) if end_ms is not None else int(now.timestamp() * 1000)
+        floor = int(end - ACCOUNT_LEDGER_LOOKBACK_DAYS * 86400 * 1000)
+        if start_ms is not None:
+            start = max(int(start_ms), floor)
+        else:
+            start = floor
+        if start > end:
+            start, end = end, start
+        return start, end
+
+    def sync_once(
+        self,
+        *,
+        reason: str = "poll",
+        start_ms: Optional[int] = None,
+        end_ms: Optional[int] = None,
+    ) -> dict[str, Any]:
+        if not self._get_db or not self._fetch_fn:
+            return {"ok": False, "msg": "未配置"}
+        with self._lock:
+            if self._syncing:
+                return {"ok": True, "busy": True, "ledger_version": self.version}
+            if reason == "manual":
+                gap = time.time() - self._last_manual_at
+                if gap < self._manual_cooldown_sec:
+                    wait = int(self._manual_cooldown_sec - gap) + 1
+                    return {
+                        "ok": False,
+                        "msg": f"同步过于频繁,请 {wait}s 后再试",
+                        "ledger_version": self.version,
+                    }
+            self._syncing = True
+        try:
+            start, end = self.lookback_bounds_ms(start_ms, end_ms)
+            rows, errors = self._fetch_fn(start_ms=start, end_ms=end)
+            conn = self._get_db()
+            try:
+                ensure_account_ledger_tables(conn)
+                n = upsert_entries(conn, rows or [])
+                # 保留略宽于 lookback 的缓存
+                prune_ms = int(
+                    (datetime.now(timezone.utc).timestamp() - (ACCOUNT_LEDGER_LOOKBACK_DAYS + 7) * 86400)
+                    * 1000
+                )
+                prune_older_than(conn, prune_ms)
+                self.last_sync_at = time.time()
+                self.last_upserted = n
+                self.last_error = "; ".join(errors[:3]) if errors else ""
+                meta_set(conn, "last_sync_at", str(self.last_sync_at))
+                meta_set(conn, "last_error", self.last_error)
+                meta_set(conn, "last_upserted", str(n))
+                conn.commit()
+            finally:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+            if reason == "manual":
+                self._last_manual_at = time.time()
+            ver = self.bump(reason)
+            return {
+                "ok": True,
+                "ledger_version": ver,
+                "upserted": n,
+                "errors": errors,
+                "start_ms": start,
+                "end_ms": end,
+            }
+        except Exception as e:
+            self.last_error = str(e)
+            try:
+                conn = self._get_db()
+                try:
+                    ensure_account_ledger_tables(conn)
+                    meta_set(conn, "last_error", self.last_error)
+                    conn.commit()
+                finally:
+                    conn.close()
+            except Exception:
+                pass
+            return {"ok": False, "msg": str(e), "ledger_version": self.version}
+        finally:
+            with self._lock:
+                self._syncing = False
+
+    def bump(self, reason: str = "poll") -> int:
+        with self._lock:
+            self.version += 1
+            ver = self.version
+        payload = json.dumps(
+            {"ledger_version": ver, "reason": reason, "exchange": self._exchange_key},
+            ensure_ascii=False,
+        )
+        self._broadcast(payload)
+        return ver
+
+    def status_dict(self) -> dict[str, Any]:
+        last_at = self.last_sync_at
+        if last_at is None and self._get_db:
+            try:
+                conn = self._get_db()
+                try:
+                    ensure_account_ledger_tables(conn)
+                    raw = meta_get(conn, "last_sync_at", "")
+                    if raw:
+                        last_at = float(raw)
+                    self.last_error = meta_get(conn, "last_error", self.last_error)
+                finally:
+                    conn.close()
+            except Exception:
+                pass
+        return {
+            "ledger_version": self.version,
+            "poll_sec": ACCOUNT_LEDGER_POLL_SEC,
+            "lookback_days": ACCOUNT_LEDGER_LOOKBACK_DAYS,
+            "last_sync_at": last_at,
+            "last_error": self.last_error,
+            "last_upserted": self.last_upserted,
+            "exchange": self._exchange_key,
+        }
+
+    def _loop(self) -> None:
+        # 启动后稍等再拉,避免和启动高峰撞车
+        if self._stop.wait(3):
+            return
+        while not self._stop.is_set():
+            try:
+                self.sync_once(reason="poll")
+            except Exception:
+                pass
+            if self._stop.wait(ACCOUNT_LEDGER_POLL_SEC):
+                break
+
+    def _broadcast(self, event: str | None = None, *, close: bool = False) -> None:
+        with self._lock:
+            subs = list(self._subscribers)
+        dead: list[queue.Queue[str | None]] = []
+        for q in subs:
+            try:
+                q.put_nowait(None if close else event)
+            except Exception:
+                dead.append(q)
+        if dead:
+            with self._lock:
+                for q in dead:
+                    if q in self._subscribers:
+                        self._subscribers.remove(q)
+
+    def _subscribe(self) -> queue.Queue[str | None]:
+        q: queue.Queue[str | None] = queue.Queue(maxsize=16)
+        with self._lock:
+            self._subscribers.append(q)
+        return q
+
+    def _unsubscribe(self, q: queue.Queue[str | None]) -> None:
+        with self._lock:
+            if q in self._subscribers:
+                self._subscribers.remove(q)
+
+    def iter_sse(self) -> Iterator[str]:
+        q = self._subscribe()
+        try:
+            yield f"event: ledger\ndata: {json.dumps({'ledger_version': self.version, 'reason': 'hello'}, ensure_ascii=False)}\n\n"
+            last_hb = time.time()
+            while not self._stop.is_set():
+                try:
+                    item = q.get(timeout=1.0)
+                except queue.Empty:
+                    item = "timeout"
+                if item is None:
+                    break
+                if item != "timeout":
+                    yield f"event: ledger\ndata: {item}\n\n"
+                    last_hb = time.time()
+                elif time.time() - last_hb >= ACCOUNT_LEDGER_SSE_HEARTBEAT_SEC:
+                    yield ": heartbeat\n\n"
+                    last_hb = time.time()
+        finally:
+            self._unsubscribe(q)
+
+
+account_ledger_store = AccountLedgerStore()

lib/account_ledger/templates/account_ledger_panel.html

@@ -0,0 +1,72 @@
+{# 账户流水:资金/交易 Tab · 交易所账单 · SSE #}
+<div class="card full account-ledger-card" id="account-ledger-root" data-account-ledger="1">
+    <div class="account-ledger-head">
+        <div>
+            <h2 style="margin-bottom:4px">账户流水</h2>
+            <p class="muted account-ledger-desc">拉取交易所资金账户与交易账户账单 · 时间跟随顶栏 UTC 预设 · 约 2 分钟自动同步</p>
+        </div>
+        <div class="account-ledger-head-actions">
+            <span class="muted" id="account-ledger-sync">—</span>
+            <button type="button" class="btn-sm" id="account-ledger-refresh">立即同步</button>
+        </div>
+    </div>
+    <div class="account-ledger-tabs" role="tablist">
+        <button type="button" class="account-ledger-tab active" data-ledger-account="funding" role="tab" aria-selected="true">资金账户</button>
+        <button type="button" class="account-ledger-tab" data-ledger-account="trading" role="tab" aria-selected="false">交易账户</button>
+    </div>
+    <p class="muted account-ledger-status" id="account-ledger-status"></p>
+    <div class="account-ledger-table-wrap panel-scroll">
+        <table class="account-ledger-table" id="account-ledger-table">
+            <thead>
+                <tr>
+                    <th>时间(北京)</th>
+                    <th>币种</th>
+                    <th>类型</th>
+                    <th>变动</th>
+                    <th>余额</th>
+                    <th>合约/备注</th>
+                </tr>
+            </thead>
+            <tbody id="account-ledger-tbody">
+                <tr><td colspan="6" class="muted">加载中…</td></tr>
+            </tbody>
+        </table>
+    </div>
+    <div class="account-ledger-pager" id="account-ledger-pager">
+        <button type="button" class="btn-sm" id="account-ledger-prev" disabled>上一页</button>
+        <span class="muted" id="account-ledger-page-info">—</span>
+        <button type="button" class="btn-sm" id="account-ledger-next" disabled>下一页</button>
+    </div>
+</div>
+<style>
+.account-ledger-card { grid-column: 1 / -1; }
+.account-ledger-head {
+  display: flex; align-items: flex-start; justify-content: space-between;
+  gap: 12px; flex-wrap: wrap; margin-bottom: 10px;
+}
+.account-ledger-head-actions { display: flex; align-items: center; gap: 10px; }
+.account-ledger-tabs {
+  display: flex; gap: 8px; margin-bottom: 10px; flex-wrap: wrap;
+}
+.account-ledger-tab {
+  border: 1px solid rgba(140,160,200,.35);
+  background: transparent; color: #c5cbe0;
+  border-radius: 6px; padding: 6px 14px; cursor: pointer; font-size: .9rem;
+}
+.account-ledger-tab.active {
+  background: #1f3a5a; border-color: #3d6f9c; color: #e8f1ff;
+}
+.account-ledger-table { width: 100%; border-collapse: collapse; font-size: .88rem; }
+.account-ledger-table th, .account-ledger-table td {
+  padding: 8px 10px; border-bottom: 1px solid rgba(120,130,160,.2); text-align: left;
+}
+.account-ledger-table th { color: #9aa3bd; font-weight: 600; }
+.account-ledger-amt-pos { color: #3ecf8e; }
+.account-ledger-amt-neg { color: #f07178; }
+.account-ledger-pager {
+  display: flex; align-items: center; justify-content: flex-end; gap: 10px;
+  margin-top: 12px;
+}
+.account-ledger-status { min-height: 1.2em; margin: 0 0 8px; }
+.account-ledger-table-wrap { max-height: min(60vh, 560px); overflow: auto; }
+</style>