M26: FAILED-Branch + robuste E2E (20/20)

notes/trading/system-docs/modul-26-telegram-gateway.md

@@ -0,0 +1,113 @@
+# Modul-26-Telegram-Gateway
+
+**Status:** FREIGEGEBEN (2026-08-21)
+**Port:** 55026 (nur Docker-intern, kein öffentlicher Port)
+**Container:** `Modul-26-Telegram-Gateway`
+**Image:** `telegram-gateway:0.1.0`
+**Netzwerk:** `trading-modules`
+
+## Zweck
+
+Dünner, **tool-loser** Adapter zwischen Telegram und M17 Hermes-Agent. Ermöglicht die Bedienung von Hermes vom Handy über einen eigenen Telegram-Bot. **KEINE Trading-Tools**, kein M09/M07/M08/M15-Control-Zugriff. Safety bleibt deterministisch in M17.
+
+## Architektur
+
+```
+Telegram Bot API
+   │  Polling (getUpdates) — KEIN Webhook, kein öffentlicher Port
+   ▼
+Modul-26-Telegram-Gateway  (Port 55026 intern)
+   │  Auth-Allowlist, Rate-Limit, Audit — NUR HTTP-Calls an M17, KEINE Tools
+   ▼
+Modul-17-Hermes-Agent  (POST /tasks llm=true)
+   │  Tool-Whitelist + Task-Gates (deterministisch, UNVERÄNDERT)
+   ▼
+LLM (Cloud deepseek-v4-flash:cloud Standard / Local llama3.1:8b explizit)
+```
+
+## Sicherheitsmodell
+
+- **Allowlist:** Nur explizit erlaubte User-/Chat-IDs (`TELEGRAM_ALLOWED_IDS`, kommagetrennt). Unbekannte User werden **hart abgelehnt** (kein Task, Log-Eintrag, Status `REJECTED`/`UNAUTHORIZED`).
+- **Rate-Limit:** Sliding-Window pro User/Chat (Default 10/min). Überschreitung → `REJECTED`/`RATE_LIMITED`.
+- **Idempotenz:** `update_id` als PK in `telegram_message`. Bereits verarbeitete Updates werden übersprungen.
+- **Secrets:** Bot-Token NUR via ENV/Secret (`TELEGRAM_BOT_TOKEN`), nie im Code. Keine Secrets in DB/Logs/Doku.
+- **Prompt-Injection:** M17 behandelt externe Eingaben als untrusted data. Tool-Whitelist + Task-Gates hart im Code.
+- **Doppelte Barriere:** Gateway ist tool-los (nur HTTP-Calls an M17) + M17-Whitelist deterministisch.
+
+## Commands
+
+| Command | M17 task_type | Beschreibung |
+|---------|---------------|--------------|
+| `/status` | — | Hermes-Health (synchron) |
+| `/research` | research | Markt-/Regime-Analyse |
+| `/analytics` | analytics | Portfolio-/Strategie-Analyse |
+| `/backtest` | backtest | Backtest starten |
+| `/optimize` | optimization | Optimierung starten |
+| `/monitoring` | monitoring | Monitoring-Status |
+| `/tasks` | — | Letzte Tasks (synchron) |
+| `/help` | — | Hilfe |
+| Freitext | research | Wird als Research-Analyse behandelt |
+
+## Asynchrone Task-Abwicklung
+
+Lange Tasks (Cloud 5-23s, explizit lokale Analyse bis zu Minuten) laufen asynchron:
+1. Sofortige Bestätigung an denselben Chat ("⏳ *task* gestartet…").
+2. Task wird in Background-Thread an M17 gesendet (`POST /tasks` mit `llm=true`).
+3. Ergebnis wird später an denselben Chat zurückgesendet.
+
+### Ergebnis-/Fehlerbehandlung
+
+- **SUCCEEDED:** M26 sendet die finale Hermes-Analyse (`analysis`) + kompakte Tool-Liste. Tool-Fehler (z.B. 404/keine Marktdaten) **brechen den Flow nicht ab** — die finale Analyse mit Einschränkungen wird trotzdem verständlich an Telegram gesendet, einzelne Tools als `[FAILED]` gelistet.
+- **FAILED:** M26 sendet eine **klare Fehlermeldung** (`🔴 *task* fehlgeschlagen (Status: FAILED)` + Fehlercode + Details) — NICHT irreführend "✅ abgeschlossen".
+
+## Audit
+
+DB-Tabelle `telegram_message` (Migration `001_telegram_gateway.sql`):
+- `update_id` (PK), `chat_id`, `user_id`, `username`, `text`, `command`
+- `task_id`, `run_id`, `status`, `error_code`, `created_at`
+
+Nachvollziehbarkeit: **update_id → task_id → run_id → LLM-run → Tool-Calls** (via M17 hermes_llm_run + hermes_tool_call).
+
+## API (Port 55026 intern)
+
+- `GET /health` — Liveness
+- `GET /health/ready` — Readiness (Telegram-Token + Allowlist)
+- `GET /messages/recent` — Letzte Messages (Audit)
+- `GET /messages/{update_id}` — Einzelne Message
+- `POST /messages/test` — Test-Nachricht an konfigurierte Destination
+
+## Konfiguration (ENV)
+
+| Variable | Beschreibung |
+|----------|--------------|
+| `TELEGRAM_BOT_TOKEN` | Bot-Token (Secret, NUR ENV) |
+| `TELEGRAM_ALLOWED_IDS` | Kommagetrennte erlaubte User-/Chat-IDs |
+| `TELEGRAM_API_BASE` | Telegram API-Base (Default `https://api.telegram.org`; für E2E Fake-Server) |
+| `M17_BASE_URL` | M17 Hermes-Agent (Default `http://Modul-17-Hermes-Agent:55017`) |
+| `PG_HOST/PORT/USER/PASSWORD/DB` | PostgreSQL (Modul-01) |
+
+## E2E-Tests
+
+`tests/e2e_m26.py` (20/20 grün, 2026-08-21):
+1. Unknown user reject
+2. /status
+3. /research (+ Ergebnis)
+4. /analytics (+ Ergebnis)
+5. /backtest (+ Ergebnis)
+6. /optimize (+ Ergebnis)
+7. /monitoring (+ Ergebnis)
+8. /tasks
+9. /help
+10. Freitext → research (+ Ergebnis)
+11. Safety: place_order im Prompt → keine Order
+12. Rate-Limit
+13. Audit: update_id → task_id → run_id
+
+Test-Infrastruktur: `tests/fake_telegram.py` (Fake-Telegram Bot API Server mit Steuer-API für E2E).
+
+## Wichtige Hinweise
+
+- **M20 bleibt reserviert für Universe-Scheduler** — M26 ist separat.
+- **M14 NICHT verändern** — M26 nutzt nur das FAIL-SAFE-Muster als Vorlage, koppelt nicht an M14.
+- **M17 Safety-Gates unverändert** — M26 fügt nur einen dünnen Adapter hinzu.
+- **Kein öffentlicher Port** — nur `expose` im Compose.