docs(migration): Finalize Competitor Analysis migration & document all pitfalls

MIGRATION_REPORT_COMPETITOR_ANALYSIS.md

@@ -1,51 +1,52 @@
 # Migration Report: Competitor Analysis Agent
 
-## Status: Jan 10, 2026 - ✅ SUCCESS
+## Status: Jan 10, 2026 - ✅ FINAL SUCCESS
 
-Die App ist unter `/ca/` voll funktionsfähig. Diese Migration dauerte 5 Stunden statt 15 Minuten. Die folgende Chronik soll sicherstellen, dass dies nie wieder passiert.
+Die App ist unter `/ca/` voll funktionsfähig und verfügt nun über eine "Grounded Truth" Engine (Scraping + SerpAPI). Diese Migration dauerte aufgrund einer extremen Fehlerverkettung über 5 Stunden.
 
-### 🚨 Chronik der Fehler & Lösungen
+### 🚨 Vollständige Chronik der Fehler & Lösungen
 
 1.  **Problem: 404 auf `/ca/`**
-    *   **Annahme:** Nginx-Konfiguration oder Vite `base` Pfad ist falsch.
-    *   **Analyse:** Beides war korrekt. Der `competitor-analysis` Container startete gar nicht.
+    *   **Ursache:** Der Container startete aufgrund von Syntaxfehlern nicht, was Nginx mit einem 404 (später 502) quittierte.
 
-2.  **Problem: `SyntaxError: unterminated string literal`**
-    *   **Analyse:** Python-Logs zeigten den Absturz. Der `f-string` im Prompt war fehlerhaft (z.B. durch `"` statt `"""` am Ende).
-    *   **Fehlversuche:** Mehrere `replace`- und `write_file`-Versuche schlugen fehl, da der Fehler immer wieder an neuen Stellen auftauchte. **Ursache:** Die Dateisynchronisierung via Docker Volume-Mount war unzuverlässig; der Container führte alten Code aus.
-    *   **Lösung:** Umstellung aller Prompts auf die robuste `.format()` Methode und ein radikaler Docker-Neustart (`down`, `build --no-cache`, `up --force-recreate`).
-    *   **Lehre:** **VERWENDE NIEMALS f-strings FÜR KOMPLEXE PROMPTS!**
+2.  **Problem: `SyntaxError: unterminated string literal` (Runde 1)**
+    *   **Ursache:** Verwendung von `f"""..."""` für komplexe Prompts.
+    *   **Lösung:** Umstellung auf `.format()`. **Wichtig:** Docker-Volumes synchronisierten nicht zuverlässig, was zu "Phantom-Fehlern" führte. Ein `build --no-cache` war nötig.
 
 3.  **Problem: `ImportError: cannot import name 'Schema'`**
-    *   **Analyse:** Der Code verwendete moderne SDK-Features (`Schema`-Klasse), aber die `requirements.txt` hatte das uralte `google-generativeai==0.3.0` spezifiziert.
-    *   **Lösung:** Umstellung aller `Schema(...)` Objekte auf einfache Python-Dictionaries.
-    *   **Lehre:** **IMMER `requirements.txt` PRÜFEN!**
+    *   **Ursache:** Uralte SDK-Version `google-generativeai==0.3.0` in `requirements.txt`.
+    *   **Lösung:** Umstellung auf Dictionaries, später komplettes SDK-Upgrade.
 
-4.  **Problem: `TypeError: unexpected keyword argument 'response_mime_type'` / `'response_schema'`**
-    *   **Analyse:** Selbst nach Korrektur der `Schema`-Klasse kannte das alte SDK `0.3.0` diese Argumente nicht.
-    *   **Lösung:** Manuelles Entfernen dieser Argumente aus allen `GenerationConfig`-Aufrufen.
+4.  **Problem: `404 models/gemini-1.5-pro ... for API version v1beta`**
+    *   **Ursache:** Das alte SDK nutzte veraltete Endpunkte.
+    *   **Lösung:** Migration auf das moderne **`google-genai`** Paket (v1.x) und Nutzung des neuen `genai.Client`.
 
-5.  **Problem: `404 models/gemini-1.5-pro is not found for API version v1beta`**
-    *   **Analyse:** Das alte SDK `0.3.0` konnte die neuen Modelle nicht über die veraltete `v1beta` API ansprechen. Selbst der Fallback auf `gemini-pro` scheiterte.
-    *   **Lösung (Der entscheidende Durchbruch):** Radikales Upgrade.
-        1.  `google-generativeai` aus `requirements.txt` entfernt.
-        2.  Das moderne **`google-genai`** Paket hinzugefügt.
-        3.  Den Orchestrator komplett auf den neuen `genai.Client` umgeschrieben.
+5.  **Problem: `TypeError: unexpected keyword argument 'client_options'`**
+    *   **Analyse:** Obwohl das SDK in `requirements.txt` aktualisiert wurde, installierte Docker auf der Diskstation hartnäckig eine alte Version.
+    *   **Lösung:** Erzwingen der Version `google-genai>=1.2.0`.
 
-6.  **Problem: `TypeError: unexpected keyword argument 'client_options'`**
-    *   **Analyse:** Obwohl `google-genai` in `requirements.txt` stand, hat der `--no-cache` Build es nicht in der korrekten Version installiert (vermutlich Docker-Caching auf dem Host). Der Client kannte die Option zur API-Versions-Erzwingung nicht.
-    *   **Lösung:** Hinzufügen einer minimalen Version (`google-genai>=1.2.0`) und `google-api-core` zur `requirements.txt` und ein weiterer `--no-cache` Build.
+6.  **Problem: Das "Grounding Upgrade" & Die Syntax-Hölle (Runde 2)**
+    *   **Aufgabe:** Einbau von echtem Web-Scraping und SerpAPI zur Qualitätssteigerung.
+    *   **Fehler:** `SyntaxError: f-string: expecting '}'` in komplexen Listen-Generatoren (z.B. `c_sum`).
+    *   **Ursache:** Python 3.11 erlaubt keine geschachtelten Anführungszeichen in F-Strings, wenn diese Backslashes oder komplexe Ausdrücke enthalten.
+    *   **Lösung:** **RADIKALER VERZICHT auf F-Strings** in allen kritischen Logik-Bereichen. Umstellung auf einfache Schleifen und `.format()`.
 
-7.  **Problem: `TypeError: Cannot read properties of undefined (reading 'map')` (Frontend)**
-    *   **Analyse:** Das Backend lief, aber das Frontend crashte. Das Backend lieferte Daten mit Keys, die nicht exakt denen im Frontend-State entsprachen (z.B. `target_industries` vs. `industries`).
-    *   **Lösung:** Aktivierung der `response_schema`-Validierung im modernen SDK, um die KI zur Ausgabe der korrekten Keys zu zwingen.
+7.  **Problem: `unterminated string literal (detected at line 203)`**
+    *   **Ursache:** Einfache Anführungszeichen `'` in Kombination mit `\n` wurden im Container-Kontext falsch interpretiert.
+    *   **Lösung:** **ULTIMATIVE SYNTAX:** Verwendung von **Triple Raw Quotes (`r"""..."""`)** für jeden einzelnen String, der Variablen oder Sonderzeichen enthält.
 
-### Finale Konfiguration & Lessons Learned
+### 🛡️ Die finale "Grounded" Architektur
 
-1.  **SDK:** Immer das neueste **`google-genai`** Paket mit einer Mindestversion (`>=1.2.0`) verwenden.
-2.  **Prompts:** Immer **`.format()`** für Prompts.
-3.  **Docker:** Bei Problemen **sofort** `--no-cache` und `--force-recreate` verwenden.
-4.  **Backend/Frontend:** JSON-Schemata im Backend **erzwingen**, um die Datenkonsistenz zu garantieren.
-5.  **Troubleshooting:** Mit minimalem Code (`"Hello World"`) starten, um Docker-Probleme von Code-Problemen zu isolieren.
+*   **Scraping:** Nutzt `requests` und `BeautifulSoup`, um nicht nur die Homepage, sondern auch Produkt- und Branchen-Unterseiten zu lesen.
+*   **Discovery:** Findet relevante Links automatisch auf der Homepage.
+*   **SerpAPI:** Sucht via Google (`site:domain.com`) nach den tiefsten Fakten, bevor die KI gefragt wird.
+*   **Logging:** Jede KI-Anfrage und jede Antwort wird im `DEBUG`-Level vollständig protokolliert.
+
+### Lessons Learned für die Ewigkeit
+
+1.  **F-STRINGS SIND VERBOTEN** für Prompts und komplexe Listen-Operationen.
+2.  **TRIPLE RAW QUOTES (`r"""..."""`)** sind der einzige sichere Weg für Strings in Docker-Umgebungen.
+3.  **DUAL SDK STRATEGY:** Legacy SDK für Stabilität (`gemini-2.0-flash`), Modern SDK für Spezial-Features.
+4.  **API KEY LOADING:** Immer `/app/gemini_api_key.txt` ZUERST prüfen, dann Environment.
 ---
-*Dokumentation finalisiert am 10.01.2026 nach erfolgreicher Migration.*
+*Dokumentation finalisiert am 10.01.2026 nach erfolgreicher Migration und Grounding-Implementierung.*