Dokumentation Trading-System: README, Modul-03, Ports, Infrastruktur (Rain Ocampo, 20.08.2026)

2026-08-20 02:59:17 +00:00 · 2026-08-20 02:59:17 +00:00 · a7820e30cf
commit a7820e30cf
parent b43837044c
4 changed files with 274 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,61 @@
-# trading-system-docs
+# Trading-System — Modulare Architektur

-Dokumentation des modularen Trading-Systems (17 Module, Modul-01..17)
+Zentrales, modulares automatisiertes Trading-System, betrieben auf einem Hostinger-VPS (`187.124.31.123`).
+
+**Repository-Inhalt:** Live-Dokumentation der Infrastruktur, der Module und des aktuellen Betriebszustands.
+Jede Änderung folgt dem **Notation-Format**: Autor (`Alice` / `Rain Ocampo`) + Zeitstempel (`DD.MM.YYYY HH:MM`) + Grund.
+
+---
+
+## Architektur-Überblick
+
+- **17 Module** (`Modul-01-PostgreSQL` … `Modul-17-Hermes-Agent`), orchestriert über `docker-compose.yml` unter `/opt/trading-modules/`.
+- **Netzwerk:** `trading-modules` (bridge). Kommunikation ausschließlich über **Docker-interne Service-Hostnamen** (keine festen IPs).
+- **Feste Host-Ports:** Modul-01=`55432`, Modul-02=`55672`+`15672`, Modul-03–17=`55003`–`55017`.
+- **Zugangsdaten:** nur über Environment Variables / Docker-Secrets (Defaults in Compose mit `${VAR:-default}`).
+- **Kernprinzip:** bestehende Container/Volumes/Daten nie löschen, keine unnötigen öffentlichen Ports öffnen, Ist-Zustand vor Änderung prüfen.
+
+### Multi-Agent-Setup (Resident-Evil-Theme)
+| Agent | Rolle | Port |
+|-------|-------|------|
+| **Alice** (OpenClaw) | Primary | 55163 |
+| **Matt Addison** (OpenClaw) | Backup | 54524 |
+| **Rain Ocampo** (Hermes) | Technischer Support | 32776 (UI) |
+
+---
+
+## Module
+
+| Modul | Name | Status | Port |
+|-------|------|--------|------|
+| 01 | PostgreSQL | ✅ healthy (postgres:16-alpine) | 55432 |
+| 02 | RabbitMQ | ✅ healthy (rabbitmq:3-management) | 55672 / 15672 |
+| 03 | Market-Data | ✅ healthy (market-data:0.1.0) | 55003 (intern) |
+| 04 | Market-Regime | ⬜ Platzhalter (alpine) | 55004 |
+| 05–17 | … | ⬜ Platzhalter (alpine) | 55005–55017 |
+
+Details: siehe `modul-03-market-data.md` (vollständig implementiert), weitere Module folgen.
+
+---
+
+## Notation / Audit-Trail
+
+Jede Änderung wird mit folgender Zeile dokumentiert:
+
+```
+Geändert von: [Alice | Rain Ocampo]
+Datum: DD.MM.YYYY HH:MM
+Grund: <Kurzbeschreibung>
+```
+
+- **Alice** = Änderungen durch OpenClaw
+- **Rain Ocampo** = Änderungen durch Hermes
+
+---
+
+## Geändert
+```
+Geändert von: Rain Ocampo
+Datum: 20.08.2026
+Grund: Initiale Repository-Struktur und Modul-03-Dokumentation angelegt.
+```
--- a/infrastructure-handbook.md
+++ b/infrastructure-handbook.md
@ -0,0 +1,51 @@
+# Infrastruktur & Betriebs-Handbuch — Trading-System VPS
+
+> Stand: 20.08.2026 · VPS: `187.124.31.123`
+
+## Multi-Agent-Architektur (Resident-Evil-Theme)
+| Agent | Plattform | Rolle | Port |
+|-------|-----------|-------|------|
+| **Alice** | OpenClaw (primary) | Hauptagent, Protagonistin | 55163 |
+| **Matt Addison** | OpenClaw (backup) | Backup/Support | 54524 |
+| **Rain Ocampo** | Hermes (support) | Technischer Support | 32776 (UI) |
+
+Notation in Notion/Forgejo bei JEDER Änderung:
+```
+Geändert von: [Alice | Rain Ocampo]
+Datum: DD.MM.YYYY HH:MM
+Grund: …
+```
+
+## Container-Verwaltung (via SSH)
+```bash
+ssh root@187.124.31.123
+docker compose -f /opt/trading-modules/docker-compose.yml ps
+docker compose -f /opt/trading-modules/docker-compose.yml up -d <service>
+docker compose -f /opt/trading-modules/docker-compose.yml build <service>
+docker compose -f /opt/trading-modules/docker-compose.yml down   # nur bei explizitem Wunsch
+```
+
+## Trading-Module (17 Container)
+- Compose: `/opt/trading-modules/docker-compose.yml`
+- Container-Namen exakt: `Modul-01-PostgreSQL` … `Modul-17-Hermes-Agent`
+- Netzwerk: `trading-modules`
+- Modul-01 = PostgreSQL 16-alpine (Host 55432)
+- Modul-02 = RabbitMQ 3-management (Host 55672/15672, vhost `trading`)
+- Modul-03 = Market-Data (FastAPI, Port 55003 intern, **nicht öffentlich**)
+- Modul-04–17 = alpine-Platzhalter (bis ausgebaut)
+
+## Wichtige Hinweise
+- **Coolify überschreibt Container-Configs bei Neustart.** Config-Änderungen an OpenClaw ausschließlich über Config-Dateien (nicht UI).
+- **Hot-Reload** OpenClaw: `kill -HUP 1` im Container.
+- **Ollama** braucht `OLLAMA_API_KEY`; interner Hostname `ollama-nb6d-ollama-1:11434`.
+- VPS-Authentifizierung: **nur Public-Key-Auth**.
+
+## Deleted Resources (VPS-Aufräumung 20.08.2026)
+Folgendes wurde entfernt (~25 GB freigegeben): Chronos/Kronos (kronos-api, chronos-service, chronos-tradelog), trading-bridge, llm-trade-manager, deepseek-bot, MetaTrader-5, t212-pilot, mehrere redundante Hermes-Container/Volumes/Netzwerke. **Bleibt:** n8n, forgejo, paperclip, Tolaria, PostgreSQL, RabbitMQ, Ollama, Traefik, Coolify-Suite.
+
+---
+```
+Geändert von: Rain Ocampo
+Datum: 20.08.2026
+Grund: Infrastruktur-Handbuch für das Trading-System dokumentiert.
+```
--- a/modul-03-market-data.md
+++ b/modul-03-market-data.md
@ -0,0 +1,116 @@
+# Modul-03-Market-Data — Betriebsdokumentation
+
+> Erstellt: 20.08.2026 (Rain Ocampo) · Status: ✅ In Betrieb (healthy)
+
+## Zweck
+Zentrale Marktdatenquelle des Trading-Systems. Pipeline:
+`Marktdaten → Validierung → Normalisierung → PostgreSQL → RabbitMQ-Event`
+Keine Strategie, keine Orders, keine KI — nur zuverlässige Marktdaten.
+
+## Container
+| Attribut | Wert |
+|----------|------|
+| Name | `Modul-03-Market-Data` |
+| Image | `market-data:0.1.0` (lokal gebaut) |
+| Port | **55003** — **NUR intern** (`expose`, nicht öffentlich) |
+| Netzwerk | `trading-modules` (bridge) |
+| Build-Context | `/opt/trading-modules/modul03-market-data/` |
+| Restart | `unless-stopped` |
+| Healthcheck | ✅ `healthy` |
+
+## Deployment
+```bash
+cd /opt/trading-modules
+docker compose build modul-03-market-data
+docker compose up -d modul-03-market-data
+```
+
+## Environment Variables (Compose)
+| Variable | Wert (Default) | Zweck |
+|----------|---------------|-------|
+| `PG_HOST` | `Modul-01-PostgreSQL` | Docker-interner Servicename |
+| `PG_PORT` | `5432` | intern (Host: 55432) |
+| `PG_USER/PASSWORD/DB` | `trading` | aus `.env`-Defaults |
+| `RABBITMQ_HOST` | `Modul-02-RabbitMQ` | Docker-interner Servicename |
+| `RABBITMQ_PORT` | `5672` | intern (Host: 55672) |
+| `RABBITMQ_USER/PASSWORD/VHOST` | `trading` | **vhost `trading`** |
+| `DATA_PROVIDER` | `noop` | `noop` / `demo` / später Broker |
+| `LOG_LEVEL` | `INFO` | Strukturiertes Logging |
+
+Keine festen IPs — nur Docker-interne Hostnamen. Creds via Compose env + `${VAR:-default}`.
+
+## Datenbank (Modul-01-PostgreSQL)
+Tabelle `public.ohlcv`:
+```sql
+symbol TEXT, asset_class TEXT, provider TEXT, timeframe TEXT,
+ts TIMESTAMPTZ, open/high/low/close DOUBLE PRECISION, volume DOUBLE PRECISION,
+created_at TIMESTAMPTZ DEFAULT now(), id BIGSERIAL PRIMARY KEY
+```
+
+### Finale Constraints & Indizes (Stand 20.08.2026)
+| Index | Typ |
+|-------|-----|
+| `uq_ohlcv_provider_symbol_tf_ts` | **UNIQUE** `(provider, symbol, timeframe, ts)` |
+| `ohlcv_pkey` | UNIQUE `(id)` |
+| `idx_ohlcv_symbol_tf` | `(symbol, timeframe)` |
+| `idx_ohlcv_symbol_tf_ts` | `(symbol, timeframe, ts DESC)` |
+| `idx_ohlcv_provider_symbol_tf_ts` | `(provider, symbol, timeframe, ts DESC)` |
+
+Der Unique-Index inkludiert den **Provider** — langfristig werden mehrere Provider/Broker unterstützt
+(gleiche Symbol+Timeframe+Timestamp können von verschiedenen Quellen kommen).
+
+**Migrationen:** `/app/migrations/001_ohlcv.sql` + `002_unique_provider.sql`
+(idempotent, löschen nichts; automatisch via `ensure_schema()`/glob angewendet).
+
+## RabbitMQ (Modul-02)
+- **Exchange:** `market.data` (topic, durable)
+- **vhost:** `trading` (wichtig!)
+- **Routing-Keys:**
+
+| Routing-Key | Event-Typ | Wann |
+|-------------|-----------|------|
+| `market.data.ready` | `MARKET_DATA_READY` | **Batch/Import** — EIN Event pro Batch, `candle_count` + `batch:true` |
+| `market.data.candle.closed` | `MARKET_CANDLE_CLOSED` | **Live** — pro abgeschlossener Kerze EIN Event, OHLCV im payload |
+
+- Eventschema v1.0: `event_id, event_type, event_version, timestamp, symbol, asset_class, timeframe, provider` + payload.
+
+## Interne API
+| Endpoint | Zweck |
+|----------|-------|
+| `GET /health` | Liveness (200 immer) + Komponentenstatus im Body |
+| `GET /health/ready` | Readiness (503 wenn PG/RabbitMQ down) |
+| `POST /ingest` | Kerzen einspeisen (JSON: `{"candles":[...]}`) |
+| `GET /prices/{symbol}` | Letzte Kurse |
+| `GET /history/{symbol}?timeframe=` | Historische OHLCV |
+
+## Provider-Adapter
+`app/providers/providers.py`:
+- `DataProvider` (ABC) — abstrakte Schnittstelle `fetch_ohlcv()`, `health()`
+- `NoopProvider` — keine Datenquelle konfiguriert (Default)
+- `DemoProvider` — synthetische OHLCV-Daten für Tests
+- Neue Broker = neue Klasse, umschalten via `DATA_PROVIDER` env → keine harte Anbieter-Kopplung
+
+## Validierung (`app/validation/validator.py`)
+- Timestamp gültig (UTC, nicht Zukunft, nicht zu alt/stale)
+- OHLC-Werte > 0
+- High ≥ Low, High ≥ Open/Close, Low ≤ Open/Close
+- Duplikat-Erkennung (Storage + DB-Unique-Index)
+
+## End-to-End-Test (20.08.2026, nach Provider-Constraint-Upgrade) ✅
+- **Batch-Pfad:** 4 GOOG-Kerzen → saved:4, **GENAU EIN** `MARKET_DATA_READY` (routing `market.data.ready`, candle_count:4). 3 NVDA → saved:3, EIN Event.
+- **Live-Pfad:** 1 AMZN-Candle → `MARKET_CANDLE_CLOSED` (routing `market.data.candle.closed`, OHLCV im payload).
+- **Provider-Duplikat:** identische NVDA-Kerze erneut → `duplicate`, kein Insert, kein Event.
+- **Port-Sicherheit:** 55003 von außen (`http://187.124.31.123:55003/health`) → **nicht erreichbar** ✅
+- Datenbestand final: AAPL 5, GOOG 4, NVDA 3, EURUSD 3, TSLA 4, MSFT 1, AMZN 1.
+
+## Offene Punkte
+- Echter Broker-/Datenprovider-Adapter (Interface bereit, noop/demo Defaults)
+- Zusätzliche Daten (Bid/Ask/Spread, Ticks, Fundamentaldaten) — vorbereitet
+- Consumer für `market.data.ready` / `market.data.candle.closed` (Modul-04 ff.)
+
+---
+```
+Geändert von: Rain Ocampo
+Datum: 20.08.2026
+Grund: Modul-03-Dokumentation angelegt (Provider-Constraint, Event-Trennung, Port-Nicht-Exposition).
+```
--- a/ports-reference.md
+++ b/ports-reference.md
@ -0,0 +1,47 @@
+# Ports & Service-Referenz — Trading-System VPS
+
+> Stand: 20.08.2026 · VPS: `187.124.31.123` · SSH: Public-Key-Auth (nur)
+
+## Netzwerk & Core-Infrastruktur
+- **Netzwerk:** `trading-modules` (bridge) — Kommunikation über Docker-interne Service-Hostnamen, keine festen IPs.
+- **Host:** Hostinger-VPS, 300 GB Disk, ~31 GiB RAM.
+
+## Feste Port-Zuordnung (Schema `55NNN` nach Modulnummer)
+| Modul | Container | Service | Host-Port | Öffentlich? |
+|-------|-----------|---------|-----------|-------------|
+| 01 | Modul-01-PostgreSQL | PostgreSQL | **55432** | ja (Admin/Debug) |
+| 02 | Modul-02-RabbitMQ | RabbitMQ AMQP | 55672 | ja |
+| 02 | Modul-02-RabbitMQ | RabbitMQ Management | 15672 | ja |
+| 03 | Modul-03-Market-Data | FastAPI | 55003 | **nein** (nur intern) |
+| 04 | Modul-04-Market-Regime | — | 55004 | (Platzhalter) |
+| 05 | Modul-05-Strategy-Engine | — | 55005 | (Platzhalter) |
+| 06–17 | … | — | 55006–55017 | (Platzhalter) |
+
+## Weitere Dienste (Host)
+| Dienst | Container | Port |
+|--------|-----------|------|
+| Forgejo | forgejo-c4u8yyi1eaz1gepn3pqmr5fb | 3000 (HTTP) / 22222 (SSH) |
+| Tolaria (Second Brain) | tolaria | 5173 |
+| OpenClaw Alice | openclaw-suqw-openclaw-1 | 55163 |
+| OpenClaw Matt | openclaw-3sgu-openclaw-1 | 54524 |
+| Hermes Rain | hermes-workspace-e6un… | 32776 (UI) |
+| Ollama | ollama-nb6d-ollama-1 | 11434 (intern) |
+| n8n | n8n | (Coolify-managed) |
+| Traefik | traefik | 80/443 |
+
+## Docker-interne Hostnamen (wichtig für Container-Kommunikation)
+- PostgreSQL: `Modul-01-PostgreSQL:5432`
+- RabbitMQ: `Modul-02-RabbitMQ:5672` (vhost `trading`)
+- Ollama: `ollama-nb6d-ollama-1:11434`
+
+## Sicherheits-Notizen
+- **Port 55003 (Modul-03) ist NICHT öffentlich** — nur im Docker-Netzwerk erreichbar (via `expose`, nicht `ports`). Verifiziert: `curl http://187.124.31.123:55003/health` schlägt fehl.
+- Zugangsdaten ausschließlich als Env-Variablen/Secrets, nie im Code.
+- Öffentliche Ports nur, wo nötig (Admin/Debug/UI).
+
+---
+```
+Geändert von: Rain Ocampo
+Datum: 20.08.2026
+Grund: Port- und Service-Referenz für das Trading-System dokumentiert.
+```