Capa de adaptación e integración de corretaje

Este capítulo está dirigido a usuarios y desarrolladores que se están preparando para conectarse a una nueva firma de corretaje (o QMT en el futuro): ¿Cómo se ve la capa «Interfaz de contador unificada» sobre la firma de corretaje simulada y cómo se puede expandir?

Nota del lector: Si es nuevo en el comercio simulado, solo necesita leer las secciones :doc:2-configuration-and-run y :doc:3-risk-and-order-lifecycle; Este capítulo puede saltarse por ahora. Vuelva a este capítulo cuando necesite conectarse a una plataforma comercial real o a un corredor personalizado.

Estimados usuarios, en qteasy, el Broker es responsable de «aceptar órdenes → informarles si las acepta → impulsar asincrónicamente la ejecución». El simulador predeterminado utiliza precios en vivo para simular todo esto; Hemos diseñado una capa de adaptación unificada para que, al cambiar a plataformas comerciales reales como QMT en el futuro, no sea necesario cambiar la lógica principal de Trader tanto como sea posible.

0. 适用场景

Quiere integrarse con la nueva firma de corretaje manteniendo la compatibilidad con la lógica Trader existente.
Primero debe establecer el ciclo cerrado mínimo de «Envío → Resultado de aceptación → Respuesta de transacción → Actualización de estado».

1. 核心概念：分层结构

Cadena típica de llamadas en vivo (de afuera hacia adentro):

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

BrokerFacade (Adaptive Shell): Como una capa de traducción unificada para diferentes contadores de corretaje. Los comerciantes solo necesitan decir «conectar/enviar/pol_fills» a Facade, sin necesidad de preocuparse si la capa subyacente es analógica o QMT.

Puntos clave:

Facade proporciona conexiones externas como conectar, desconectar, enviar con confirmación, completar encuestas y obtener acceso de forma remota.
En la CLI, broker status|connect|disconnect refleja is_connected (en el simulador, esto significa «la capa del adaptador está lista», no un inicio de sesión de intermediación real).
El bucle principal Trader consume recompensas comerciales a través de poll_fills, en lugar de acceder directamente a la cola interna.

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

La Capa de adaptación del corredor sirve como interfaz unificada entre Trader y corredores específicos (simuladores y futuro QMT, etc.). Independientemente de la capa subyacente, Trader utiliza el mismo proceso: «Conectar → Enviar orden → Escuchar aceptación → Sondear para ejecución → Verificar el libro mayor remoto si es necesario». La siguiente tabla proporciona una comparación de nombres de interfaces y uso diario para una fácil referencia al leer la tabla de comparación y la lista de integración a continuación.

Significado de cada columna: Interfaz es el nombre del método de la capa de adaptación; Qué hacer es responsabilidad del enlace en vivo; Puedes considerarlo como una metáfora que te ayudará a recordar.

Cómo utilizar: Al integrar una nueva correduría, implemente cada elemento de la lista de verificación del §6; para las operaciones y el mantenimiento diarios, solo necesita concentrarse en connect, submit_with_ack, poll_fills y la CLI broker status.

Interfaz	Hacer lo	Puedes entenderlo como
`connect` / `disconnect`	Establecer/desconectar sesión de capa de adaptación	Apertura/cierre de ventana del mostrador
`is_connected`	¿Te has conectado?	¿Está la ventana abierta?
`submit_with_ack`	Envíe el pedido y simultáneamente reciba la confirmación de aceptación o rechazo.	Escuche «Aceptar/Rechazar» inmediatamente después de enviar el pedido.
`cancel`	Cancelar	Cancelar órdenes no ejecutadas
`poll_fills`	Reciba comentarios sobre transacciones asincrónicas	Pregunte «¿Alguna transacción nueva?»
`get_remote_*`	Ver efectivo/posiciones/pedidos remotos	Conciliar cuentas con los libros de contabilidad de las casas de bolsa (los simuladores son en su mayoría marcadores de posición).

2.1 Comparación de responsabilidades de interfaz

La misma interfaz se comporta de manera diferente en el simulador y en el QMT real: el primero utiliza precios en vivo para la simulación, mientras que el segundo se conecta al front-end. La siguiente tabla le ayuda a establecer expectativas, evitando confundir el connect en el simulador con un inicio de sesión real y también facilitando la planificación de capacidades adicionales al integrarse con QMT.

El significado de cada columna: Interfaz es el mismo que el §2; Semántica es la responsabilidad abstracta; En el simulador verá es el comportamiento de simulación predeterminado actual; Real QMT (planificado) es un objetivo futuro (no un compromiso en la versión actual).

Cómo utilizar: Al solucionar problemas, primero verifique si la columna del simulador cumple con los criterios de «aceptación + informe»; Al planificar QMT, seleccione las capacidades objetivo en la última columna.

Interfaz	Semántica	En el simulador verás	QMT real (en planificación)
`connect` / `disconnect`	la sesión	Conjunto de bandera interna; no es un inicio de sesión genuino.	Inicio de sesión y reconexión reales
`submit_with_ack`	Procesamiento simultáneo	Se aceptan devoluciones, simula broker_order_id, etc.	柜台真实受理结果（见 :doc:`4a-xtquant-broker-adapter-contract-v1`）
`poll_fills`	Recompensas asincrónicas	Cola de transacciones simulada	Push/encuesta de transacciones reales
`get_remote_*`	Libro mayor remoto	Generalmente vacío o Ninguno	Fuente de datos para conciliación, control de acceso y sincronización
`cancel`	Cancelar	Implementación de simulación	Mapeo del número de cancelación real

Se recomienda comprender la prioridad en función del «bucle cerrado más pequeño»:

Conexión: connect / is_connected
Transacción: submit_with_ack / cancel
Recompensa: ⟦CÓDIGO0⟧
Consulta: get_remote_* (Solo tiene significado comercial completo después de conectarse a un contador real)

3. submit_with_ack 与本地订单

A diferencia del rechazo de órdenes de control de riesgos: el control de riesgos tiene prioridad y no está incluido en la lista de órdenes (ver :doc:3-risk-and-order-lifecycle).

submit_with_ack devuelve sincrónicamente si la firma de corretaje ha aceptado la orden. La siguiente tabla solo describe la correspondencia entre los pedidos locales y el ⟦CÓDIGO1⟧ durante la etapa de aceptación; para conocer el progreso de la transacción, consulte la tabla de estado en :doc:3-risk-and-order-lifecycle.

Significado de cada columna: Resultado aceptado: Esto corresponde a la semántica aceptada en ACK; Pedido local: Indica el estado de la tabla de pedidos; broker_order_id: Esto indica si el número de orden de corretaje se ha reescrito.

Cómo utilizar:: Si se rechaza una orden y el número de corredor está vacío, verifique la fila con «aceptado=Falso»; si hay un número de corredor pero la transacción no se ha completado durante mucho tiempo, verifique la tabla de estado y poll_fills.

Resultados de aceptación	Pedidos locales	broker_order_id
`accepted=True`	seguir circulando	Reescribir número y nombre de la firma de corretaje
`accepted=False`	A menudo `rejected`	Mantener vacío

Para una comparación detallada, consulte :doc:6-trader-snapshot-gate.

Antes del envío, la estructura del pedido y los campos de recompensa se validan según el contrato. Si el formato es incorrecto, se informará un error lo antes posible para evitar que «ingresen datos sucios al libro mayor».

4. 扩展新 Broker 类型

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

Registrar una fábrica (ejemplo):

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): Actualmente reservado, la ejecución imprimirá [NOT_IMPLEMENTED] ..., lo que indica que el «estado de extracción de corretaje» real aún no se ha implementado; será reemplazado por una implementación disponible después de la integración con QMT.

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

Enviar o sondear sin conectarse debería resultar en un error explícito, no en una falla silenciosa.
cancel Número de delegación desconocido: debería devolver constantemente «Cancelado».
poll_fills tiempo de espera: se debe devolver una lista vacía, no datos sucios.
En el simulador, **connect no representa una sesión de corretaje real; solo indica que la capa de adaptación puede manejarlo.

6. 最小接入清单

Implementar connect / disconnect / is_connected
Conecte submit_with_ack a poll_fills
El campo de devolución satisface la validación del contrato.
Implementar cancel y rutas de excepción
(Si se requiere control de acceso/reconciliación/sincronización) Implementar get_remote_*
Verifique lo siguiente en la CLI: broker status, reconcile y asignación de pedidos.

7. 最小验收标准

is_connected=True después de connect, puede ser submit_with_ack
Procesado correctamente: el pedido local contiene broker_order_id
Rechazo de orden: rejected y el campo del corredor está vacío.
Las devoluciones poll_fills son verificables.
No conectado/Orden desconocido/El comportamiento del tiempo de espera es estable
CLI broker / reconcile observable

8. 相关跳转

Ciclo de vida y control de riesgos: ciclo de vida de 3 riesgos y pedidos
Productos y solución de problemas: :doc:5-artifacts-and-troubleshooting
Instantánea/Control de acceso: :doc:6-trader-snapshot-gate
Referencia CLI: :doc:8-cli-trader-capability-matrix
Descripción del diseño: design/10-live-trading-s1.3-architecture.md