feat(gtm): add aspect ratio & corporate design; fix(market): harden backend logging & json parsing

gtm_architect_documentation.md

@@ -1,4 +1,4 @@
-# Dokumentation: GTM Architect Engine (v2.3)
+# Dokumentation: GTM Architect Engine (v2.4)
 
 ## 1. Projektübersicht
 
@@ -15,9 +15,10 @@ graph LR
     User[Browser] -- HTTP/JSON --> Proxy[Nginx :8090]
     Proxy -- /gtm/ --> NodeJS[Node.js Server :3005]
     NodeJS -- Spawn Process --> Python[Python Orchestrator]
-    Python -- google.genai --> Gemini[Google Gemini 2.0 Flash (Text)]
-    Python -- google.genai --> Imagen[Google Imagen 4.0 (Text-to-Image)]
-    Python -- google.genai --> GeminiImg[Google Gemini 2.5 Flash Image (Image-to-Image)]
+    Python -- import --> Helpers[Core Engine (helpers.py)]
+    Helpers -- Dual SDK --> Gemini[Google Gemini 2.0 Flash (Text)]
+    Helpers -- Dual SDK --> Imagen[Google Imagen 4.0 (Text-to-Image)]
+    Helpers -- Dual SDK --> GeminiImg[Google Gemini 2.5 Flash (Image-to-Image)]
     Python -- SQL --> DB[(SQLite: gtm_projects.db)]
 ```
 
@@ -25,24 +26,44 @@ graph LR
 
 1.  **Frontend (`/gtm-architect`):**
     *   Framework: **React** (Vite + TypeScript).
-    *   **Feature (NEU):** **Session History** (Sitzungsverlauf). Ermöglicht das Laden alter Projekte direkt aus der Datenbank.
-    *   **Feature (NEU):** **Markdown Upload**. Ermöglicht das Importieren externer Report-Dateien (`.md`).
-    *   **UI:** Verbesserte Tabelle für Strategie-Matrix.
+    *   Features: **Session History** (Laden/Löschen alter Projekte) und **Markdown Upload**.
 
 2.  **Backend Bridge (`server.cjs`):**
     *   Runtime: **Node.js** (Express).
-    *   Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse.
+    *   Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse (`gtm_architect_orchestrator.py`).
 
 3.  **Logic Core (`gtm_architect_orchestrator.py`):**
     *   Runtime: **Python 3.11+**.
-    *   **Datenbank-Integration:** Vollständiger Support für CRUD-Operationen via `gtm_db_manager.py`.
-    *   **Automatisierung:** Automatische Projekterstellung beim ersten Start (Phase 1) basierend auf dem Produktnamen.
-    *   **Output-Sanitization:** Automatisches Entfernen von Markdown-Codefences (` ```markdown `), um korrektes Rendering im Frontend sicherzustellen.
+    *   Verantwortlichkeit: Steuert den 9-Phasen-Prozess, verwaltet Payloads und interagiert mit der Datenbank. Nutzt `helpers.py` für alle KI-Interaktionen.
 
-4.  **Persistenz (`gtm_projects.db`):**
-    *   Typ: **SQLite**. Speichert alle Phasen-Ergebnisse als JSON-Blobs.
+4.  **Core Engine (`helpers.py`):**
+    *   Laufzeit: **Python 3.11+**.
+    *   Verantwortlichkeit: Abstrahiert die Komplexität der KI-API-Aufrufe. Stellt robuste, wiederverwendbare Funktionen für Text- und Bildgenerierung bereit.
 
-## 3. Der 9-Phasen Prozess
+5.  **Persistenz (`gtm_projects.db`):**
+    *   Typ: **SQLite**. Speichert alle Phasen-Ergebnisse als JSON-Blobs in einer einzigen Tabelle.
+
+## 3. Kernfunktionalität: Die AI Engine (`helpers.py`)
+
+Das Herzstück des Systems ist die `helpers.py`-Bibliothek, die für Stabilität und Zukunftssicherheit konzipiert wurde.
+
+### 3.1 Dual SDK Support
+
+Um maximale Stabilität zu gewährleisten und gleichzeitig Zugriff auf die neuesten KI-Modelle zu haben, wird ein dualer Ansatz für die Google AI SDKs verfolgt:
+*   **`google-generativeai` (Legacy):** Wird bevorzugt für Text-Generierungs-Aufgaben (`gemini-2.0-flash`) verwendet, da es sich in diesem Setup als robuster erwiesen hat.
+*   **`google-genai` (Modern):** Wird für alle Bild-Generierungs-Aufgaben und als Fallback für die Text-Generierung genutzt.
+
+### 3.2 Hybride Bildgenerierung
+
+Die `call_gemini_image`-Funktion wählt automatisch die beste Methode basierend auf dem Input:
+*   **Szenario A: Text-to-Image (Kein Referenzbild)**
+    *   **Modell:** `imagen-4.0-generate-001`.
+    *   **Anwendung:** Generiert ein komplett neues Bild basierend auf einem textuellen Prompt (z.B. für Landingpage-Banner).
+*   **Szenario B: Image-to-Image (Mit Referenzbild)**
+    *   **Modell:** `gemini-2.5-flash-image`.
+    *   **Anwendung:** Platziert ein existierendes Produkt (via Upload) in eine neue, per Text beschriebene Szene. Der Prompt ist darauf optimiert, das Produktdesign nicht zu verändern.
+
+## 4. Der 9-Phasen Prozess
 
 | Phase | Modus | Input | Output | Beschreibung |
 | :--- | :--- | :--- | :--- | :--- |
@@ -56,19 +77,24 @@ graph LR
 | **8** | `phase8` | Phase 1, 2 | Business Case | CFO-Argumentation, ROI-Logik. |
 | **9** | `phase9` | Phase 1, 4 | Feature-to-Value | Übersetzung technischer Features in Nutzen. |
 
-## 4. Sitzungs-Management (NEU)
+## 5. Sitzungs-Management
 
-Das System verwaltet nun persistente Sitzungen:
+Das System verwaltet persistente Sitzungen in der SQLite-Datenbank:
 *   **List:** Abruf aller gespeicherten Projekte mit Zeitstempel.
 *   **Load:** Vollständige Wiederherstellung des App-States (alle Phasen).
 *   **Delete:** Permanentes Entfernen aus der Datenbank.
 
-## 5. Deployment & Betrieb
+## 6. Deployment & Betrieb
 
 *   **Wichtig:** Das Frontend wird im Build-Stage gebaut. Bei Änderungen an `App.tsx` muss der Container mit `docker-compose up -d --build gtm-app` neu gebaut werden.
-*   **Backend:** Änderungen an `gtm_architect_orchestrator.py` erfordern keinen Build, nur einen Restart (`docker restart gtm-app`).
+*   **Backend:** Änderungen an `gtm_architect_orchestrator.py` oder `helpers.py` erfordern keinen Build, nur einen Restart (`docker restart gtm-app`).
 
-## 6. Historie & Fixes (Jan 2026)
+## 7. Historie & Fixes (Jan 2026)
+
+*   **[UPGRADE] v2.4:**
+    *   Dokumentation der Kern-Engine (`helpers.py`) mit Dual SDK & Hybrid Image Generation.
+    *   Aktualisierung der Architektur-Übersicht und Komponenten-Beschreibungen.
+    *   Versionierung an den aktuellen Code-Stand (`v2.4.0`) angepasst.
 
 *   **[UPGRADE] v2.3:**
     *   Einführung der Session History (Datenbank-basiert).