From df3cd3fc5758000323f1c7b5fd557c71d112a0f8 Mon Sep 17 00:00:00 2001 From: Rain Ocampo Date: Fri, 21 Aug 2026 06:48:27 +0000 Subject: [PATCH] M09/M19: IG-Demo-Adapter + CLOSE-Pfad-Fix + Fake-MATCH-Fix (21.08.2026) M09 (modul-09-execution-service.md): - IG-Demo-Adapter (IG_DEMO-Modus) dokumentiert - Order-Aktions-Auswertung: OPEN/INCREASE->create_position, CLOSE/REDUCE->close_position - CLOSE-Direction korrekt umkehren (_close_direction: LONG->SELL, SHORT->BUY) - broker_order_id/dealId sauber durchreichen - unbekannte/ungueltige Aktionen FAIL-CLOSED (IG_UNSUPPORTED_ACTION) - 6 IG-Adapter-Tests dokumentiert - erster erfolgreicher IG-DEMO OPEN->CLOSE-E2E (US500) M19 (modul-19-broker-reconciliation.md): - Fake-MATCH Root Cause dokumentiert - korrigierte interne Positionswahrheit: position_state (M18) primaer - trade_journal/execution_order allein vortaeuschen keine interne offene Position - qty=0 nie MATCH - Tests: Unit 16/16, E2E 14/14 (S13 Fake-MATCH->MISSING_INTERNAL) --- modul-09-execution-service.md | 64 +++++++++++++++++++++++++++++-- modul-19-broker-reconciliation.md | 38 ++++++++++++++++-- 2 files changed, 95 insertions(+), 7 deletions(-) diff --git a/modul-09-execution-service.md b/modul-09-execution-service.md index c27a0fc..66a0686 100644 --- a/modul-09-execution-service.md +++ b/modul-09-execution-service.md @@ -45,10 +45,65 @@ RabbitMQPublisher (market.execution) `submit_order()`, `get_order_status()` - `PaperBrokerAdapter` (app/broker/paper.py): V1, simuliert realistischen Lifecycle (SUBMITTED → FILLED, Partial Fill, Reject, Timeout) für Tests +- `IgDemoAdapter` (app/broker/ig_demo.py): IG-Markets-Demo-Broker (IG_DEMO-Modus), + echter externer Broker-Adapter. Liest/schreibt über IG REST API (demo-api.ig.com). - `BrokerRegistry` (app/broker/registry.py): wählt Adapter anhand `DEFAULT_BROKER` (V1: paper). Echte Broker-Adapter später austauschbar, keine Brokerlogik im Core-Code. +## IG-Demo-Adapter (IG_DEMO-Modus, 21.08.2026) + +**Status: FREIGEGEBEN / PRODUKTIV VERIFIZIERT** — erster echter externer Broker-Adapter. + +- **Eigener Modus `IG_DEMO`** (nicht LIVE+Gate); PAPER/IG_DEMO/LIVE strikt getrennt. +- **Demo-Basis-URL erzwungen** (`demo-api.ig.com`), LIVE-Endpunkt (`api.ig.com`) + technisch blockiert, kein IG_DEMO→LIVE-Autowechsel. +- **Credentials ausschließlich VPS-Secret/ENV** (`.env.ig`, chmod 600/root-only); + nie in Code/Forgejo/Tolaria/DB/Logs. +- **Mengen instrumentabhängig** über `broker_mapping` (PostgreSQL); kein globales 1:1. +- **Epic-Mapping produktiv in PostgreSQL `broker_mapping`**; Forgejo nur Schema/Doku/Beispiele. + +### Order-Aktions-Auswertung (CLOSE-Pfad-Fix, 21.08.2026) +`BrokerOrderRequest` trägt `action_type` (Default `OPEN`) + `broker_order_id`. +Der Service reicht beides durch; der Adapter wertet `action_type` aus: + +| action_type | IG-Pfad | +|-------------|---------| +| `OPEN` / `INCREASE` | `POST /positions/otc` (create_position) | +| `CLOSE` / `REDUCE` | `POST /positions/otc` mit `_method:DELETE` (close_position) | +| unbekannt/ungültig | **FAIL-CLOSED** (`IG_UNSUPPORTED_ACTION`) | + +**CLOSE-Direction korrekt umkehren:** CLOSE einer LONG/BUY-Position muss mit +**SELL** erfolgen (Gegenseite), nicht mit der Positionsrichtung. `_close_direction()`: +LONG→SELL, SHORT→BUY. + +**broker_order_id/dealId sauber durchreichen:** `broker_order_id` wird vom Service +in die Order übernommen und an den Adapter durchgereicht; IG `dealId` wird als +`broker_order_id` persistiert. + +**Unbekannte/ungültige Aktionen FAIL-CLOSED:** `_derive_action_type()` setzt +unbekannte Aktionen NICHT mehr auf OPEN zurück, sondern reicht sie durch → +Control blockt mit `UNKNOWN_ACTION_TYPE`, Adapter mit `IG_UNSUPPORTED_ACTION`. + +### IG-Adapter-Tests (6/6 grün) +1. `test_unsupported_action_fail_closed` — unbekannte Aktion → FAIL-CLOSED +2. `test_close_direction_inverted` — CLOSE einer BUY-Position → SELL +3. `test_open_uses_create_position` — OPEN → create_position +4. `test_close_uses_close_position` — CLOSE → close_position mit `_method:DELETE` +5. `test_broker_order_id_passthrough` — broker_order_id/dealId durchgereicht +6. `test_fail_closed_without_credentials` — ohne Credentials → nicht konfiguriert + +### Erster erfolgreicher IG-DEMO OPEN→CLOSE-E2E (21.08.2026) +- **OPEN** `IGE2E-US500-OPEN-1787292734` → dealId `DIAAAAYB46KMNAE`, size 1.0, BUY, + openLevel 7652.58 → **FILLED** +- **CLOSE-Bug gefunden + gefixt:** erster CLOSE sendete fälschlich als zweite OPEN + (action_type ignoriert) + falsche direction (BUY statt SELL) +- **CLOSE2** `IGE2E-US500-CLOSE2-1787293768` für `DIAAAAYB463S4AB` → **FILLED** + (filled_quantity 1, avg_fill_price 7652.19) +- **IG GET /positions: Anzahl 0** — alle Positionen geschlossen +- **Safety-Reset:** M09 zurück auf PAPER (`EXECUTION_MODE=PAPER`, + `TRADING_ENABLED=false`, `DEFAULT_BROKER=paper`) + ## Idempotenz - Unique-Index `uq_execution_order_src` auf `source_portfolio_decision_id` @@ -84,10 +139,11 @@ sowie `REJECTED`, `CANCELLED`, `FAILED`. ## Tests -- **21/21 Unit-Tests** (test_execution.py): gültige Order → PAPER FILLED, - Idempotenz, ungültige Quantity → REJECTED, Kill-Switch, fehlende - Broker-Credentials → FAIL-CLOSED, Broker-Reject, Timeout → keine blinde - Doppelorder, Partial Fill, Reconnect-Backoff, parallele identische Events +- **31/31 Unit-Tests** (test_execution.py + test_ig_demo.py + test_control.py): + gültige Order → PAPER FILLED, Idempotenz, ungültige Quantity → REJECTED, + Kill-Switch, fehlende Broker-Credentials → FAIL-CLOSED, Broker-Reject, + Timeout → keine blinde Doppelorder, Partial Fill, Reconnect-Backoff, + parallele identische Events, Control-Gate (M15), IG-Adapter (6/6) - **E2E 6/6 Checks** (Kette 03→04→05→06→07→08→09): Execution-Order in DB, exakt 1 Paper-Order, Pflichtfelder, Idempotenz, ORDER_SUBMITTED+ORDER_FILLED, gültiger Trade → PAPER FILLED diff --git a/modul-19-broker-reconciliation.md b/modul-19-broker-reconciliation.md index ff69f1d..5af7c07 100644 --- a/modul-19-broker-reconciliation.md +++ b/modul-19-broker-reconciliation.md @@ -70,6 +70,32 @@ Modul-19-Broker-Reconciliation (Port 55019, NUR intern) 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. +## Interne Positionswahrheit (Kernregel, 21.08.2026) +> ⚠️ **Kernregel (User, 21.08.2026):** Eine externe Broker-Position darf nur `MATCH` sein, wenn eine +> **echte interne OPEN-Position** existiert. **Interne Positionswahrheit = `position_state` (M18).** +> `trade_journal`/`execution_order` allein dürfen **KEINE** interne offene Position vortäuschen. + +**Vorher (Bug):** `get_internal_open()` las `trade_journal` (M10) als Basis. Ein `trade_journal`-Eintrag mit +`status='OPEN'` galt als intern offen, auch **ohne** `position_state` (M18). Folge: IG-Position existierte, +intern nur `execution_order`/`trade_journal` → M19 klassifizierte fälschlich `MATCH` mit qty 0 (**Fake-MATCH**). + +**Nachher (Fix):** `get_internal_open()` liest **primär `position_state` (M18)** als Treiber. Ein +`trade_journal`-Eintrag **ohne** `position_state` zählt **nicht** als intern offen → Broker-Position wird +`MISSING_INTERNAL` statt Fake-MATCH. CLOSED `position_state`-Einträge werden mitgeliefert, damit die Engine +`STATUS_MISMATCH` erkennen kann. + +**Erwartete Klassifikation (Kernregel):** +| Situation | Klassifikation | +|-----------|----------------| +| IG OPEN + kein `position_state` | `MISSING_INTERNAL` | +| IG OPEN + `position_state` OPEN + gleiche qty/direction | `MATCH` | +| IG OPEN + `position_state` CLOSED | `STATUS_MISMATCH` | +| IG OPEN + andere qty | `QUANTITY_MISMATCH` | +| IG OPEN + andere direction | `DIRECTION_MISMATCH` | +| Intern OPEN + IG flat | `MISSING_BROKER` | + +**Wichtig:** `qty=0` darf **niemals** zu `MATCH` führen (Engine: `internal_open` erfordert `qty>0`). + ## 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. @@ -83,10 +109,11 @@ MISSING_INTERNAL). Beides sind kritische Abweichungen, die als `reconciliation.a - 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, +- **Unit:** `tests/test_engine.py` — 16/16 grün (Klassifikation, Provider, Safety `test_never_allows_trade`, + Kernregel `qty=0` nie MATCH, journal-ohne-position_state → MISSING_INTERNAL). +- **E2E:** `tests/e2e_m19_full.py` — 14/14 grün (MATCH, QUANTITY, DIRECTION, MISSING_BROKER/INTERNAL, PARTIAL_FILL, STATUS_MISMATCH, Duplikat/Idempotenz, parallel/race-safe, Health/Readiness, Event-Dedup, - Audit-Trail). + Audit-Trail, **S13 Fake-MATCH → MISSING_INTERNAL**). - **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. @@ -110,3 +137,8 @@ ist additiv (M15 kann künftig konsumieren). Keine Produktivpositionen — alle 5. **Broker-Realität rekonstruiert:** V1 akzeptiert `execution_order` als Broker-Realität; echter Adapter folgt nach M19 (Demo-Broker-Adapter), siehe oben. 6. **Keine Host-Port-Bindings** (nur `expose`) — wie M18, keine öffentliche API. +7. **Fake-MATCH (Root Cause, 21.08.2026):** `get_internal_open()` las `trade_journal` (M10) als Basis. Ein + `trade_journal`-Eintrag mit `status='OPEN'` galt als intern offen, auch **ohne** `position_state` (M18). + Folge: IG-Position existierte, intern nur `execution_order`/`trade_journal` → M19 klassifizierte fälschlich + `MATCH` mit qty 0. **Fix:** Interne Positionswahrheit primär aus `position_state` (M18); `trade_journal`/ + `execution_order` allein vortäuschen keine interne offene Position → `MISSING_INTERNAL`. `qty=0` nie MATCH.