实盘协议¶

trade-learn 2.0 的主能力是事件驱动回测；paper / live 的边界已经通过 tradelearn.core 预留。理解这页可以帮助你写不会被回测语义绑死的策略和 broker 适配器。

回测 broker 与实盘 broker 的区别¶

因此，为了加快回测而优化 RustBroker，不会自动改变实盘 broker；但策略层必须只依赖共同的“意图 + 事件”语义。

trade-learn 不公开 tradelearn.live 包。具体 QMT / IB / CTP 适配器应在私有扩展或部署目录中维护，用户策略只依赖 tradelearn.engine / tradelearn.lite 的公开策略 API。

实盘适配器应该接收中性订单请求，返回委托确认，并通过事件回流成交、撤单、拒单和状态。这里描述的是框架内部协议，不是用户策略应直接导入的公开 API；具体字段定义见 docs/internals/contracts.md。

类型	关键字段	用途
`OrderRequest`	`symbol`, `side`, `qty`, `order_type`, `limit_price`, `stop_price`, `tif`, `client_oid`	策略发出的 broker-neutral 下单请求
`OrderAck`	`client_oid`, `broker_oid`, `accepted_ts`	broker 接受请求后的确认
`Fill`	`broker_oid`, `symbol`, `qty`, `price`, `commission`, `ts`	成交事件
`PositionSnapshot`	`symbol`, `qty`, `avg_price`, `ts`	持仓快照
`AccountSnapshot`	`cash`, `equity`, `ts`	账户快照
`OrderStatusUpdate`	`broker_oid`, `status_str`, `ts`, `replay`	订单状态更新

这些类型只描述跨运行时共同语义，不携带 Backtrader bracket 字段，也不携带某个券商私有状态机。

实盘适配器应同时支持单笔 order_status(...) 和批量 order_statuses(...)。执行器需要等待委托反馈时，优先批量查询，减少 QMT / REST proxy 的请求次数和下单后确认延迟。

内部事件泵用来把外部 broker 的轮询结果标准化成框架事件。普通用户不需要直接使用它；私有适配器作者如需对接 broker 事件，应参考内部契约文档，而不是在策略代码里导入 tradelearn.core。

为了让同一套策略可以从回测迁移到 paper / live，建议遵守：

在 next() 里表达交易意图：buy、sell、close、order_target_percent、target_weights。
不假设立即成交，也不要假设发单后持仓立即变化。
通过 notify_order、notify_trade、Stats 或 broker 事件观察成交结果。
多资产目标权重策略应表达“目标组合”，不要在策略里手写 broker 状态同步。

QMT、IB、CTP、Binance 等适配器应作为独立扩展实现：

这样可以保持 tradelearn.backtest 的 Rust 性能优化和实盘 broker 的连接逻辑互不污染。