Brokerage-Anpassungsschicht und Integration

Dieses Kapitel richtet sich an Benutzer und Entwickler, die sich auf die Anbindung an ein neues Brokerhaus (oder zukünftig an QMT) vorbereiten: Wie sieht die Schicht „Unified Counter Interface“ über dem simulierten Brokerhaus aus und wie kann sie erweitert werden?

Hinweis für Leser: Wenn Sie noch keine Erfahrung mit simuliertem Handel haben, brauchen Sie nur die Abschnitte :doc:2-Konfiguration-und-Ausführung und :doc:3-Risiko-und-Auftragslebenszyklus zu lesen; dieses Kapitel kann vorerst übersprungen werden. Kehren Sie zu diesem Kapitel zurück, wenn Sie eine Verbindung zu einer realen Handelsplattform oder einem Broker herstellen möchten.

Liebe Nutzer, in qteasy ist der Broker für die Auftragsannahme, die Benachrichtigung über die Annahme und die asynchrone Ausführung zuständig. Der Standard-Simulator verwendet Live-Kurse, um all dies zu simulieren. Wir haben eine einheitliche Anpassungsschicht entwickelt, sodass beim zukünftigen Wechsel zu realen Handelsplattformen wie QMT die Hauptlogik des Traders möglichst wenig angepasst werden muss.

0. 适用场景

  • Sie möchten sich in das neue Brokerhaus integrieren und gleichzeitig die Kompatibilität mit der bestehenden Trader-Logik beibehalten.

  • Sie müssen zunächst den minimalen geschlossenen Kreislauf von „Einreichung → Annahmeergebnis → Transaktionsantwort → Statusaktualisierung“ einrichten.

1. 核心概念：分层结构

Typischer Ablauf eines Live-Anrufs (von extern nach intern):

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

BrokerFacade (Adaptive Shell): Wie eine einheitliche Übersetzungsschicht für verschiedene Brokerage-Zähler – Händler müssen der Facade nur „connect / submit / poll_fills“ sagen, ohne sich darum kümmern zu müssen, ob die zugrunde liegende Schicht analog oder QMT ist.

Wichtigste Punkte:

  • Facade bietet externe Verbindungen wie connect, disconnect, submit with ack, poll fills und get remote.

  • In der CLI spiegelt broker status|connect|disconnect den Status is_connected wider (im Simulator bedeutet dies „die Adapterschicht ist bereit“, nicht eine echte Broker-Anmeldung).

  • Die Hauptschleife des Händlers verbraucht die Handelsbelohnungen über poll_fills, anstatt direkt auf die interne Warteschlange zuzugreifen.

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

Die Broker-Anpassungsschicht dient als einheitliche Schnittstelle zwischen Trader und bestimmten Brokern (Simulatoren, zukünftigen QMTs usw.). Unabhängig von der zugrunde liegenden Schicht verwendet Trader denselben Prozess: „Verbinden → Auftrag aufgeben → Annahme abwarten → Ausführung abfragen → ggf. Remote-Ledger prüfen.“ Die folgende Tabelle bietet einen Vergleich der Schnittstellennamen und ihrer täglichen Nutzung als praktische Referenz beim Lesen der Vergleichstabelle und der Integrationsliste weiter unten.

Bedeutung der einzelnen Spalten: Schnittstelle ist der Name der Methode der Anpassungsschicht; Was zu tun ist ist die Verantwortung in der Live-Verbindung; Sie können es sich als eine Metapher vorstellen, die Ihnen beim Merken hilft.

Anwendung: Bei der Integration eines neuen Brokers arbeiten Sie alle Punkte der Checkliste in §6 ab; für den täglichen Betrieb und die Wartung müssen Sie sich nur auf connect, submit_with_ack, poll_fills und den CLI-Befehl broker status konzentrieren.

Schnittstelle

Was ist zu tun

Man kann es so verstehen:

verbinden / trennen

Aufbau/Trennung der Adapterschichtsitzung

Öffnen/Schließen des Thekenfensters

is_connected

Haben Sie eine Verbindung hergestellt?

Ist das Fenster geöffnet?

submit_with_ack

Senden Sie die Bestellung ab und erhalten Sie gleichzeitig eine Bestätigung über die Annahme oder Ablehnung.

Achten Sie unmittelbar nach dem Absenden der Bestellung auf die Meldung „Annehmen/Ablehnen“.

abbrechen

Stornierung

Nicht ausgeführte Aufträge stornieren

poll_fills

Empfangen Sie asynchrones Transaktionsfeedback

Fragen Sie: „Gibt es neue Transaktionen?“

get_remote_*

Bargeld/Positionen/Bestellungen aus der Ferne einsehen

Die Konten werden mit den Hauptbüchern der Brokerfirmen abgeglichen (die Simulatoren dienen größtenteils als Platzhalter).

2.1 Vergleich der Schnittstellenverantwortlichkeiten

Die Benutzeroberfläche verhält sich im Simulator und im echten QMT unterschiedlich: Im Simulator werden Live-Kurse für die Simulation verwendet, während im echten QMT eine Verbindung zum Frontend hergestellt wird. Die folgende Tabelle hilft Ihnen, die Erwartungen zu klären – so vermeiden Sie, die Verbindung im Simulator mit einem echten Login zu verwechseln, und erleichtern die Planung zusätzlicher Funktionen bei der Integration mit QMT.

Bedeutung der einzelnen Spalten: Schnittstelle entspricht §2; Semantik ist die abstrakte Verantwortung; Im Simulator sehen Sie ist das aktuelle Standardverhalten der Simulation; Reales QMT (geplant) ist ein zukünftiges Ziel (in der aktuellen Version noch keine Verpflichtung).

Anwendungshinweise: Prüfen Sie bei der Fehlersuche zunächst, ob die Spalte „Simulator“ die Kriterien „Abnahme + Bericht“ erfüllt; wählen Sie bei der Planung des QMT die Zielfunktionen in der letzten Spalte aus.

Schnittstelle

Semantik

Im Simulator werden Sie sehen

Real QMT (in Planung)

verbinden / trennen

Gespräch

Internes Flag gesetzt; kein gültiger Login.

Echte Anmeldung und Wiederverbindung

submit_with_ack

Gleichzeitige Verarbeitung

Retouren werden akzeptiert, simuliert broker_order_id usw.

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

poll_fills

Asynchrone Belohnungen

Simulierte Transaktionswarteschlange

Echtzeit-Transaktions-Push/Polling

get_remote_*

Remote-Ledger

Normalerweise leer oder keine Angabe

Datenquelle für Abgleich, Zugriffskontrolle und Synchronisierung

abbrechen

Stornierung

Simulationsimplementierung

Zuordnung realer Stornierungsnummern

Es wird empfohlen, die Priorität anhand des „kleinsten geschlossenen Regelkreises“ zu bestimmen:

  1. Verbindung: connect / is_connected

  2. Transaktion: submit_with_ack / cancel

  3. Belohnung: poll_fills

  4. Abfrage: get_remote_* (Hat erst nach der Verbindung mit einem realen Zähler volle geschäftliche Bedeutung)

3. submit_with_ack 与本地订单

Im Gegensatz zur Ablehnung von Risikokontrollaufträgen: Risikokontrollaufträge haben Priorität und werden nicht in die Auftragsliste aufgenommen (siehe :doc:3-risk-and-order-lifecycle).

submit_with_ack gibt synchron zurück, ob das Brokerhaus den Auftrag angenommen hat. Die folgende Tabelle beschreibt lediglich die Zuordnung zwischen lokalen Aufträgen und broker_order_id während der Annahmephase; Informationen zum Transaktionsfortschritt finden Sie in der Statustabelle in :doc:3-risk-and-order-lifecycle.

Bedeutung der einzelnen Spalten: Akzeptiertes Ergebnis: Dies entspricht der akzeptierten Semantik in ACK; Lokaler Auftrag: Dies gibt den Status der Auftragstabelle an; broker_order_id: Dies gibt an, ob die Brokerauftragsnummer zurückgeschrieben wurde.

Anwendung:: Wenn eine Order abgelehnt wird und die Brokernummer leer ist, prüfen Sie die Zeile mit „accepted=False“; wenn eine Brokernummer vorhanden ist, die Transaktion aber seit längerer Zeit nicht abgeschlossen wurde, prüfen Sie die Statustabelle und poll_fills.

Akzeptanzergebnisse

Lokale Anordnungen

Broker-Auftrags-ID

accepted=True

Weiter verbreiten

Bitte zurückschreiben: Maklerfirmennummer und -name

accepted=False

Oft abgelehnt

Leer halten

Einen detaillierten Vergleich finden Sie unter :doc:6-trader-snapshot-gate.

Vor der Übermittlung werden die Auftragsstruktur und die Prämienfelder vertraglich geprüft. Bei Formatfehlern wird umgehend eine Fehlermeldung ausgegeben, um zu vermeiden, dass fehlerhafte Daten in die Buchhaltung gelangen.

4. 扩展新 Broker 类型

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

Fabrik registrieren (Beispiel):

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 (Alias pull-state): Derzeit reserviert, die Ausführung gibt [NOT_IMPLEMENTED] ... aus, was darauf hinweist, dass der eigentliche „Pull-State vom Broker“ noch nicht implementiert ist; er wird nach der Integration mit QMT durch eine verfügbare Implementierung ersetzt.

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

  • Das Absenden oder Abfragen ohne Verbindungsaufbau sollte zu einer expliziten Fehlermeldung führen, nicht zu einem stillen Fehlschlagen.

  • cancel Unbekannte Delegationsnummer: Sollte immer „Abgebrochen“ zurückgeben.

  • poll_fills-Timeout: Es sollte eine leere Liste zurückgegeben werden, keine geänderten Daten.

  • Im Simulator stellt **connect keine echte Brokerage-Sitzung dar; es zeigt lediglich an, dass die Anpassungsschicht damit umgehen kann.

6. 最小接入清单

  1. Implementieren Sie connect / disconnect / is_connected

  2. Verbinde submit_with_ack mit poll_fills

  3. Das Rückgabefeld erfüllt die Vertragsvalidierung.

  4. Implementieren Sie cancel- und Ausnahmepfade.

  5. (Falls Zugriffskontrolle/Abgleich/Synchronisierung erforderlich ist) Implementieren Sie get_remote_*

  6. Überprüfen Sie in der CLI Folgendes: broker status, reconcile und Order Mapping.

7. 最小验收标准

  • is_connected=True nach connect, kann submit_with_ack verwendet werden.

  • Erfolgreich verarbeitet: Lokaler Auftrag enthält broker_order_id

  • Auftragsablehnung: rejected und das Broker-Feld ist leer.

  • Die Rückgabewerte von poll_fills sind überprüfbar.

  • Keine Verbindung / Unbekannte Reihenfolge / Timeout-Verhalten ist stabil

  • CLI broker / reconcile Observable

8. 相关跳转

  • Lebenszyklus- und Risikokontrolle: 3-Risiko- und Auftragslebenszyklus

  • Produkte und Fehlerbehebung: :doc:5-artifacts-and-troubleshooting

  • Snapshot/Zugriffskontrolle: :doc:6-trader-snapshot-gate

  • CLI-Referenz: :doc:8-cli-trader-capability-matrix

  • Designbeschreibung: design/10-live-trading-s1.3-architecture.md