hamuna-quant-cli 0.1.0.dev93__py3-none-any.whl

hamuna_quant_cli/live/qmt_broker.py

@@ -0,0 +1,683 @@
+"""hamuna_qmt_broker — akquant 自定义 broker, 走 bridge_server HTTP API.
+
+设计:
+  - 纯交易 broker, 行情走 akquant 现有 `DataFeed` (`market_gateway=None`).
+    QMT 行情 (snapshot / history / subscribe) 留给 MarketGateway (下一阶段),
+    当前 trader_gateway 只做账户 / 委托 / 成交 / 下单 / 撤单 5 类.
+  - HTTP 客户端用 stdlib `urllib.request`, 不引入新依赖.
+  - bridge_server 协议: 单 POST/GET /<route>, JSON body, 响应 {ok, code, data, request_id}.
+
+调用方式 (run_live 之前先 import 触发 register):
+    import hamuna_qmt_broker  # noqa: F401
+    run_live(broker="qmt", ..., qmt_base_url="http://127.0.0.1:9000",
+             qmt_account_id="8888888888", qmt_account_type="stock")
+
+设计原则:
+  - thin client: 翻译 + HTTP, 不存任何业务逻辑
+  - fail fast: HTTP / 解析失败立即抛清晰错误 (不进 retry-loop)
+  - 缺 akquant 时模块仍可 import + register 不报错; 真实调用才会 ImportError
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# ============================================================
+# 延迟 import — 让 self-check 不依赖 akquant 也能跑通
+# ============================================================
+def _import_akquant_gateway():
+    try:
+        from akquant.gateway import register_broker
+        from akquant.gateway.broker_models import (
+            BrokerCapability,
+            UnifiedAccount,
+            UnifiedOrderRequest,
+            UnifiedOrderSnapshot,
+            UnifiedOrderStatus,
+            UnifiedPosition,
+            UnifiedTrade,
+        )
+        from akquant.gateway.protocols import GatewayBundle
+        from akquant.gateway.trader_base import TraderGatewayBase
+        return {
+            "register_broker": register_broker,
+            "BrokerCapability": BrokerCapability,
+            "UnifiedAccount": UnifiedAccount,
+            "UnifiedOrderRequest": UnifiedOrderRequest,
+            "UnifiedOrderSnapshot": UnifiedOrderSnapshot,
+            "UnifiedOrderStatus": UnifiedOrderStatus,
+            "UnifiedPosition": UnifiedPosition,
+            "UnifiedTrade": UnifiedTrade,
+            "GatewayBundle": GatewayBundle,
+            "TraderGatewayBase": TraderGatewayBase,
+        }
+    except ImportError as e:
+        raise ImportError(
+            f"hamuna_qmt_broker 需要 akquant>=0.3.41 的 gateway 模块. "
+            f"`pip install --upgrade 'akquant>=0.3.41'`. 当前错误: {e}"
+        ) from e
+
+
+# ============================================================
+# HTTP client — urllib 包装, 一次 retry on connection error
+# ============================================================
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+class BrokerHTTPError(RuntimeError):
+    """bridge_server 返回 ok=False 或 HTTP 状态非 2xx."""
+
+
+def _emit_paper(msg: str) -> None:
+    """paper 模式日志 — flush=True 保证 akquant 拉日志实时看到, 不被缓冲."""
+    print(f"[PAPER] {msg}", flush=True)
+
+
+class _HTTP:
+    def __init__(self, base_url: str, timeout: float = 30.0) -> None:  # ponytail: 默认 30s 容忍 TCP connect 偶发超时 (用户实测 stacktrace 暴露 urllib 5s 在内网抖动下会 TimeoutError) — ceiling = qmt_market.poll_interval (30s), 再高就盖过 poll cycle; upgrade path = 改 requests + urllib3.Retry 自动重试 transient failure
+        self.base_url = base_url.rstrip("/")
+        self.timeout = float(timeout)
+
+    def _request(self, method: str, route: str, payload: dict[str, Any] | None) -> dict[str, Any]:
+        url = self.base_url + route
+        body: bytes | None = None
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if payload is not None:
+            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json; charset=utf-8"
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode("utf-8", errors="replace") if e.fp else ""
+            raise BrokerHTTPError(
+                f"bridge_server {method} {route} HTTP {e.code}: {raw[:200]}"
+            ) from e
+        except urllib.error.URLError as e:
+            raise BrokerHTTPError(
+                f"bridge_server {method} {route} 连接失败: {e.reason} "
+                f"(base_url={self.base_url})"
+            ) from e
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise BrokerHTTPError(
+                f"bridge_server {method} {route} 返回非 JSON: {raw[:200]}"
+            ) from e
+        if not isinstance(parsed, dict):
+            raise BrokerHTTPError(
+                f"bridge_server {method} {route} 响应不是 dict: {raw[:200]}"
+            )
+        if not parsed.get("ok"):
+            raise BrokerHTTPError(
+                f"bridge_server {method} {route} 失败: "
+                f"code={parsed.get('code')!r} message={parsed.get('message') or parsed.get('data')}"
+            )
+        # bridge_server envelope: {ok, value, request_id, ts}. 业务负载在 `value`.
+        return parsed.get("value") if isinstance(parsed.get("value"), dict) else parsed
+
+    def get(self, route: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        if params:
+            from urllib.parse import urlencode
+            route = route + ("&" if "?" in route else "?") + urlencode(params)
+        return self._request("GET", route, payload=None)
+
+    def post(self, route: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", route, payload=payload)
+
+
+# ============================================================
+# 安全码映射: akquant 侧用 sh600000 / sz000001 / 600000.XSHG, bridge 接受 600000.SH / 600000.XSHG.
+# 转换原则: 已是 .XSHG/.XSHE 形式直接 to_qmt; sh/sz 前缀剥掉; 裸 6 位按首字 (5/6/7/9→SH, 0/1/2/3→SZ) 加 .SH/.SZ.
+# ============================================================
+def _to_qmt_symbol(symbol: str) -> str:
+    s = (symbol or "").strip()
+    if not s:
+        return s
+    upper = s.upper()
+    if upper.endswith((".XSHG", ".XSHE", ".SH", ".SZ", ".SSE", ".SZE")):
+        # 统一转成 bridge 的 .SH / .SZ 形式
+        code, suf = s.rsplit(".", 1)
+        suf = suf.upper()
+        if suf in ("XSHG", "SSE", "SH"):
+            return f"{code}.SH"
+        if suf in ("XSHE", "SZE", "SZ"):
+            return f"{code}.SZ"
+        return s
+    # 兼容 sh600000 / sz000001
+    if upper.startswith(("SH", "SZ")) and len(upper) >= 8:
+        head = upper[:2]
+        code = upper[2:]
+        return f"{code}.{head}"
+    # 裸 6 位
+    if len(s) == 6 and s.isdigit():
+        if s[0] in ("5", "6", "7", "9"):
+            return f"{s}.SH"
+        if s[0] in ("0", "1", "2", "3"):
+            return f"{s}.SZ"
+    return s
+
+
+def _from_qmt_symbol(qmt_symbol: str) -> str:
+    """bridge 返回的 sh/sz 形式 → akquant 友好 (保留 .XSHG/.XSHE, 带 .X 利于识别)."""
+    s = (qmt_symbol or "").strip()
+    if not s or "." not in s:
+        return s
+    code, suf = s.rsplit(".", 1)
+    suf = suf.upper()
+    if suf == "SH":
+        return f"{code}.XSHG"
+    if suf == "SZ":
+        return f"{code}.XSHE"
+    return s
+
+
+# ============================================================
+# QMT 委托状态 (raw_status int) → UnifiedOrderStatus
+# QMT 内部状态码约定 (xtquant 标准, 与 bridge_server 直传):
+#   0=未知 1=待报 2=已报待撤 3=已撤 4=部撤 5=部成 6=已成 7=废单 8=已报未成
+# 实际不同 QMT 版本可能略不同 — 不确定时 fallback "New"
+# ============================================================
+_QMT_ORDER_STATUS_MAP = {
+    0: "New", 1: "Submitted", 2: "Submitted", 3: "Cancelled",
+    4: "Cancelled", 5: "PartiallyFilled", 6: "Filled", 7: "Rejected",
+    8: "Submitted",
+}
+
+
+def _map_order_status(raw: Any) -> Any:
+    """int → UnifiedOrderStatus; 失败返 New."""
+    ak = _import_akquant_gateway()
+    UnifiedOrderStatus = ak["UnifiedOrderStatus"]
+    if isinstance(raw, int) and raw in _QMT_ORDER_STATUS_MAP:
+        return UnifiedOrderStatus(_QMT_ORDER_STATUS_MAP[raw])
+    return UnifiedOrderStatus.NEW
+
+
+# ============================================================
+# QmtTraderGateway — akquant TraderGatewayBase 子类
+# ============================================================
+def _make_trader_gateway():
+    ak = _import_akquant_gateway()
+    TraderGatewayBase = ak["TraderGatewayBase"]
+
+    class QmtTraderGateway(TraderGatewayBase):
+        """走 bridge_server HTTP 的 akquant trader gateway.
+
+        kwargs 由 run_live(**kwargs) 透传到 builder, builder 再传到我:
+          base_url      (default "http://127.0.0.1:9000")
+          account_id    (必填)
+          account_type  (default "stock")
+          timeout       (default 5.0 秒)
+        """
+
+        # ---- 类级别常量: BrokerCapability ----
+        _CAP_NAME = "qmt"
+
+        def __init__(
+            self,
+            base_url: str = "http://127.0.0.1:9000",
+            account_id: str = "",
+            account_type: str = "stock",
+            timeout: float = 5.0,
+            paper: bool = True,
+        ) -> None:
+            """
+            paper: 默认 True — 安全默认, paper 模式下 place_order / cancel_order
+                   不发真 HTTP, 走本地 mock. 显式真下单必须 paper=False.
+            """
+            super().__init__()
+            ak = _import_akquant_gateway()
+            self._BrokerCapability = ak["BrokerCapability"]
+            self._UnifiedOrderRequest = ak["UnifiedOrderRequest"]
+            self._http = _HTTP(base_url, timeout=timeout)
+            self._account_id = account_id
+            self._account_type = account_type
+            self._connected = False
+            self._paper = paper
+            self._paper_order_seq = 0  # 仅 paper 模式用, mock 订单号递增
+            if paper:
+                _emit_paper(
+                    f"qmt broker paper 模式启动 — account={account_id} "
+                    f"place_order / cancel_order 不发真 HTTP, mock 返 PAPER-NNNNNN"
+                )
+
+        # ----- 生命周期 -----
+        def connect(self) -> None:
+            """调 /account 验证桥活 + 账户配 (bridge_server 没显式 /connect 协议)."""
+            data = self._http.post("/account", {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+            })
+            if not isinstance(data, dict) or not data.get("account_id"):
+                raise BrokerHTTPError(
+                    f"connect: /account 返回异常: {data!r}"
+                )
+            self._connected = True
+
+        def disconnect(self) -> None:
+            self._connected = False
+
+        def start(self) -> None:
+            """无推模式 (bridge_server 不主动 push). v0.2 加轮询 push."""
+            if not self._connected:
+                self.connect()
+
+        # ----- 能力声明 -----
+        def get_capabilities(self):  # type: ignore[override]
+            return self._BrokerCapability(
+                broker_name=self._CAP_NAME,
+                broker_live=True,
+                client_order_id=True,
+                order_type=True,
+                time_in_force_str=True,
+                position_effect=True,
+                reduce_only=False,
+                position_details=True,
+                supports_short_sell=False,
+                broker_extra_fields=(
+                    "strategy_name", "order_remark", "quick_trade",
+                    "qmt_pr_type",
+                ),
+                supported_position_effects=("auto", "open", "close"),
+                features=frozenset({
+                    "qmt_bridge",
+                    "bullettrade_compat",
+                    "http_polling_only",  # 标无 push, 给上层知道
+                }),
+            )
+
+        # ----- 下单 -----
+        def place_order(self, req):  # type: ignore[override]
+            if not self._connected:
+                raise BrokerHTTPError("place_order: 未 connect, 先调 start()/connect()")
+            # paper 模式: 不发真 HTTP, mock 返 PAPER-NNNNNN — e2e 验证不真下单
+            if self._paper:
+                self._paper_order_seq += 1
+                order_id = f"PAPER-{self._paper_order_seq:06d}"
+                self.record_broker_order(order_id, req.client_order_id)
+                _emit_paper(
+                    f"place_order 跳过真下单: symbol={req.symbol} side={req.side} "
+                    f"qty={req.quantity} price={req.price} → mock order_id={order_id}"
+                )
+                return order_id
+            ak = _import_akquant_gateway()
+            side = str(req.side).upper()
+            # bridge 的 amount 字段 — QMT 用 int, 但 akquant quantity 是 float, 截断到 int.
+            amount = int(req.quantity)
+            if amount <= 0:
+                raise BrokerHTTPError(
+                    f"place_order: amount 必须 > 0, got {req.quantity}"
+                )
+            order_type = str(req.order_type or "Market").lower()
+            # bridge pr_type: 11=限价 12=市价IOC 13=市价GFD. 默认按 order_type 推断.
+            pr_type = int(req.extra.get("qmt_pr_type", 0)) or (
+                11 if order_type in ("limit", "limit_if_touched") else 12
+            )
+            price = float(req.price or 0.0)
+            if pr_type != 12 and price <= 0:
+                raise BrokerHTTPError(
+                    f"place_order: 限价单需要 price > 0 (got {price}, pr_type={pr_type})"
+                )
+            payload = {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+                "security": _to_qmt_symbol(req.symbol),
+                "side": "BUY" if side in ("buy", "long", "b") else "SELL",
+                "amount": amount,
+                "price": price,
+                "pr_type": pr_type,
+                "strategy_name": str(req.extra.get("strategy_name", "hamuna_strategy")),
+                "order_remark": str(req.extra.get("order_remark") or req.client_order_id)[:24],
+                "quick_trade": int(req.extra.get("quick_trade", 0)),
+                "client_order_id": req.client_order_id,
+            }
+            data = self._http.post("/place_order", payload)
+            order_id = str(data.get("order_id") or data.get("order_ref") or "")
+            if order_id:
+                self.record_broker_order(order_id, req.client_order_id)
+            # 即便 order_id 空 (bridge 的 submit_unknown), 也返回它拿到的 ref, 让上层知道.
+            return order_id or str(data.get("passorder_return") or "")
+
+        # ----- 撤单 -----
+        def cancel_order(self, broker_order_id: str) -> None:
+            if not self._connected:
+                raise BrokerHTTPError("cancel_order: 未 connect")
+            if self._paper:
+                _emit_paper(f"cancel_order 跳过真撤单: broker_order_id={broker_order_id}")
+                return
+            self._http.post("/cancel_order", {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+                "order_id": broker_order_id,
+            })
+
+        # ----- 查询: 单委托 -----
+        def query_order(self, broker_order_id: str):  # type: ignore[override]
+            if not self._connected:
+                return None
+            try:
+                data = self._http.get("/orders", {
+                    "account_id": self._account_id,
+                    "account_type": self._account_type,
+                    "order_id": broker_order_id,
+                })
+            except BrokerHTTPError:
+                return None
+            orders = (data or {}).get("orders") or []
+            if not orders:
+                return None
+            o = orders[0]
+            ak = _import_akquant_gateway()
+            client_oid = self.client_order_id_for(broker_order_id) or str(
+                o.get("qmt_user_order_id") or o.get("order_remark") or ""
+            )
+            return ak["UnifiedOrderSnapshot"](
+                client_order_id=client_oid,
+                broker_order_id=str(o.get("order_id") or broker_order_id),
+                symbol=_from_qmt_symbol(str(o.get("security") or "")),
+                status=_map_order_status(o.get("raw_status")),
+                filled_quantity=float(o.get("filled") or 0),
+                avg_fill_price=float(o.get("price") or 0.0),
+                position_effect=str(
+                    {"OPEN": "open", "CLOSE": "close"}.get(
+                        str(o.get("position_effect") or "").upper(), "auto"
+                    )
+                ),
+            )
+
+        # ----- 查询: 成交 -----
+        def query_trades(self, since=None):  # type: ignore[override]
+            if not self._connected:
+                return []
+            data = self._http.get("/trades", {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+            })
+            ak = _import_akquant_gateway()
+            UnifiedTrade = ak["UnifiedTrade"]
+            out: list = []
+            for t in (data or {}).get("trades") or []:
+                oid = str(t.get("order_id") or "")
+                client_oid = self.client_order_id_for(oid) or str(
+                    t.get("qmt_user_order_id") or t.get("order_remark") or ""
+                )
+                out.append(UnifiedTrade(
+                    trade_id=str(t.get("trade_id") or ""),
+                    broker_order_id=oid,
+                    client_order_id=client_oid,
+                    symbol=_from_qmt_symbol(str(t.get("security") or "")),
+                    side="buy" if str(t.get("side") or "").upper() == "BUY" else "sell",
+                    quantity=float(t.get("amount") or 0),
+                    price=float(t.get("price") or 0.0),
+                    timestamp_ns=int(t.get("timestamp_ns") or 0),
+                    position_effect="auto",
+                ))
+            return out
+
+        # ----- 查询: 账户 -----
+        def query_account(self):  # type: ignore[override]
+            if not self._connected:
+                return None
+            data = self._http.post("/account", {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+            })
+            ak = _import_akquant_gateway()
+            return ak["UnifiedAccount"](
+                account_id=str(data.get("account_id") or self._account_id),
+                equity=float(data.get("total_value") or 0.0),
+                cash=float(data.get("cash") or 0.0),
+                available_cash=float(data.get("available_cash") or 0.0),
+                timestamp_ns=int(data.get("timestamp_ns") or 0),
+            )
+
+        # ----- 查询: 持仓 -----
+        def query_positions(self):  # type: ignore[override]
+            if not self._connected:
+                return []
+            data = self._http.post("/positions", {
+                "account_id": self._account_id,
+                "account_type": self._account_type,
+            })
+            ak = _import_akquant_gateway()
+            UnifiedPosition = ak["UnifiedPosition"]
+            out: list = []
+            for p in (data or {}).get("positions") or []:
+                qty = int(p.get("amount") or 0)
+                out.append(UnifiedPosition(
+                    symbol=_from_qmt_symbol(str(p.get("security") or "")),
+                    quantity=float(qty),
+                    available_quantity=float(p.get("closeable_amount") or 0),
+                    direction="long" if qty >= 0 else "short",
+                    today_quantity=0.0,
+                    yesterday_quantity=0.0,
+                    avg_price=float(p.get("avg_cost") or 0.0),
+                ))
+            return out
+
+        # ----- heartbeat -----
+        def heartbeat(self) -> bool:
+            """基础探活: 调 /health (无 body), 不更新 _connected."""
+            try:
+                self._http.get("/health")
+                return True
+            except BrokerHTTPError:
+                return False
+
+    return QmtTraderGateway
+
+
+# ============================================================
+# builder + register
+# ============================================================
+def build_qmt(
+    feed: Any,
+    symbols: list[str],
+    use_aggregator: bool,
+    **kwargs: Any,
+) -> Any:
+    """akquant run_live(broker="qmt", ...) 的 builder 入口.
+
+    kwargs:
+      qmt_base_url     (default "http://127.0.0.1:9000")
+      qmt_account_id   (必填)
+      qmt_account_type (default "stock")
+      qmt_timeout      (default 5.0 秒)
+      qmt_paper        (default "1"=paper; 显式真下单设 "0" — 默认安全)
+    """
+    base_url = kwargs.get("qmt_base_url") or kwargs.get("base_url") or "http://127.0.0.1:9000"
+    account_id = kwargs.get("qmt_account_id") or kwargs.get("account_id") or ""
+    account_type = kwargs.get("qmt_account_type") or kwargs.get("account_type") or "stock"
+    timeout = float(kwargs.get("qmt_timeout") or kwargs.get("timeout") or 30.0)  # ponytail: 跟 _HTTP.timeout 默认 30s 保持一致 (caller 显式传 timeout=5.0 会盖过这里默认, 但 build_qmt 不传 timeout 时必须 30s 才治网络抖动)
+    paper = _qmt_paper_default(kwargs.get("qmt_paper"))
+    if not account_id:
+        raise ValueError(
+            "hamuna_qmt_broker: 缺少 qmt_account_id — 透传给 run_live(..., qmt_account_id='...')"
+        )
+    ak = _import_akquant_gateway()
+    QmtTraderGateway = _make_trader_gateway()
+    trader = QmtTraderGateway(
+        base_url=base_url, account_id=account_id, account_type=account_type,
+        timeout=timeout, paper=paper,
+    )
+    return ak["GatewayBundle"](
+        market_gateway=None,  # 行情走 akquant DataFeed (无 push)
+        trader_gateway=trader,
+        trader_capabilities=trader.get_capabilities(),
+        metadata={"broker": "qmt", "bridge": "bullettrade_compat", "paper": paper},
+    )
+
+
+def _qmt_paper_default(v: Any) -> bool:
+    """CLI 字符串 → paper bool. 默认 True (安全).
+    显式 "0"/"false"/"no"/"off" → False (真下单); 其它 (含 None/""/"1"/"true") → True (paper)."""
+    if v is None or v == "":
+        return True
+    s = str(v).strip().lower()
+    if s in ("0", "false", "no", "off"):
+        return False
+    return True
+
+
+# 注册 (side-effect import). akquant 未装时不抛 — 让 --help 仍能跑.
+def _safe_register() -> None:
+    try:
+        ak = _import_akquant_gateway()
+        ak["register_broker"]("qmt", build_qmt)
+    except ImportError:
+        pass
+
+
+_safe_register()
+
+
+# ============================================================
+# self-check — 不依赖 akquant, 起本地 mock bridge_server, 验证 HTTP shape
+# ============================================================
+if __name__ == "__main__":
+    import threading
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    class _MockBridge(BaseHTTPRequestHandler):
+        def log_message(self, fmt, *args):
+            pass  # 静音
+
+        def _read_json(self):
+            length = int(self.headers.get("Content-Length") or 0)
+            return json.loads(self.rfile.read(length).decode("utf-8")) if length else {}
+
+        def _send(self, code, payload):
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self):
+            if self.path.startswith("/health"):
+                self._send(200, {"ok": True, "data": {"status": "ok"}})
+                return
+            if self.path.startswith("/orders"):
+                self._send(200, {"ok": True, "data": {"orders": [{
+                    "order_id": "ORD1", "security": "600000.SH", "raw_status": 6,
+                    "filled": 100, "price": 10.5, "amount": 100,
+                    "qmt_user_order_id": "coid1",
+                }]}})
+                return
+            if self.path.startswith("/trades"):
+                self._send(200, {"ok": True, "data": {"trades": [{
+                    "trade_id": "TRD1", "order_id": "ORD1", "security": "600000.SH",
+                    "amount": 100, "price": 10.5, "side": "BUY",
+                    "qmt_user_order_id": "coid1",
+                }]}})
+                return
+            self._send(404, {"ok": False, "code": "NOT_FOUND"})
+
+        def do_POST(self):
+            data = self._read_json()
+            if "/account" in self.path:
+                self._send(200, {"ok": True, "data": {
+                    "account_id": data.get("account_id"), "account_type": "stock",
+                    "available_cash": 50000.0, "cash": 100000.0, "total_value": 150000.0,
+                }})
+                return
+            if "/positions" in self.path:
+                self._send(200, {"ok": True, "data": {"positions": [{
+                    "security": "600000.SH", "amount": 100, "closeable_amount": 100,
+                    "avg_cost": 10.0,
+                }]}})
+                return
+            if "/place_order" in self.path:
+                self._send(200, {"ok": True, "data": {
+                    "order_id": "ORD2", "order_ref": "ORD2", "security": "600000.SH",
+                    "side": data.get("side"), "amount": data.get("amount"),
+                    "price": data.get("price"),
+                }})
+                return
+            if "/cancel_order" in self.path:
+                self._send(200, {"ok": True, "data": {"cancelled": True}})
+                return
+            self._send(404, {"ok": False, "code": "NOT_FOUND"})
+
+    server = HTTPServer(("127.0.0.1", 0), _MockBridge)
+    port = server.server_address[1]
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    print(f"[self-check] mock bridge_server at http://127.0.0.1:{port}")
+
+    # 1. symbol 映射 (无 akquant 依赖)
+    assert _to_qmt_symbol("sh600000") == "600000.SH"
+    assert _to_qmt_symbol("600000.XSHG") == "600000.SH"
+    assert _to_qmt_symbol("sz000001") == "000001.SZ"
+    assert _to_qmt_symbol("000001.XSHE") == "000001.SZ"
+    assert _from_qmt_symbol("600000.SH") == "600000.XSHG"
+    assert _from_qmt_symbol("000001.SZ") == "000001.XSHE"
+    print("[self-check] OK symbol 映射")
+
+    # 2. HTTP client — 6 个 endpoint shape 验证
+    http = _HTTP(f"http://127.0.0.1:{port}", timeout=2.0)
+    acct = http.post("/account", {"account_id": "ACCT", "account_type": "stock"})
+    assert acct["available_cash"] == 50000.0, acct
+    pos = http.post("/positions", {"account_id": "ACCT"})
+    assert pos["positions"][0]["security"] == "600000.SH", pos
+    order = http.post("/place_order", {
+        "account_id": "ACCT", "security": "600000.SH", "side": "BUY",
+        "amount": 100, "price": 10.0,
+    })
+    assert order["order_id"] == "ORD2", order
+    http.post("/cancel_order", {"account_id": "ACCT", "order_id": "ORD2"})
+    orders = http.get("/orders", {"account_id": "ACCT", "order_id": "ORD1"})
+    assert orders["orders"][0]["raw_status"] == 6
+    trades = http.get("/trades", {"account_id": "ACCT"})
+    assert trades["trades"][0]["trade_id"] == "TRD1"
+    print("[self-check] OK HTTP client shape")
+
+    # 3. akquant 协议 — 检查 TraderGatewayBase 子类化 + 方法齐
+    try:
+        ak = _import_akquant_gateway()
+    except ImportError as e:
+        print(f"[self-check] akquant 未装 ({e.__cause__ or e}) — 跳过协议层验证")
+    else:
+        QmtTraderGateway = _make_trader_gateway()
+        # 实例化 (不连, 只查 shape)
+        gw = QmtTraderGateway(
+            base_url=f"http://127.0.0.1:{port}", account_id="ACCT", account_type="stock",
+            timeout=2.0,
+        )
+        for name in (
+            "connect", "disconnect", "start", "place_order", "cancel_order",
+            "query_order", "query_trades", "query_account", "query_positions",
+            "get_capabilities", "heartbeat", "on_order", "on_trade",
+            "on_execution_report", "record_broker_order", "client_order_id_for",
+        ):
+            assert hasattr(gw, name), f"missing {name}"
+        cap = gw.get_capabilities()
+        assert cap.broker_name == "qmt"
+        assert "qmt_bridge" in cap.features
+        print("[self-check] OK akquant 协议点齐 (TraderGatewayBase 子类)")
+        # 4. e2e: 真实 connect / place / cancel / query
+        gw.connect()
+        a = gw.query_account()
+        assert a.account_id == "ACCT" and a.available_cash == 50000.0, a
+        ps = gw.query_positions()
+        assert len(ps) == 1 and ps[0].symbol == "600000.XSHG", ps
+        oid = gw.place_order(ak["UnifiedOrderRequest"](
+            client_order_id="coid-test", symbol="600000.XSHG", side="buy",
+            quantity=100, price=10.0, order_type="Limit",
+        ))
+        assert oid == "ORD2", oid
+        gw.cancel_order(oid)
+        snap = gw.query_order("ORD1")
+        # raw_status=6 → Filled, 但 query_order 不一定拿到 coid 反查 (mock 返回 ORD1 没在 record 里)
+        # 测试 record_broker_order + 反查
+        gw.record_broker_order("ORD1", "coid-test")
+        snap2 = gw.query_order("ORD1")
+        assert snap2 is not None and snap2.symbol == "600000.XSHG", snap2
+        print("[self-check] OK e2e connect→place→cancel→query")
+
+    server.shutdown()
+    print("[self-check] ALL PASSED")