akquant 0.3.1__tar.gz → 0.3.2__tar.gz

{akquant-0.3.1 → akquant-0.3.2}/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `BacktestConfig` 新增 `days_per_year`（年化天数因子，默认 252；数字货币 24/7 市场可设 365）与 `risk_free_rate`（年化无风险利率，默认 0.0）两个字段，用于参数化 Sharpe/Sortino/波动率等风险指标的年化口径。`risk_free_rate` 默认 0 不改变任何现有数值。
 
 ### Changed
+- **`buy`/`sell`/`submit_order` 返回类型变更（破坏性）**：三者现统一返回 `OrderReceipt`（原为 `str` 订单号），回测与实盘（`broker_live`）两种模式返回类型一致；实盘 `submit_order` 此前会将多腿委托（如反手拆分的平仓+开仓、开平分离）收窄为单一 id 字符串，现已修复为返回携带全部腿 id 的完整 `OrderReceipt`。取单个订单 id 用 `receipt.primary`（首腿 broker_order_id，兼容旧用法），取全部腿 id 用 `receipt.order_ids`；`str(receipt)` 取 `group_id`（逻辑委托的客户端订单号），关联成交请用 `trade.group_id` 而非逐个 order_id 比对；新增 `cancel_group(group_id)` 用于一次性撤销一个逻辑委托的全部腿。
 - **回测指标口径变更（破坏性）**：Sharpe / Sortino 比率的分子改为「日收益算术均值 × `days_per_year`」做年化，替代原先的 CAGR（复合年化），与 pyfolio/empyrical/quantstats 等主流实现一致，并与分母 `√days_per_year` 的年化口径匹配。升级后历史报告的 Sharpe/Sortino 数值会变化，不可直接与旧版逐值对比；UPI 与 Calmar 仍沿用 CAGR 口径。
 - 策略交易日边界回调已硬切改名：`before_trading(trading_date, timestamp)` 更名为 `on_before_trading(trading_date, timestamp)`，`after_trading(trading_date, timestamp)` 更名为 `on_after_trading(trading_date, timestamp)`。
 - 旧回调名不再保留兼容别名；升级到当前版本后，若策略仍实现 `before_trading` / `after_trading`，将不会再被框架触发，请同步迁移到新名称。

{akquant-0.3.1 → akquant-0.3.2}/Cargo.lock

@@ -30,7 +30,7 @@ dependencies = [
 
 [[package]]
 name = "akquant"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "anyhow",
  "chrono",

{akquant-0.3.1 → akquant-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "akquant"
-version = "0.3.1"
+version = "0.3.2"
 edition = "2024"
 description = "High-performance quantitative trading framework based on Rust and Python"
 license = "MIT"

{akquant-0.3.1 → akquant-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akquant
-Version: 0.3.1
+Version: 0.3.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{akquant-0.3.1 → akquant-0.3.2}/docs/zh/guide/strategy.md

@@ -774,8 +774,44 @@ AKQuant 当前的订单语义已经不再是单纯的 `side`，而是 `side + po
 
 *   **撤单 (Cancel Order)**:
     *   `self.cancel_order(order_id)`: 撤销指定订单。
+    *   `self.cancel_group(group_id)`: 按 `group_id` 撤销一个逻辑委托拆出的全部腿。
     *   `self.cancel_all_orders()`: 撤销当前所有未成交订单。
 
+### 7.2.2 OrderReceipt：下单回执与 group_id
+
+`buy()` / `sell()` / `submit_order()` 统一返回 `OrderReceipt`（回测与
+`broker_live` 实盘两种模式返回类型一致，不再是裸 `str` 订单号）：
+
+*   `receipt.primary`：首腿的订单 id（`broker_order_id`），多数场景下当作
+    "这笔下单的订单号" 使用，等价于旧版直接拿到的 `str`。
+*   `receipt.order_ids`：全部腿的订单 id 元组。一次 `side + position_effect="auto"`
+    调用在持有反向仓位时会被自动拆成 `close` + `open` 两腿（或期货 `close_today`
+    / `close_yesterday` 两腿），此时 `order_ids` 长度 > 1，`primary` 只是其中一腿。
+*   `str(receipt)`：逻辑委托的 `group_id`（客户端订单号），用于把拆出的多腿关联为
+    "同一次下单"；与 `receipt.primary` 是两个不同的 id 空间，不要混用。
+*   关联成交回报时优先用 `trade.group_id` 而不是逐个 `order_id` 比对，这样无论
+    该笔委托是否被拆腿都能正确聚合。
+
+跨 `close + open` 的反手示例（先平后开，两腿在同一次 `buy()`/`sell()` 调用里发出）：
+
+```python
+def on_bar(self, bar):
+    # 当前持有空头仓位，买入 300 手：自动拆成「平空 200 手」+「开多 100 手」两腿
+    receipt = self.buy(bar.symbol, quantity=300)  # position_effect 默认 "auto"
+
+    print(receipt.primary)      # 首腿(平仓腿)的订单 id，兼容旧版单一 str 用法
+    print(receipt.order_ids)    # (平仓腿 id, 开仓腿 id) —— 全部腿
+    print(str(receipt))         # group_id：这次逻辑委托的客户端订单号
+
+    # 想整单撤销（两腿都撤）：
+    self.cancel_group(receipt)  # 等价于 self.cancel_group(str(receipt))
+
+def on_trade(self, trade):
+    # 用 group_id 聚合同一次逻辑委托拆出的多腿成交，而不是比较单个 order_id
+    if trade.group_id == self._entry_group_id:
+        ...
+```
+
 ### 7.3 OCO 与 Bracket 助手
 
 AKQuant 提供了两组交易助手，减少策略中手写订单联动逻辑：

{akquant-0.3.1 → akquant-0.3.2}/examples/36_trailing_orders.py

@@ -23,7 +23,8 @@ class TrailingOrderStrategy(Strategy):
             and not self.entry_order_id
             and not self.trailing_order_id
         ):
-            self.entry_order_id = self.buy(bar.symbol, 100, tag="trail-entry")
+            entry_receipt = self.buy(bar.symbol, 100, tag="trail-entry")
+            self.entry_order_id = str(getattr(entry_receipt, "primary", entry_receipt))
             print(
                 f"[{bar.timestamp_iso}] 提交进场单: {bar.symbol}, close={bar.close:.2f}"
             )
@@ -37,7 +38,7 @@ class TrailingOrderStrategy(Strategy):
         if trade.order_id == self.entry_order_id:
             self.entry_order_id = ""
             ref_price = self.last_close.get(trade.symbol, float(trade.price))
-            self.trailing_order_id = self.place_trailing_stop(
+            trailing_receipt = self.place_trailing_stop(
                 symbol=trade.symbol,
                 quantity=float(trade.quantity),
                 trail_offset=self.trail_offset,
@@ -45,6 +46,9 @@ class TrailingOrderStrategy(Strategy):
                 trail_reference_price=ref_price,
                 tag="trail-stop",
             )
+            self.trailing_order_id = str(
+                getattr(trailing_receipt, "primary", trailing_receipt)
+            )
             print(
                 f"[{trade.timestamp}] 提交 trailing stop: symbol={trade.symbol}, "
                 f"offset={self.trail_offset:.2f}, ref={ref_price:.2f}"

{akquant-0.3.1 → akquant-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "akquant"
-version = "0.3.1"
+version = "0.3.2"
 description = "High-performance quantitative trading framework based on Rust and Python"
 readme = "README.md"
 license = {text = "MIT License"}

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/__init__.py

@@ -52,6 +52,7 @@ from .feed_adapter import (
     ReplayFeedAdapter,
     ResampledFeedAdapter,
 )
+from .gateway.order_receipt import OrderLeg, OrderReceipt
 from .indicator import Indicator, IndicatorSet
 from .indicator_stream import (
     is_indicator_stream_event,
@@ -181,6 +182,8 @@ if hasattr(_akquant, "__all__"):  # noqa: F405
         "validate_strategy_params",
         "extract_runtime_kwargs",
         "build_param_grid_from_search_space",
+        "OrderLeg",
+        "OrderReceipt",
         "talib",
     ]
 else:
@@ -259,6 +262,8 @@ else:
         "validate_strategy_params",
         "extract_runtime_kwargs",
         "build_param_grid_from_search_space",
+        "OrderLeg",
+        "OrderReceipt",
         "talib",
     ]
 

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/akquant.pyi

@@ -112,7 +112,7 @@ class TimeInForce:
     GTC: typing.ClassVar["TimeInForce"]
     IOC: typing.ClassVar["TimeInForce"]
     FOK: typing.ClassVar["TimeInForce"]
-    GTD: typing.ClassVar["TimeInForce"]
+    Day: typing.ClassVar["TimeInForce"]
 
 class TradingSession:
     Normal: typing.ClassVar["TradingSession"]

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/execution/sim.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from .. import strategy_trading_api as api
+from ..gateway.order_receipt import OrderReceipt
 
 
 class SimExecution:
@@ -50,8 +51,8 @@ class SimExecution:
         """获取现金."""
         return api._sim_get_cash(self._s)
 
-    def submit_order(self, **kwargs: Any) -> str:
-        """提交订单，返回订单号."""
+    def submit_order(self, **kwargs: Any) -> OrderReceipt:
+        """提交订单，返回 OrderReceipt（携带回测拆腿产生的全部订单 id）."""
         return api._sim_submit_order(self._s, **kwargs)
 
     def cancel_order(self, order_id: str) -> None:

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/gateway/broker_event_adapter.py

@@ -44,6 +44,7 @@ class StrategyOrder:
     client_order_id: str = ""
     broker_order_id: str = ""
     owner_strategy_id: Optional[str] = None
+    group_id: str = ""
 
 
 @dataclass
@@ -62,6 +63,7 @@ class StrategyTrade:
     client_order_id: str = ""
     broker_order_id: str = ""
     owner_strategy_id: Optional[str] = None
+    group_id: str = ""
 
 
 _STATUS_MAP = {
@@ -138,8 +140,8 @@ def _to_tif(value: Any) -> Optional[Any]:
         "GTC": TimeInForce.GTC,
         "IOC": TimeInForce.IOC,
         "FOK": TimeInForce.FOK,
-        "GTD": TimeInForce.GTD,
-        "DAY": TimeInForce.GTD,
+        "GTD": TimeInForce.Day,
+        "DAY": TimeInForce.Day,
     }
     return mapping.get(text)
 
@@ -149,6 +151,7 @@ def map_order_snapshot(
     request: Any = None,
     owner_strategy_id: Optional[str] = None,
     local_id: Optional[str] = None,
+    group_id: str = "",
 ) -> StrategyOrder:
     """把 UnifiedOrderSnapshot 映射成与回测 Order 同形状的 StrategyOrder."""
     broker_order_id = str(_get(snapshot, "broker_order_id", "") or "")
@@ -186,6 +189,7 @@ def map_order_snapshot(
         client_order_id=str(_get(snapshot, "client_order_id", "") or ""),
         broker_order_id=broker_order_id,
         owner_strategy_id=owner_strategy_id,
+        group_id=group_id,
     )
 
 
@@ -236,6 +240,7 @@ def map_trade(
     request: Any = None,
     owner_strategy_id: Optional[str] = None,
     local_id: Optional[str] = None,
+    group_id: str = "",
 ) -> StrategyTrade:
     """把 UnifiedTrade 映射成与回测 Trade 同形状的 StrategyTrade."""
     return StrategyTrade(
@@ -251,4 +256,5 @@ def map_trade(
         client_order_id=str(_get(trade, "client_order_id", "") or ""),
         broker_order_id=str(_get(trade, "broker_order_id", "") or ""),
         owner_strategy_id=owner_strategy_id,
+        group_id=group_id,
     )

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/gateway/broker_execution.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 from ..log import get_logger
 from .broker_event_adapter import map_local_stop, map_order_snapshot
@@ -14,6 +14,7 @@ from .local_stop_book import (
     is_stop_order_type,
     underlying_order_type,
 )
+from .order_receipt import OrderReceipt
 
 logger = get_logger("gateway.live")
 
@@ -30,13 +31,15 @@ class BrokerExecution:
         state_cache: BrokerStateCache,
         submitter: Any,
         record_stop_remap: Any = None,
+        group_broker_ids: Any = None,
     ) -> None:
-        """绑定策略实例、柜台网关、状态缓存、下单器与止损 remap 回调."""
+        """绑定策略实例、柜台网关、状态缓存、下单器、止损 remap 与 group 反查回调."""
         self._s = strategy
         self._gw = trader_gateway
         self._cache = state_cache
         self._submitter = submitter
         self._record_stop_remap = record_stop_remap
+        self._group_broker_ids = group_broker_ids
         self._stop_book = LocalStopBook()
         self._stop_seq = 0
         self._warned_hold_bar = False
@@ -126,11 +129,12 @@ class BrokerExecution:
         """获取现金."""
         return float(getattr(self._cache.account(), "cash", 0.0) or 0.0)
 
-    def submit_order(self, **kwargs: Any) -> str:
-        """提交订单，返回订单号.
+    def submit_order(self, **kwargs: Any) -> OrderReceipt:
+        """提交订单，返回下单回执（OrderReceipt，含全部腿 id）.
 
         条件/止损单（trigger_price/trail_offset 或止损类 order_type）拦截入
-        本地簿，不下发柜台；柜台不支持这类原生条件单。
+        本地簿，不下发柜台；柜台不支持这类原生条件单——本地止损单只有单一
+        本地 id，封装为单腿 OrderReceipt 以保持返回类型与柜台下单一致。
 
         time_in_force=None（Strategy.submit_order 的缺省值）会显式覆盖
         submitter.submit_order 签名默认值 "GTC"；这里丢弃 None，
@@ -141,10 +145,16 @@ class BrokerExecution:
             or kwargs.get("trail_offset") is not None
             or is_stop_order_type(kwargs.get("order_type"))
         ):
-            return self._register_local_stop(**kwargs)
+            local_id = self._register_local_stop(**kwargs)
+            return OrderReceipt.single(
+                group_id=local_id,
+                broker_order_id=local_id,
+                position_effect=str(kwargs.get("position_effect") or "auto"),
+                client_order_id=local_id,
+            )
         if kwargs.get("time_in_force") is None:
             kwargs.pop("time_in_force", None)
-        return str(self._submitter.submit_order(**kwargs))
+        return cast(OrderReceipt, self._submitter.submit_order(**kwargs))
 
     def _next_local_stop_id(self) -> str:
         self._stop_seq += 1
@@ -205,7 +215,7 @@ class BrokerExecution:
             if order.time_in_force is not None:
                 kwargs["time_in_force"] = order.time_in_force
             try:
-                broker_order_id = str(self._submitter.submit_order(**kwargs))
+                broker_order_id = str(self._submitter.submit_order(**kwargs).primary)
             except Exception as exc:  # noqa: BLE001
                 order.submit_attempts += 1
                 if order.submit_attempts < MAX_STOP_SUBMIT_ATTEMPTS:
@@ -233,6 +243,15 @@ class BrokerExecution:
             return
         self._gw.cancel_order(str(order_id))
 
+    def cancel_group(self, group_id: str) -> None:
+        """撤销一个逻辑委托的全部腿（按 group_id）."""
+        gid = str(group_id)
+        if self._group_broker_ids is None:
+            return
+        for broker_order_id in self._group_broker_ids(gid):
+            if broker_order_id:
+                self.cancel_order(str(broker_order_id))
+
     def cancel_all_orders(self, symbol: str | None = None) -> None:
         """取消所有未完成订单(含本地止损)."""
         for order in self._stop_book.open_orders(symbol):

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/gateway/broker_models.py

@@ -195,6 +195,7 @@ class UnifiedOrderSnapshot:
     reject_reason: str = ""
     timestamp_ns: int = 0
     position_effect: str = "auto"
+    group_id: str = ""
 
 
 @dataclass
@@ -210,6 +211,7 @@ class UnifiedTrade:
     price: float
     timestamp_ns: int
     position_effect: str = "auto"
+    group_id: str = ""
 
 
 @dataclass
@@ -225,6 +227,7 @@ class UnifiedExecutionReport:
     reject_reason: str = ""
     timestamp_ns: int = 0
     position_effect: str = "auto"
+    group_id: str = ""
 
 
 @dataclass

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/gateway/broker_runtime.py

@@ -38,6 +38,8 @@ class BrokerRuntime:
         adapt_strategy_payload: Callable[[str, Any], Any],
         record_stop_remap: Any = None,
         should_replay_trades: Callable[[], bool] | None = None,
+        sync_group_mapping: Callable[[str, str], None] = lambda _c, _g: None,
+        group_broker_ids: Callable[[str], list[str]] | None = None,
     ) -> None:
         """Assemble broker submitter, event bridge and recovery coordinators."""
         self._broker_state_caches: list[Any] = []
@@ -76,6 +78,8 @@ class BrokerRuntime:
         self._get_execution_capabilities = get_execution_capabilities
         self._record_order_request = record_order_request
         self._record_stop_remap = record_stop_remap
+        self._sync_group_mapping = sync_group_mapping
+        self._group_broker_ids = group_broker_ids
         self._submitter: BrokerOrderSubmitter | None = None
 
     @property
@@ -114,6 +118,7 @@ class BrokerRuntime:
             payload_field=self._payload_field,
             get_execution_capabilities=self._get_execution_capabilities,
             record_order_request=self._record_order_request,
+            sync_group_mapping=self._sync_group_mapping,
         )
         self._submitter.install()
 
@@ -130,6 +135,7 @@ class BrokerRuntime:
             cache,
             self._submitter,
             record_stop_remap=self._record_stop_remap,
+            group_broker_ids=self._group_broker_ids,
         )
 
         return self._submitter

akquant-0.3.2/python/akquant/gateway/order_receipt.py

@@ -0,0 +1,60 @@
+"""OrderReceipt: 逻辑委托的返回句柄，携带跨边界拆出的全部腿 id 与语义."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class OrderLeg:
+    """单腿委托：语义 + client/broker id."""
+
+    position_effect: str
+    quantity: float
+    client_order_id: str
+    broker_order_id: str
+
+
+@dataclass(frozen=True)
+class OrderReceipt:
+    """一次下单调用的结果：一个逻辑委托可拆成多腿分别报单."""
+
+    group_id: str
+    order_ids: tuple[str, ...]
+    legs: tuple[OrderLeg, ...]
+
+    def __str__(self) -> str:
+        """Return group_id as string representation."""
+        return self.group_id
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over order_ids."""
+        return iter(self.order_ids)
+
+    def __len__(self) -> int:
+        """Return count of order_ids."""
+        return len(self.order_ids)
+
+    @property
+    def primary(self) -> str:
+        """Return first order_id or empty string if no ids."""
+        return self.order_ids[0] if self.order_ids else ""
+
+    @classmethod
+    def single(
+        cls,
+        group_id: str,
+        broker_order_id: str,
+        position_effect: str = "auto",
+        quantity: float = 0.0,
+        client_order_id: str = "",
+    ) -> "OrderReceipt":
+        """Create a single-leg receipt for convenience."""
+        leg = OrderLeg(
+            position_effect=position_effect,
+            quantity=quantity,
+            client_order_id=client_order_id or group_id,
+            broker_order_id=broker_order_id,
+        )
+        return cls(group_id=group_id, order_ids=(broker_order_id,), legs=(leg,))

{akquant-0.3.1 → akquant-0.3.2}/python/akquant/gateway/order_submitter.py

@@ -8,6 +8,7 @@ from .broker_models import (
     validate_broker_extra,
     validate_execution_semantics,
 )
+from .order_receipt import OrderLeg, OrderReceipt
 
 logger = get_logger("gateway.live")
 
@@ -38,49 +39,38 @@ def find_live_close_position(
     return None
 
 
-def resolve_live_order_legs(
+def _split_close_legs(
     trader_gateway: Any,
     capability: BrokerCapability,
     symbol: str,
     side: str,
     quantity: float,
-    position_effect: str,
-    reduce_only: bool,
+    supported_effects: set[str],
     payload_field: Callable[[Any, str], Any],
 ) -> list[tuple[str, float]]:
-    """Resolve close orders into close_today/close_yesterday legs when supported."""
-    normalized_effect = str(position_effect).strip().lower()
-    if quantity <= 0 or reduce_only or normalized_effect != "close":
-        return [(normalized_effect, quantity)]
-    supported_effects = {
-        str(item).strip().lower() for item in capability.supported_position_effects
-    }
+    """把一段平仓量拆成 close_today/close_yesterday；能力不足则整段 close."""
     if not capability.position_details:
-        return [(normalized_effect, quantity)]
+        return [("close", quantity)]
     if (
         "close_today" not in supported_effects
         or "close_yesterday" not in supported_effects
     ):
-        return [(normalized_effect, quantity)]
-
+        return [("close", quantity)]
     query_positions = getattr(trader_gateway, "query_positions", None)
     if not callable(query_positions):
-        return [(normalized_effect, quantity)]
+        return [("close", quantity)]
     try:
         positions = query_positions()
     except Exception:
-        return [(normalized_effect, quantity)]
-
+        return [("close", quantity)]
     target_position = find_live_close_position(positions, symbol, side, payload_field)
     if target_position is None:
-        return [(normalized_effect, quantity)]
-
+        return [("close", quantity)]
     available_today = max(
         0.0, float(getattr(target_position, "available_today_quantity", 0.0) or 0.0)
     )
     available_yesterday = max(
-        0.0,
-        float(getattr(target_position, "available_yesterday_quantity", 0.0) or 0.0),
+        0.0, float(getattr(target_position, "available_yesterday_quantity", 0.0) or 0.0)
     )
     split_quantity = min(quantity, available_today + available_yesterday)
     legs: list[tuple[str, float]] = []
@@ -99,6 +89,95 @@ def resolve_live_order_legs(
     return legs
 
 
+def resolve_live_order_legs(
+    trader_gateway: Any,
+    capability: BrokerCapability,
+    symbol: str,
+    side: str,
+    quantity: float,
+    position_effect: str,
+    reduce_only: bool,
+    payload_field: Callable[[Any, str], Any],
+) -> list[tuple[str, float]]:
+    """Resolve close orders into close_today/close_yesterday legs when supported.
+
+    Also resolves `auto` reversal orders (sell/buy quantity exceeding the opposite
+    position) into close leg(s) plus a trailing `open` leg, unless the broker
+    declares it handles reversal itself via `"auto_reverse" in capability.features`.
+    """
+    normalized_effect = str(position_effect).strip().lower()
+    if quantity <= 0 or reduce_only:
+        return [(normalized_effect, quantity)]
+
+    supported_effects = {
+        str(item).strip().lower() for item in capability.supported_position_effects
+    }
+
+    # 反手：auto 单卖出量超过反向持仓可用量时，核心拆成 平仓 + 开仓。
+    # broker 若声明自身会反手(auto_reverse)，则不拆。
+    if normalized_effect == "auto":
+        if "auto_reverse" in capability.features:
+            return [(normalized_effect, quantity)]
+        if "open" not in supported_effects or "close" not in supported_effects:
+            return [(normalized_effect, quantity)]
+        query_positions = getattr(trader_gateway, "query_positions", None)
+        if not callable(query_positions):
+            return [(normalized_effect, quantity)]
+        try:
+            positions = query_positions()
+        except Exception:
+            return [(normalized_effect, quantity)]
+        target = find_live_close_position(positions, symbol, side, payload_field)
+        if target is None:
+            return [(normalized_effect, quantity)]
+        raw_today = payload_field(target, "available_today_quantity")
+        raw_yesterday = payload_field(target, "available_yesterday_quantity")
+        raw_available = payload_field(target, "available_quantity")
+        has_availability = any(
+            value is not None for value in (raw_today, raw_yesterday, raw_available)
+        )
+        available_split = max(0.0, float(raw_today or 0.0)) + max(
+            0.0, float(raw_yesterday or 0.0)
+        )
+        available_quantity = max(0.0, float(raw_available or 0.0))
+        raw_quantity = abs(float(payload_field(target, "quantity") or 0.0))
+        # 可平口径与 _split_close_legs 一致: broker 报可用量时优先用今昨可用量,
+        # 其次 available_quantity(即便为 0 也不回退——全冻结应交由下方 closable<=0
+        # 门槛退回单腿 auto); 仅当 broker 完全不提供可用量字段时才退回原始持仓。
+        if has_availability:
+            closable = available_split if available_split > 0 else available_quantity
+        else:
+            closable = raw_quantity
+        if closable <= 0 or quantity <= closable:
+            return [(normalized_effect, quantity)]
+        close_qty = closable
+        open_qty = quantity - closable
+        legs = _split_close_legs(
+            trader_gateway,
+            capability,
+            symbol,
+            side,
+            close_qty,
+            supported_effects,
+            payload_field,
+        )
+        legs.append(("open", open_qty))
+        return legs
+
+    if normalized_effect != "close":
+        return [(normalized_effect, quantity)]
+
+    return _split_close_legs(
+        trader_gateway,
+        capability,
+        symbol,
+        side,
+        quantity,
+        supported_effects,
+        payload_field,
+    )
+
+
 def build_live_order_client_ids(
     request_client_order_id: str, order_legs: list[tuple[str, float]]
 ) -> list[str]:
@@ -169,6 +248,7 @@ class BrokerOrderSubmitter:
         payload_field: Callable[[Any, str], Any],
         get_execution_capabilities: Callable[[], dict[str, Any]],
         record_order_request: Callable[[str, Any], None],
+        sync_group_mapping: Callable[[str, str], None] = lambda _c, _g: None,
     ) -> None:
         """Bind strategy injection hooks, id mapping and capability callbacks."""
         self._trader_gateway = trader_gateway
@@ -182,6 +262,7 @@ class BrokerOrderSubmitter:
         self._payload_field = payload_field
         self._get_execution_capabilities = get_execution_capabilities
         self._record_order_request = record_order_request
+        self._sync_group_mapping = sync_group_mapping
         self._warned_ignored_params: set[str] = set()
 
     def install(self) -> None:
@@ -213,8 +294,17 @@ class BrokerOrderSubmitter:
         trail_offset: float | None = None,
         trail_reference_price: float | None = None,
         broker_options: dict[str, Any] | None = None,
-    ) -> str:
-        """Submit a live broker order using the unified strategy-facing signature."""
+    ) -> OrderReceipt:
+        """Submit a live broker order using the unified strategy-facing signature.
+
+        Returns an `OrderReceipt`, not a single id string: a logical order can be
+        split into multiple legs (e.g. close_today/close_yesterday, or a reversal's
+        close+open legs), each with its own client/broker order id. `receipt.primary`
+        is the *first leg's* `broker_order_id` (the value production call sites use
+        as "the" order id); `str(receipt)` is the `group_id` (client order id) and is
+        a *different* id space in production brokers — do not use them
+        interchangeably.
+        """
         if not getattr(self._strategy, "broker_ready", True):
             raise RuntimeError(
                 "broker 尚未就绪，请在 broker_ready=True"
@@ -279,6 +369,7 @@ class BrokerOrderSubmitter:
             notify_strategy_error=self._notify_strategy_error,
         )
         broker_order_ids: list[str] = []
+        legs: list[OrderLeg] = []
         for leg_index, (leg_position_effect, leg_quantity) in enumerate(order_legs):
             request = UnifiedOrderRequest(
                 client_order_id=client_order_ids[leg_index],
@@ -300,4 +391,17 @@ class BrokerOrderSubmitter:
             self._bind_order_owner(
                 request.client_order_id, broker_order_id, owner_strategy_id
             )
-        return broker_order_ids[0]
+            self._sync_group_mapping(request.client_order_id, request_client_order_id)
+            legs.append(
+                OrderLeg(
+                    position_effect=leg_position_effect,
+                    quantity=leg_quantity,
+                    client_order_id=request.client_order_id,
+                    broker_order_id=broker_order_id,
+                )
+            )
+        return OrderReceipt(
+            group_id=request_client_order_id,
+            order_ids=tuple(broker_order_ids),
+            legs=tuple(legs),
+        )