# Modul-18: Position-Manager

**Status: FREIGEGEBEN (21.08.2026)** · Container `Modul-18-Position-Manager` · Port `55018` (nur intern/expose)

## Zweck
Modul-18 verwaltet **bereits offene Positionen** deterministisch: Es beobachtet offene Trades und gibt auf Basis fester
Exit-Regeln (Stop-Loss, Take-Profit, Break-even, Trailing, Time-Exit) gezielte **Exit-Aktionen** an Modul-09.

**Kritische Grenze:** M18 ist ein **reiner Exit-/Positions-Manager**, KEIN Signal-/Einstiegsmodul.
- ✅ M18 darf NUR `REDUCE` / `CLOSE` / `CANCEL` an M09 geben. **NIE `OPEN` / `INCREASE`.**
- ❌ Kein eigenmächtiges Nachkaufen/Pyramiding. Keine KI/ML. Keine direkte Broker-Anbindung.
- Jede Order-Aktion läuft ausschließlich über **M09 Execution** via RabbitMQ `trade.approved`.
- **FAIL-CLOSED:** stale/unbekannter Zustand → nie blind senden; Restart/Reconnect erzeugt keine Doppelaktion; keine Zombies.

## Architektur / Datenfluss
```
Modul-03-Market-Data (Preise) ──┐
                                ▼
Modul-10-Trade-Journal (OPEN) ──► Modul-18-Position-Manager (Port 55018, NUR intern)
Modul-15 (Trading-State, readonly)     │
                                ├── Engine-Loop (deterministische Exit-Regeln)
                                ├── Publisher  → RabbitMQ market.portfolio / trade.approved  → M09
                                └── Consumer   ← RabbitMQ market.execution / order.filled    (Reconciliation)
                                       │
                                       ▼
                                 Modul-09-Execution-Service (PaperBroker: broker=paper) → order.filled
```

**App-Struktur (`app/`):**
- `core/engine.py` — Exit-Regel-Engine (Regel-Priorität deterministisch)
- `core/orchestrator.py` — Hydrate-State, wendet Regeln an, idempotent
- `publisher/publisher.py` — publiziert Aktionen an M09 (`trade.approved`, je Aktion eine eindeutige `action_id`)
- `consumer/consumer.py` — konsumiert M09-Execution-Events (`order.filled` etc.) für Reconciliation
- `pricing/client.py` — liest Preise von M03, inkl. **Stale-Guard**
- `providers/journal.py` — Quelle offener Positionen (Trade-Journal, `status=OPEN`)
- `storage/storage.py` — Persistenz (`position_state`/`position_action`/`position_event`)
- `api/main.py` — REST-API (`/health`, `/readiness`), Port 55018 nur intern

**Eigene Tabellen (`migrations/001_position.sql`):**
- `position_state` — aktueller verwalteter Zustand je Position
- `position_action` — jede an M09 gegebene Order-Aktion (REDUCE/CLOSE/CANCEL)
- `position_event` — append-only Audit-Event-Historie

## Exit-Regeln (deterministisch)
| Regel | Trigger | Aktion |
|-------|---------|--------|
| Stop-Loss | Preis ≤ stop_loss | CLOSE |
| Take-Profit | Preis ≥ target | CLOSE |
| Break-even | Preis günstig, SL auf Entry gesetzt | CLOSE bei BE-SL |
| Trailing | Preis weiter günstig (best_price_seen) | CLOSE bei Trailing-SL |
| Time-Exit | max. Haltedauer erreicht | CLOSE |
| Partial-Fill / Duplikat | idempotente Aktion | exakt 1 Order, keine Doppelaktion |
| HALTED (M15) | Trading-State HALTED | CLOSE weiterhin erlaubt (Exit) |
| stale Preis | Kerze älter als `stale_price_max_age_seconds` (3600s) | **FAIL-CLOSED: keine Aktion** |

Regeln laufen mit fester Priorität; jede Exit-Aktion wird als eindeutige `position_action` (action_id) persistiert.

## M09-CLOSE-Pfad (Reduktion → Execution)
```
M18 position_action (action_id, CLOSE) 
   → Publisher → RabbitMQ exchange "market.portfolio" routing "trade.approved"
   → M09 Execution (control/client bypass für REDUCE/CLOSE/CANCEL) → PaperBroker (broker=paper)
   → execution_order (source_portfolio_decision_id = M18 action_id, status FILLED)
   → RabbitMQ "market.execution" routing "order.filled"
   → M18-Consumer → Reconciliation (position_state → CLOSED, qty=0, Audit-Event)
```
**Verifikation:** Für jede Exit-Aktion existiert **exakt 1** execution_order mit `broker=paper`, `status=FILLED`,
`source_portfolio_decision_id` = M18 `action_id`. M09 speichert die M18-`action_id` als
`source_portfolio_decision_id` (top-level + Payload). Keine Doppelaktionen je action_id (HAVING count>1 = 0).

## Reconciliation über order.filled
M18 konsumiert M09-Execution-Events (`order.filled`, `order.partially_filled`, `order.rejected`, `order.failed`)
und gleicht den eigenen `position_state` ab: FILLED → Position als `CLOSED` markieren, `quantity=0`, Audit-Event
`ORDER_EXECUTED`/`ORDER_FILLED`. Damit sind M10 (Journal) und M18 (Manager) konsistent, auch wenn M10 CLOSE
nicht automatisch verknüpft.

## Thread-Local-DB-Fix (Root Cause „connection pointer is NULL")
**Symptom:** Reconciliation scheiterte sporadisch mit `connection pointer is NULL`.
**Root Cause:** `PositionStorage._conn` war eine **geteilte Singleton-Verbindung** zwischen Engine-Loop-Thread und
ExecutionConsumer-Thread. psycopg2 ist **nicht thread-safe**: ein Thread schloss die Verbindung
(`resolve_position_key`/`has_pending_exit`), der andere Thread lief auf totem Cursor.
**Fix:** **Thread-Local-Verbindung** — `self._tl = threading.local()`; jeder Thread erhält eine eigene
psycopg2-Verbindung; kein Cross-Thread-`.close()`. `close()`/`rollback()` (ensure_schema) auf lokale Verbindung umgestellt.
**Verifikation:** Unit-Tests **13/13 grün**, E2E **47/47 PASS**.

## Testdesign-Lessons (E2E)
1. **action_id statt Journal-pd_id:** M09 speichert die M18-`action_id` als `source_portfolio_decision_id` —
   Verifikation muss `wait_execution_for_action(action_id)` nutzen, nicht Journal-`pd_id`.
2. **Audit-Eventname:** Consumer schreibt `ORDER_EXECUTED` (bzw. `ORDER_FILLED`); Test akzeptiert beide.
3. **Szenario 10 RA/RB:** Verifikation über `action_id`, nicht `pd_id`.
4. **Stale-Szenario:** `stale_price_max_age_seconds=3600`; eine 5-min-Kerze ist NICHT stale. M03 akzeptiert
   bis 30 Tage alte Kerzen, persistiert injiziertes `ts` aber nicht (vergibt frisches ts). Fix: 2h-alte Kerze
   (>1h < 30Tage) injizieren + **pro-Lauf eindeutiges Symbol** (M03-Speicher hat keinen Delete-Endpoint).

## Safety (User-Vorgabe, kritisch)
- **NUR REDUCE/CLOSE/CANCEL** — niemals OPEN/INCREASE. Kein Nachkaufen/Pyramiding.
- Idempotent + race-safe + **FAIL-CLOSED**. Restart/Reconnect keine Doppelaktion. Keine Zombies.
- Broker/Execution unklar → nie blind erneut senden.
- Vollständiger Audit-Trail (`position_event` append-only).
- Port 55018 nur Docker-intern (`expose`), kein öffentliches Mapping. Netz `trading-modules`.
- Keine Secrets in Logs/API/DB.

## Tests & E2E-Verifikation (VPS, 21.08.2026)
- **Unit-Tests** `tests/test_engine.py`: **13/13 grün** (Thread-Local-Fix).
- **E2E** `tests/e2e_m18_full2.py`: **47/47 PASS** (EXIT=0), deterministischer Lauf 0–15:
  HOLD · SL→CLOSE · TP→CLOSE · Break-even · Trailing · Time-Exit · Partial-Fill · bereits CLOSED · Duplikat ·
  parallel/race-safe (RA/RB) · M09 down · M15 HALTED · **stale Preis (FAIL-CLOSED)** · Restart · Reconciliation order.filled.
- Für jede Exit-Aktion: exakt 1 Execution je action_id, `broker=paper`, `status=FILLED`, keine Doppelaktionen,
  keine offenen Zombie-Testpositionen.
- **Regression M03→M09:** M18 erzeugt **NIE OPEN/INCREASE** (nur CLOSE). M09 execution_order:
  nur `CLOSE`, alle `FILLED`, `broker=paper`, keine Doppel-Order je action_id.
- **Health/Security:** `/health` + `/readiness` 200; Port 55018 nur intern; keine Secrets in
  Logs/API/DB; keine Tracebacks seit finalem Lauf; Consumer/RMQ-Reconnect sauber.

## Compose / Betrieb
- Netzwerk `trading-modules`, DB-Host `Modul-01-PostgreSQL` (Modul-01), RabbitMQ `Modul-02-RabbitMQ`.
- Port 55018 nur `expose` (Docker-intern), kein Host-Mapping. `restart: unless-stopped`.
- Keine Secrets im Compose-Env.

---
## Geändert
```
Geändert von: Rain Ocampo
Datum: 21.08.2026
Grund: Modul-18-Position-Manager formal abgeschlossen + FREIGEGEBEN. E2E 47/47 PASS, Regression M03→M09 gruen
       (nur CLOSE, nie OPEN/INCREASE), Health/Security gruen (Port 55018 intern, keine Secrets/Tracebacks).
       Thread-Local-DB-Fix (psycopg2 "connection pointer is NULL" geteiltes Singleton → Thread-Local). Doku angelegt.
```