README.md hinzugefügt (Setup + Architektur-Überblick)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-24 08:33:29 +02:00
parent 75d28827e8
commit 6318817ac1
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Oil Trading Bot (MT5, WTI)
+
+Algorithmischer **WTI-Öl-Trading-Bot** auf MetaTrader 5 mit headless FastAPI-Backend
+und Mobile-PWA. Analyse, Strategie, Backtests und LLM-Copilot laufen in Python; MQL5
+ist nur eine dünne Zeichen-Schicht fürs Desktop-Terminal.
+
+> **Hinweis:** Interne Doku, Antworten und UI-Texte sind auf Deutsch. Die
+> ausführliche Entwickler-/Strategie-Dokumentation steht in [`CLAUDE.md`](CLAUDE.md)
+> und [`docs/`](docs/).
+
+## Überblick
+
+- **`server.py` + `core/engine.py`** — headless FastAPI-Web-Backend, das die
+  **Mobile-PWA** in [`web/`](web/) bedient (Zugriff vom Handy z. B. via WireGuard).
+- **Eine** Oberfläche: die PWA. Das frühere Tkinter-Widget wurde entfernt.
+- ⚠ Immer nur **eine** Server-Instanz gegen dasselbe MT5-Terminal laufen lassen
+  (zwei TrailingManager = Konflikt).
+
+## Architektur (`core/`)
+
+| Modul | Aufgabe |
+|-------|---------|
+| `mt5data.py` | Preis / Trend / Konto |
+| `trader.py` | Orders + SL/TP |
+| `trailing.py` | Trailing / Teil-Exit / Time-Stop |
+| `wave_rec.py` | Empfehlung (EMA12/50-Trendfolge, Squeeze-Breakout, Gates) |
+| `elliott.py` | Elliott-Wellen / FVG |
+| `structure.py` | Marktstruktur (HH/HL/LH/LL, BOS, Regressionskanal — Anzeige) |
+| `daily_levels.py` | Tages-Prognose (Web-Recherche) |
+| `gaps.py` | D1-Kurslücken |
+| `candle_logger.py` | M1-Candle-Log → `candles_m1` |
+| `agent.py` | KI-Copilot (LLM) |
+| `history.py` | SQLite-Persistenz |
+| `config.py` | Konstanten + `oil_widget_config.ini`-Loader |
+| `engine.py` | headless Motor: fährt die Loops als Threads, liefert `snapshot()` |
+
+`engine._verdict()` aggregiert die Module zur **Gesamtempfehlung** (`verdict` im
+Snapshot) — Details: [`docs/gesamtempfehlung.md`](docs/gesamtempfehlung.md).
+
+## Voraussetzungen
+
+- **Windows** (das `MetaTrader5`-Python-Wheel ist Windows-only; das Backend läuft
+  neben dem MT5-Terminal).
+- **Python 3.12** mit `fastapi`, `uvicorn`, `MetaTrader5` (+ weitere Abhängigkeiten,
+  die die Module importieren).
+- Ein laufendes **MetaTrader-5-Terminal** mit dem WTI-Symbol des Brokers
+  (z. B. `SpotCrude` bei Pepperstone).
+
+## Einrichtung
+
+1. Repo klonen.
+2. Config-Vorlage kopieren und mit echten Keys füllen:
+   ```bash
+   cp oil_widget_config.ini.example oil_widget_config.ini
+   ```
+   Dann `oil_widget_config.ini` ausfüllen (LLM-/News-/Telegram-/Graph-Keys, WTI-Symbol,
+   Trading-Schalter). **Diese Datei enthält Live-Secrets und ist per `.gitignore`
+   vom Repo ausgeschlossen — niemals committen.** Erläuterungen zu allen
+   `[trading]`-Schaltern stehen als Kommentare in [`core/config.py`](core/config.py).
+3. MT5-Terminal starten und einloggen.
+
+## Starten
+
+```bash
+# Änderungen aktivieren / Server (neu) starten:
+restart_server.bat
+```
+
+Auto-Start ist als Windows-Aufgabe `OilTradingServer` (Login-Trigger, versteckt via
+VBS) eingerichtet. Die PWA ist danach unter `http://<host>:8000/` erreichbar.
+
+## Strategie in Kürze
+
+- **Richtung** = EMA12 vs. EMA50 (`wave_rec.py`), mit Totband, Anti-Überdehnung,
+  S/R- und Session-Konfidenz.
+- **Volatilitäts-Squeeze-Breakout** = additiver, backtest-validierter Auto-Entry
+  (Kompression → Ausbruch); optional autonom (`auto_squeeze`).
+- **Gates**: ATR-Breakout-Bestätigung, Entry-Raum, Mindest-Konfidenz, Higher-TF-
+  Gegen-Trend, EIA-Blackout.
+- **Exit**: SL-Band ~2×ATR, Breakeven ab +1,3×ATR, Trailing, Time-Stop, sowie ein
+  kalibriertes **P(Durchbruch)-Modell** für den S/R-Close am Gegenlevel.
+
+> **Methodik:** Strategie-Änderungen werden per **2-Stichproben-Backtest** (zwei
+> Zeiträume/Regime) mit **echten Kosten** belegt, bevor sie live gehen — „erst
+> messen, dann umbauen". Die zahlreichen `backtest_*.py`-Skripte dokumentieren
+> geprüfte und verworfene Ideen.
+
+## Nützliche Skripte
+
+| Befehl | Zweck |
+|--------|-------|
+| `python backtest_signal.py [TF] [N] [K]` | Empfehlungs-Edge messen (ereignisbasiert) |
+| `python analyze_execution.py` | Spread-/Slippage-/MAE-MFE-Kalibrierung |
+| `python weekly_review.py` | Wochenreport (Live-Stats vs. Backtest-Erwartung) |
+| `python -m py_compile <datei>` | Syntaxprüfung vor „fertig" |
+
+## Web-Assets
+
+Der Browser cacht hart: bei jeder JS/CSS-Änderung in `web/index.html` die
+Asset-Version `?v=N` **hochzählen**. Der Server sendet `Cache-Control: no-store`.
+
+## Datenhaltung
+
+- **`oil_widget_history.db`** (SQLite): `trades`, `recommendations`, `candles_m1` u. a.
+  Nicht im Repo (per `.gitignore`) — vor Eingriffen Backup (`*.bak-<datum>`).
+- Laufzeit-State (`emergency_state.json`, `runtime_state.json`, `report_state.json`)
+  wird vom Server erzeugt und ist ebenfalls nicht versioniert.
+
+## Lizenz
+
+Privates Projekt — keine Lizenz vergeben.