Modul-19: Broker-Reconciliation

Status: FREIGEGEBEN (21.08.2026) · Container Modul-19-Broker-Reconciliation · Port 55019 (nur intern/expose)

Zweck

Modul-19 gleicht die interne Trading-Realität (M10 Trade-Journal, M18 Position-Manager) gegen die Broker-/Execution-Realität ab. Es erkennt Diskrepanzen (fehlende/überschüssige Positionen, Mengen-, Richtungs- oder Statusabweichungen) und erzeugt daraus Audit + Alarm, ohne selbst zu handeln.

Kritische Grenze: M19 ist ein reiner Reconciliation-/Monitoring-Dienst, KEIN Trade-Ausführer.

✅ M19 erzeugt NIE OPEN / INCREASE (keine automatische Reparatur, kein Ordering).
✅ M19 schreibt ausschließlich in eigene Audit-Tabellen (reconciliation_*), liest fremde Tabellen read-only.
❌ Keine KI/ML. Keine direkte Broker-Anbindung in V1.
FAIL-CLOSED: unklare/unerreichbare Broker-Realität → STALE/UNKNOWN/Alarm + Audit, nie blind handeln.
Keine Zombie-Konsumenten; Restart/Reconnect erzeugt keine Doppel-Events (idempotent).

V1-Grenze: „Brokerrealität“ = rekonstruiert aus M09 `execution_order`

⚠️ WICHTIG (V1-Akzeptanz): In V1 gibt es keinen echten Broker-Adapter. Die „Brokerrealität" wird rekonstruiert aus der von M09 persistierten Tabelle execution_order (PaperBroker hält sein Orderbuch nur In-Memory; die einzig nachweisbare Quelle ist die DB-Persistenz).

Das ist für V1 akzeptabel, aber NICHT gleichwertig mit echter Broker-Reconciliation. Echte Broker-Reconciliation (Abruf von Live-Positionen/Fills beim Broker/MT5) folgt nach M19 über einen Demo-Broker-Adapter (Plugin am BrokerStateProvider-Interface).

Architektur / Datenfluss

M09 Execution (execution_order, status SUBMITTED/PARTIALLY_FILLED/FILLED) ──┐  Broker-Realität (V1)
M10 Trade-Journal (trade_journal, status=OPEN) ─────────────────────────────┤  interne Realität
M18 Position-Manager (position_state, position_key=trade_id) ───────────────┘
        │
        ▼
Modul-19-Broker-Reconciliation (Port 55019, NUR intern)
   ├── BrokerStateProvider (Interface, V1=paper)  → Broker-Positionen (netto je Symbol)
   ├── InternalStateReader  → interne offene Positionen (Journal + M18 state)
   ├── ReconciliationEngine → Klassifikation je Symbol/Position
   ├── Storage  → reconciliation_run / reconciliation_result / reconciliation_event (idempotent)
   └── Publisher → RabbitMQ exchange "reconciliation" routing "reconciliation.alert" (additiv, M15 kann später konsumieren)

App-Struktur:

broker/base.py — BrokerStateProvider-Interface (V1=paper, später live/demo-Adapter)
broker/paper.py — V1-Paper-Provider: rekonstruiert Broker-Positionen aus execution_order (read-only)
broker/registry.py — Provider-Registry
core/internal_state.py — liest interne offene Positionen (M10 + M18)
core/engine.py — Reconciliation-Klassifikation (deterministisch)
core/service.py — Loop-Orchestrator, publiziert kritische Alarme, Trade-Actions hart deaktiviert
storage/storage.py — Persistenz (eigene Tabellen), Thread-Local-DB (psycopg2 nicht thread-safe)
publisher/publisher.py — Alarm-Publish auf RMQ (additive Schnittstelle)
api/main.py — REST-API (/health, /health/ready, /reconcile, /reconcile/runs, /reconcile/results), Port 55019 intern

Eigene Tabellen (migrations/001_reconciliation.sql):

reconciliation_run — Lauf (run_id PK, status RUNNING/COMPLETED/FAILED, totals)
reconciliation_result — Ergebnis je Position/Symbol (idempotent: UNIQUE(run_id, position_key))
reconciliation_event — append-only Alarm-/Audit-Events

Klassifikationen (deterministisch, V1)

Klassifikation	Bedingung	Konsequenz
`MATCH`	intern offen == Broker offen (Symbol, Richtung, Menge)	kein Event
`QUANTITY_MISMATCH`	Broker-Menge ≠ interne Menge	CRITICAL-Event
`DIRECTION_MISMATCH`	Broker-Richtung ≠ interne Richtung	CRITICAL-Event
`MISSING_BROKER`	intern offen, Broker hat Position	CRITICAL-Event
`MISSING_INTERNAL`	Broker offen, intern kein Datensatz	CRITICAL-Event
`STATUS_MISMATCH`	intern kennt Position, aber CLOSED/abweichend vs. Broker offen	CRITICAL-Event
`PARTIAL_FILL`	Broker PARTIALLY_FILLED → Menge berücksichtigt	(Konsistenz)
`STALE` / `UNKNOWN`	Broker-Realität unklar/unerreichbar	FAIL-CLOSED, kein Trade, Alarm + Audit

Hinweis (Design): MISSING_INTERNAL = Broker offen, intern hat gar keinen Datensatz. STATUS_MISMATCH = intern kennt die Position, aber sie ist CLOSED/abweichend während der Broker offen ist (vorher fälschlich MISSING_INTERNAL). Beides sind kritische Abweichungen, die als reconciliation.alert-CRITICAL gemeldet werden.

Safety (hart)

allow_trade_actions ist hart False (Konfiguration + API erzwingen; /reconcile lehnt ab wenn True).
M19 erzeugt niemals OPEN/INCREASE, keine automatische Reparatur, überschreibt Brokerrealität nie.
Bei UNKNOWN/STALE/UNREACHABLE → FAIL-CLOSED + Audit + Alarm, nie blind senden.
M19 ist reiner Publisher auf RMQ (kein Consumer → keine Zombie-Konsumenten).

Deployment

Port 55019 nur intern (expose, keine Host-Port-Bindings — wie M18).
Netz trading-modules_trading-modules, restart: unless-stopped.
RMQ-Host Modul-02-RabbitMQ, vhost trading. PG-Host Modul-01-PostgreSQL.
Reconciliation-Loop loop_interval_seconds=60, loop_enabled=True.

Tests

Unit: tests/test_engine.py — 11/11 grün (Klassifikation, Provider, Safety test_never_allows_trade).
E2E: tests/e2e_m19_full.py — 13/13 grün (MATCH, QUANTITY, DIRECTION, MISSING_BROKER/INTERNAL, PARTIAL_FILL, STATUS_MISMATCH, Duplikat/Idempotenz, parallel/race-safe, Health/Readiness, Event-Dedup, Audit-Trail).
Infrastruktur (live, VPS): Broker-DB unreachable → FAIL-CLOSED (broker_reachable:false, trade_actions_allowed:false); Restart sauber; RMQ-Down → kein Crash (gehaltene pika-Warnungen); RMQ-Reconnect ohne Zombies; M09-Ausfall → M19 arbeitet weiter (Quelle ist PG execution_order); Health+Readiness 200; Port nur intern.

Regression M03→M09→M18

Alle Kettenglieder healthy nach M19-Deployment (M03/M05/M08/M09/M10/M15/M18 /health = ok). M19 schreibt ausschließlich in reconciliation_*; fremde Tabellen (execution_order, trade_journal, position_state) bleiben unberührt. Keine M19-Konsumenten an der Trading-Kette; M19-Exchange reconciliation ist additiv (M15 kann künftig konsumieren). Keine Produktivpositionen — alle Datensätze sind M18E2E2/M19E2E2-Testreste.

Bugs / Lessons Learned

RMQ-vhost / vs trading: M18 nutzt vhost trading; M19 musste auf vhost trading korrigiert werden (anfänglich / → Fehler). Nach Fix sauber.
Envs-Präfix M19_: pydantic-settings env_prefix="M19_" — Envs wie M19_PG_HOST, M19_RABBITMQ_HOST verwenden, NICHT bare PG_HOST (Falle beim Isolationstest). Produktiv-Container trägt noch bare PG_*/ RABBITMQ_*-Envs (M18-Muster) = tote Envs; M19 greift auf korrekte pydantic-Defaults (Modul-01-PostgreSQL, Modul-02-RabbitMQ, vhost trading) zurück. Für saubere Konsistenz künftig Envs auf M19_-Präfix umstellen.
psycopg2 nicht thread-safe: Storage nutzt threading.local() pro Thread (Fix aus M18 übernommen).
MISSING_INTERNAL vs STATUS_MISMATCH: sauber getrennt (s. o.), sonst fälschliche Klassifikation.
Broker-Realität rekonstruiert: V1 akzeptiert execution_order als Broker-Realität; echter Adapter folgt nach M19 (Demo-Broker-Adapter), siehe oben.
Keine Host-Port-Bindings (nur expose) — wie M18, keine öffentliche API.

7.8 KiB Raw Blame History