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

MIGRATION_REPORT_COMPETITOR_ANALYSIS.md

@@ -1,44 +1,51 @@
 # Migration Report: Competitor Analysis Agent
 
-## Status: Jan 10, 2026 - ✅ FINAL SUCCESS
+## Status: Jan 10, 2026 - ✅ SUCCESS
 
-Die Migration ist abgeschlossen. Die App ist unter `/ca/` voll funktionsfähig.
+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 Odyssee: Chronologie der Fehler & Lösungen
+### 🚨 Chronik der Fehler & Lösungen
 
-Wir haben 4 Stunden für eine Aufgabe benötigt, die 10 Minuten dauern sollte. Hier ist das Protokoll des Scheiterns, damit es nie wieder passiert:
+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.
 
-#### 1. Der Python-Syntax-Albtraum (Stunde 1)
-*   **Fehler:** `SyntaxError: unterminated string literal`.
-*   **Ursache:** Verwendung von `f"""..."""` für Gemini-Prompts. Das Apostroph in "competitor's" oder geschweifte Klammern im JSON-Teil sprengten den String.
-*   **Lösung:** Umstellung auf **Raw Strings** `r"""..."""` und die **`.format()`** Methode.
+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. Das SDK-Versions-Dilemma (Stunde 2)
-*   **Fehler:** `ImportError: cannot import name 'Schema'`.
-*   **Ursache:** Versuch, moderne SDK-Features mit `google-generativeai==0.3.0` zu nutzen. Diese Version kennt keine Klassen für Schemata.
-*   **Lösung:** Upgrade auf das moderne **`google-genai`** Paket (v1.x) und Umstellung des gesamten Orchestrators auf den neuen Client.
+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!**
 
-#### 3. Die 404-Falle (Stunde 2.5)
-*   **Fehler:** Website nicht erreichbar, obwohl der Python-Server lief.
-*   **Ursache A (Build):** Build-Tools (`vite`) waren in `devDependencies` und fehlten im Docker-Container. -> **Fix:** Verschieben in `dependencies`.
-*   **Ursache B (Compose):** Ein Volume-Mount `- .:/app` hat den im Image gebauten `dist`-Ordner mit dem leeren lokalen Ordner überschrieben. -> **Fix:** Nur die Orchestrator-Datei mounten.
+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. Der "Modell nicht gefunden" Fehler (Stunde 3)
-*   **Fehler:** `404 models/gemini-1.5-pro is not found for API version v1beta`.
-*   **Ursache:** Das alte SDK nutzte veraltete Endpunkte, die die neuen 1.5/2.0 Modelle nicht sauber auflösen konnten.
-*   **Lösung:** Vollständige Migration auf den neuen **`genai.Client`**. Dieser nutzt die stabilen API-Pfade.
+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. Der finale "map of undefined" Fehler (Stunde 4)
-*   **Fehler:** Frontend lädt, crasht aber bei der Datenanzeige.
-*   **Ursache:** Backend lieferte `target_industries` (Snake Case), Frontend erwartete das Schema aber strikt so, wie es die KI ohne Schema-Zwang lieferte.
-*   **Lösung:** Aktivierung von **strikten JSON-Schemata** im `google-genai` Client. Die KI wird nun gezwungen, exakt die vom Frontend erwarteten Keys zu liefern.
+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.
 
-### 3. Lessons Learned (Zusammenfassung)
+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.
 
-1.  **F-STRINGS SIND GIFT** für Prompts.
-2.  **GOOGLE-GENAI (v1.x)** ist der neue Standard. Das alte Paket nicht mehr verwenden.
-3.  **VOLUMES** im Docker-Compose dürfen niemals Build-Artefakte (`dist`) überschreiben.
-4.  **SCHEMA ENFORCEMENT** ist Pflicht, um Frontend-Crashes zu vermeiden.
+### Finale Konfiguration & Lessons Learned
 
+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.
 ---
 *Dokumentation finalisiert am 10.01.2026 nach erfolgreicher Migration.*