### **Anforderungsdokument (Version 3): Docker-Migration nach Ubuntu VM (`docker1`)**

**Zweck:** Verbindliche Netzwerk-Anforderungen und schrittweiser Migrationsplan für den Umzug des GTM-Engine Stacks (ca. 20 Container). Basierend auf den Stabilisierungs-Erkenntnissen vom 07.03.2026.

#### **Teil 1: Externe Port-Freigaben (Firewall)**

Diese Ports müssen auf der Firewall für den eingehenden Verkehr zur VM `10.10.81.2` geöffnet werden.

| Host-Port | Ziel-Dienst | Zugriff | Zweck |
| :--- | :--- | :--- | :--- |
| **8090** | `gateway_proxy` | Intranet | **Zentraler Zugang.** Alle Web-Apps (Dashboard, CE, Lead). |
| **3000** | `gitea` | Intranet | Gitea Web UI. |
| **2222** | `gitea` | Intranet | Gitea Git via SSH. |
| **8003** | `connector-so` | **Public** | SuperOffice Webhook-Empfänger (SSL erforderlich!). |
| **5678** | `n8n` | **Public** | Automation Workhooks. |
| **8004** | `lead-engine` | **Public** | Lead Engine API (für Buchungs-Links). |

---

#### **Teil 2: Netzwerk-Architektur (Intern)**

*   **DNS Resolver:** In Nginx konfiguriert (`resolver 127.0.0.11`).
*   **WebSockets:** Das Gateway unterstützt `Upgrade`-Header (kritisch für Streamlit/Lead-Engine).
*   **Echo-Prävention:** Der Connector (`worker.py`) identifiziert sich dynamisch. Keine manuellen ID-Einträge in `.env` nötig, solange `SO_CLIENT_ID` passt.

---

# ⚠️ Kritische Lehren (Post-Mortem 07.03.2026)

Der Umzug am Montag muss zwingend diese Punkte beachten, um den "Totalausfall" von heute zu vermeiden:

### 1. Datenbank-Schema-Falle
**Problem:** Alte `.db`-Dateien (Backups) haben oft nicht alle Spalten, die der aktuelle Code erwartet.
**Lösung:** Nach dem Starten der Container auf der neuen VM **muss** das Migrations-Skript ausgeführt werden:
```bash
docker exec -it company-explorer python /app/fix_missing_columns.py
```
*Dies repariert Tabellen für Companies, Industries und Contacts (inkl. Unsubscribe-Tokens).*

### 2. Docker Volumes vs. Bind Mounts
**Regel:** Datenbanken werden **NIEMALS** mehr direkt auf einen Host-Pfad gemountet.
**Grund:** Permission-Errors und SQLite-Locks ("Database is locked") auf Netzwerk-Dateisystemen (Synology/NFS).
**Vorgehen:** Nutzung von benannten Volumes (`explorer_db_data`, `connector_db_data`, `lead_engine_data`).

### 3. Daten-Injektion (Der "Rescue"-Befehl)
Um bestehende Daten in die neuen Volumes zu bekommen, nutzt man diesen Befehl:
```bash
# Beispiel für den Company Explorer
docker cp ./my_local_backup.db company-explorer:/data/companies_v3_fixed_2.db
```

### 4. Streamlit Proxy-Konfiguration
**Problem:** Streamlit (Lead Engine) verliert die Verbindung unter Sub-Pfaden (`/lead/`).
**Lösung:** 
*   Dockerfile: `--server.baseUrlPath=/lead` ist Pflicht.
*   Nginx: `proxy_http_version 1.1` und `Upgrade`-Header müssen gesetzt sein.

---

### **Verbindlicher Migrationsplan (Montag)**

**Phase 1: Vorbereitung**
1.  [ ] **`git push`** auf Synology (aktuellster Stand d1b77fd2).
2.  [ ] **`.env` Datei sichern** (enthält alle heute stabilisierten Keys!).

**Phase 2: Deployment auf `docker1`**
1.  [ ] Repo klonen: `git clone ... /opt/gtm-engine`
2.  [ ] `.env` anlegen und befüllen.
3.  [ ] Starten: `docker compose up -d --build`
4.  [ ] **Schema-Check:** `docker exec -it company-explorer python /app/fix_missing_columns.py` ausführen.

**Phase 3: Datenrettung (Falls nötig)**
1.  [ ] Datenbank-Dumps vom Wochenende via `docker cp` in die Volumes schieben.
2.  [ ] Webhook-Status prüfen: `docker exec -it connector-superoffice python /app/register_webhook.py`.

---

### **Aktuelle Offene Todos (Priorisiert)**

1.  **Lead Engine:** Microsoft Graph Credentials in `.env` ergänzen (401 Fehler beheben).
2.  **n8n:** Workflow-Export von Synology und Import auf neuer Instanz.
3.  **Styling:** Frontend-CSS im Company Explorer verifizieren (Build läuft wieder, aber UI-Check nötig).