### **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. |
| **8094** | `gtm-architect`| Intranet | GTM Architect Direct. |
| **8092** | `b2b-marketing`| Intranet | B2B Marketing Assistant Direct. |
| **8001** | `transcription`| Intranet | Transcription Tool Direct (via 8090). |

---

#### **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.
*   **Routing:** 
    * `/ce/` -> `company-explorer:8000`
    * `/lead/` -> `lead-engine:8501` (UI)
    * `/feedback/` -> `lead-engine:8004` (API)
    * `/gtm/` -> `gtm-architect:3005` (API/Frontend)
    * `/b2b/` -> `b2b-marketing-assistant:3002` (API/Frontend)
    * `/content/` -> `content-engine:3000` (API/Frontend)
    * `/market/` -> `market-intelligence:3001` (API/Frontend)
    * `/competitor/` -> `competitor-analysis:3000` (API/Frontend)
    * `/heatmap/` -> `heatmap-frontend:80` (Static/Proxy)
    * `/tr/` -> `transcription-tool:8001` (API/Frontend) -> **Achtung:** Benötigt expliziten `rewrite` in Nginx!

---

# ⚠️ Kritische Lehren (Update 08.03.2026)

Der Umzug muss zwingend diese Punkte beachten, um den "Totalausfall" zu vermeiden:

### 1. Datenbank-Schema & Volumes
**Regel:** Datenbanken werden **NIEMALS** mehr direkt auf einen Host-Pfad gemountet.
**Grund:** Permission-Errors und SQLite-Locks auf Netzwerk-Dateisystemen.
**Vorgehen:** Nutzung von benannten Volumes (`explorer_db_data`, `connector_db_data`, `lead_engine_data`, `gtm_architect_data`, `b2b_marketing_data`, `content_engine_data`, `market_intel_data`, `competitor_analysis_data`, `transcription_uploads`).

### 2. Lead Engine: Kalender-Logik (v1.4)
*   **Raster:** Das System bietet Termine nur im **15-Minuten-Takt** (:00, :15, :30, :45) an.
*   **Abstand:** Zwischen zwei Terminvorschlägen liegen mind. **3 Stunden** Pause.
*   **AppOnly Workaround:** Termin wird im Kalender von `info@robo-planet.de` erstellt und der Mitarbeiter (`e.melcer@`) als Teilnehmer hinzugefügt.

### 3. GTM Architect & B2B Assistant: Standalone-Betrieb
*   **Architektur:** Beide Apps nutzen das "Self-Contained Image" Muster. Code, Frontend-Builds (`dist/`) und `node_modules` sind fest im Image verbaut.
*   **GTM Port:** 3005 intern.
*   **B2B Port:** 3002 intern.
*   **DB-Abhängigkeit:** Der B2B Assistant benötigt zwingend die Datei `market_db_manager.py` (wird beim Build aus dem Root kopiert).

### 4. Transcription Tool: FFmpeg & Routing
*   **FFmpeg:** Muss im Image vorhanden sein (Build dauert ca. 15 Min auf Synology).
*   **Pfade:** Das Tool benötigt eine `tsconfig.json` im `frontend/` Ordner für den TypeScript-Build.
*   **Nginx:** Der Pfad `/tr/` muss explizit umgeschrieben werden: `rewrite ^/tr/(.*) /$1 break;`.

---

### 📂 Docker Volume Migration (Der "Plug & Play" Weg)

Um die Daten (Companies, Leads, Projekte, Audio-Files) ohne Verluste umzuziehen, müssen die benannten Volumes gesichert werden.

**Auf der Synology (Quelle):**
```bash
# Backup aller kritischen Volumes in ein Archiv
docker run --rm -v explorer_db_data:/data -v $(pwd):/backup alpine tar czf /backup/explorer_data.tar.gz -C /data .
docker run --rm -v lead_engine_data:/data -v $(pwd):/backup alpine tar czf /backup/lead_data.tar.gz -C /data .
docker run --rm -v gtm_architect_data:/data -v $(pwd):/backup alpine tar czf /backup/gtm_data.tar.gz -C /data .
docker run --rm -v b2b_marketing_data:/data -v $(pwd):/backup alpine tar czf /backup/b2b_data.tar.gz -C /data .
docker run --rm -v content_engine_data:/data -v $(pwd):/backup alpine tar czf /backup/content_data.tar.gz -C /data .
docker run --rm -v market_intel_data:/data -v $(pwd):/backup alpine tar czf /backup/market_data.tar.gz -C /data .
docker run --rm -v competitor_analysis_data:/data -v $(pwd):/backup alpine tar czf /backup/competitor_data.tar.gz -C /data .
docker run --rm -v transcription_uploads:/data -v $(pwd):/backup alpine tar czf /backup/tr_uploads.tar.gz -C /data .
```



**Auf der Ubuntu VM (Ziel):**
1. Volumes anlegen: `docker volume create explorer_db_data` (etc.)
2. Daten wiederherstellen:
```bash
docker run --rm -v explorer_db_data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/explorer_data.tar.gz"
```

---

### **Verbindlicher Migrationsplan**

**Phase 1: Vorbereitung**
1.  [ ] **`git push`** auf Synology (aktuellster Stand inkl. GTM-Integration).
2.  [ ] **`.env` Datei sichern** (Vollständigkeit prüfen!).
3.  [ ] **Volumes sichern** (siehe oben: `tar.gz` Erstellung).

**Phase 2: Deployment auf `docker1`**
1.  [ ] Repo klonen: `git clone ... /opt/gtm-engine`
2.  [ ] `.env` kopieren.
3.  [ ] **Volumes restoren** (BEVOR `docker compose up` ausgeführt wird).
4.  [ ] Starten: `docker compose up -d --build`
5.  [ ] **Schema-Check:** `docker exec -it company-explorer python /app/fix_missing_columns.py`

**Phase 3: Verifizierung**
1.  [ ] Check Kalender-Lesen: `docker exec lead-engine python /app/trading_twins/test_calendar_logic.py`
2.  [ ] Check GTM Architect: `https://10.10.81.2:8090/gtm/`