仲介アダプテーション層と統合

この章は、新しい証券会社 (将来は QMT) に接続する準備をしているユーザーと開発者を対象としています。シミュレートされた証券会社の上にある「統一カウンター インターフェイス」レイヤーはどのようなもので、どのように拡張できるのでしょうか?

読者メモ: シミュレーション取引が初めての場合は、セクション:doc:2-configuration-and-run と :doc:3-risk-and-order-lifecycle を読むだけで済みます。この章は今のところスキップしても構いません。実際の取引プラットフォームまたはカスタム ブローカーに接続する必要がある場合は、この章に戻ってください。

ユーザーの皆様、qteasy では、ブローカー は「注文の受け取り → 注文を受け入れるかどうかの通知 → 非同期で実行をプッシュする」責任を負います。デフォルトのシミュレーターは、ライブ価格を使用してこれらすべてをシミュレートします。将来的にQMTなどの実際の取引プラットフォームに切り替える際に、Traderのメインロジックをできるだけ変更する必要がないように、統合されたアダプテーションレイヤーを設計しました。

0. 适用场景

  • 既存の Trader ロジックとの互換性を維持しながら、新しい証券会社と統合したいと考えています。

  • まずは「申請→受理結果→取引応答→ステータス更新」という最小限の閉ループを確立する必要があります。

1. 核心概念：分层结构

一般的なライブ コール チェーン (外部から内部へ):

Operator.run_live_trade()
  → Trader（日程、风控、账本）
       → BrokerFacade（券商适配外壳：统一 API）
            → SimulatorBroker / 您注册的 Broker

BrokerFacade (アダプティブ シェル): さまざまな証券カウンター用の 統合変換レイヤー のようなものです。トレーダーは、基礎となるレイヤーがアナログであるか QMT であるかを気にする必要がなく、ファサードに「接続 / 送信 / ポールフィル」と言うだけで済みます。

重要なポイント:

  • Facade は、接続、切断、ACK 付き送信、ポーリング入力、リモート取得などの外部接続を提供します。

  • CLI では、broker status|connect|disconnect は is_connected を反映します (シミュレーターでは、これは「アダプター層の準備ができている」ことを意味し、実際の仲介ログインではありません**)。

  • Trader メインループは、内部キューに直接アクセスするのではなく、poll_fills を介して取引報酬を消費します。

2. 核心接口（用户/开发者向）

ブローカー アダプテーション レイヤー は、Trader と特定の仲介業者 (シミュレーター、将来の QMT など) の間の統合インターフェイスとして機能します。基礎となる層に関係なく、Trader は同じプロセスを使用します。「接続 → 注文の送信 → 承認のリッスン → 実行のポーリング → 必要に応じてリモート台帳を確認する」。以下の表は、以下の比較表と統合リストを読むときに簡単に参照できるように、インターフェイス名と日常的な使用方法の比較を示しています。

各列の意味: インターフェイス はアダプテーション層メソッドの名前です。 何をすべきかはライブリンクの責任です。 これは、覚えておくための比喩として考えることができます。

使用方法: 新しい仲介会社を統合する場合、§6 のチェックリストの各項目を実装します。日常の運用とメンテナンスでは、connect、submit_with_ack、poll_fills、および CLI broker status のみに注目する必要があります。

インタフェース

何をする

次のように理解できます

connect / disconnect

アダプテーション層セッションの確立/切断

カウンター窓開閉

is_connected

接続しましたか？

窓は開いていますか？

submit_with_ack

注文を送信すると同時に、受諾または拒否の確認を受け取ります。

注文を送信した直後に、「承諾/拒否」を聞いてください。

cancel

キャンセル

未約定注文をキャンセルする

poll_fills

非同期トランザクションのフィードバックを受け取る

「新しい取引はありますか?」と尋ねます。

get_remote_*

リモートの現金/ポジション/注文を表示する

口座を証券会社の台帳と照合します (シミュレーターはほとんどがプレースホルダーです)。

2.1 インターフェースの責任の比較

同じインターフェイスでも シミュレーター と 実際の QMT では動作が異なります。前者はシミュレーションにライブ価格設定を使用し、後者はフロントエンドに接続します。以下の表は、期待値を確立するのに役立ちます。シミュレーター上の connect を実際のログインと間違えるのを防ぎ、QMT と統合する際の追加機能の計画も容易にします。

各列の意味: インターフェイス は §2 と同じです。 セマンティクス は抽象的な責任です。 シミュレータでは、 が現在のデフォルトのシミュレーション動作であることがわかります。 本当の QMT (計画) は将来の目標です (現在のバージョンでの約束ではありません)。

使用方法: トラブルシューティングを行うときは、まずシミュレーターの列が「承認 + 報告」基準を満たしているかどうかを確認します。 QMT を計画する場合は、最後の列でターゲット機能を選択します。

インタフェース

セマンティクス

シミュレーターで見ることができます

リアルQMT（​​計画中）

connect / disconnect

セッション

内部フラグセット。本物のログインではありません。

実際のログインと再接続

submit_with_ack

同時処理

返品は受け入れられ、broker_order_id などをシミュレートします。

柜台真实受理结果（见 :doc:4a-xtquant-broker-adapter-contract-v1）

poll_fills

非同期報酬

シミュレートされたトランザクション キュー

実際のトランザクションのプッシュ/ポーリング

get_remote_*

リモート台帳

通常は空かなし

調整、アクセス制御、同期のためのデータソース

cancel

キャンセル

シミュレーションの実装

実際のキャンセル数のマッピング

「最小の閉ループ」に基づいて優先度を理解することをお勧めします。

  1. 接続: connect / is_connected

  2. トランザクション: submit_with_ack / cancel

  3. 報酬: poll_fills

  4. クエリ: get_remote_* (実際のカウンターに接続された後にのみ完全なビジネス上の意味を持ちます)

3. submit_with_ack 与本地订单

リスク管理の注文拒否とは異なります: リスク管理が優先され、注文リストには含まれません (:doc:3-risk-and-order-lifecycle を参照)。

submit_with_ack は、証券会社が注文を承諾したかどうかを同期的に返します。以下の表は、受け入れ段階におけるローカル注文と broker_order_id との対応のみを説明しています。トランザクションの進行状況については、:doc:3-risk-and-order-lifecycle のステータス表を参照してください。

各列の意味: 受け入れられた結果: これは、ACK で受け入れられたセマンティクスに対応します。 ローカル注文: これは注文テーブルのステータスを示します。 broker_order_id: これは、仲介注文番号が書き戻されたかどうかを示します。

使用方法:: 注文が拒否され、ブローカー番号が空の場合は、「accepted=False」の行を確認します。ブローカー番号があるにもかかわらず、取引が長期間完了していない場合は、ステータス テーブルと poll_fills を確認してください。

合格結果

現地でのご注文

broker_order_id

accepted=True

循環し続ける

再書き込み 証券会社の番号と名前

accepted=False

多くの場合、rejected

空にしておいてください

詳細な比較については、:doc:6-trader-snapshot-gate を参照してください。

送信前に、注文構造と報酬フィールドが契約に基づいて検証されます。形式が正しくない場合は、「台帳にダーティなデータが入力される」ことを避けるために、できるだけ早くエラーが報告されます。

4. 扩展新 Broker 类型

XtQuant / MiniQMT：配置项 live_trade_broker_type='xtquant' 已在 2.5.2 白名单中；实现细节与禁止双重下单等规则见英文契约 :doc:4a-xtquant-broker-adapter-contract-v1（协作方 PR 评审基准）。

工場を登録する(例):

from qteasy.broker import register_broker_factory

register_broker_factory('my_broker', MyBrokerFactory)
# qt.configure(live_trade_broker_type='my_broker')

独立扩展包（推荐用于 QMT）：

import qteasy_xtquant

qteasy_xtquant.register()
# qt.configure(live_trade_broker_type='xtquant')

CLI sync (エイリアス pull-state): 現在予約、実行すると [NOT_IMPLEMENTED] ... が出力され、実際の「仲介からのプル状態」がまだ実装されていないことが示されます。 QMT との統合後に、利用可能な実装に置き換えられます。

5. 边界行为（接入时请注意）

  • 接続せずに送信またはポーリングを行うと、サイレントエラーではなく、明示的なエラーが発生するはずです。

  • cancel 不明な委任番号: 常に「Cancelled」を返す必要があります。

  • poll_fills タイムアウト: ダーティ データではなく、空のリストが返される必要があります。

  • シミュレータでは、**connect は実際の仲介セッションを表しません。アダプテーション層がそれを処理できることを示すだけです。

6. 最小接入清单

  1. connect / disconnect / is_connected を実装します

  2. submit_with_ack を poll_fills に接続します

  3. 戻りフィールドは契約の検証を満たしています。

  4. cancel と例外パスを実装する

  5. (アクセス制御/調整/同期が必要な場合) get_remote_* を実装します

  6. CLI で以下を確認します: broker status、reconcile、および順序マッピング。

7. 最小验收标准

  • connect の後の is_connected=True は、submit_with_ack になる可能性があります

  • 正常に処理されました: ローカル注文には broker_order_id が含まれています

  • 注文拒否: rejected、ブローカーフィールドは空です。

  • poll_fills の返品は検証可能です。

  • 接続されていない / 順序が不明 / タイムアウト動作は安定しています

  • CLI broker / reconcile 監視可能

8. 相关跳转

  • ライフサイクルとリスク管理: 3 つのリスクと順序のライフサイクル

  • 製品とトラブルシューティング: :doc:5-artifacts-and-troubleshooting

  • スナップショット/アクセス制御: :doc:6-trader-snapshot-gate

  • CLI リファレンス: :doc:8-cli-trader-capability-matrix

  • 設計の説明: design/10-live-trading-s1.3-architecture.md