Migration Guide: Google AI Builder Apps -> Local Docker Stack

CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):

DIE GOLDENE REGEL DER STRINGS: Nutze NIEMALS f"""...""" für komplexe Prompts oder Listen-Operationen mit verschachtelten Keys. Es führt unweigerlich zu SyntaxError: unterminated string literal. Nutze AUSSCHLIESSLICH Triple Raw Quotes (r"""...""") und die .format() Methode.

SDK WAHL (DUAL SDK): Das moderne google-genai ist gut, aber das Legacy google-generativeai ist oft stabiler für reinen Text (gemini-2.0-flash). Nutze die "Dual SDK Strategy" aus helpers.py.

GROUNDED TRUTH (MUSS): Verlasse dich niemals auf das Wissen des Modells allein. Implementiere immer Web-Scraping (Homepage + Unterseiten) und SerpAPI-Suchen, um das Modell mit Fakten zu füttern.

DOCKER VOLUMES: Mounte nur spezifische Dateien, niemals den dist-Ordner überschreiben. Bei Syntax-Fehlern, die trotz Korrektur bleiben: docker-compose build --no-cache.

0. Der "Quick-Start" Checkliste (5-Minuten-Plan)

SDK: Stehen beide SDKs in der requirements.txt?
Prompts: Sind alle Prompts als r"""...""".format() angelegt?
Grounding: Werden Produkt- und Branchenseiten gescrapt?
Package.json: Sind Build-Tools in dependencies?
Vite Config: Ist base: './' gesetzt?

1. Vorbereitung & Abhängigkeiten (Common Pitfalls)

Bevor Code kopiert wird, müssen die Grundlagen stimmen.

1.1 Package.json Check (Frontend Build-Falle)

Build-Tools wie vite, @vitejs/plugin-react oder typescript müssen in den dependencies stehen, nicht in devDependencies. Der multi-stage Docker-Build installiert standardmäßig keine dev-dependencies.

1.2 Python Syntax & F-Strings (Der Prompt-Albtraum)

Verschachtelte Anführungszeichen in F-Strings sprengen den Python-Parser in vielen Umgebungen. RICHTIG:

prompt = r"""
Analysiere "{name}". Antworte JSON: {{"key": "value"}}
""".format(name=item['name'])

1.3 Volume Mounts & Datei-Synchronisierung

Einzeldatei-Mounts (- ./file.py:/app/file.py) sind oft unzuverlässig bei schnellen Code-Änderungen. Im Zweifel das Image neu bauen.

2. Die AI Engine (Standard)

Nutze für alle Services die Logik aus gtm_architect_orchestrator.py:

Dual SDK Support (Legacy + Modern).
Modell-Fallback (Versuche 2.0-flash, dann 1.5-flash).
Grounded Scraping vor jedem KI-Aufruf.

Dokumentation finalisiert am 10.01.2026 nach der Competitor-Analysis Odyssee.

2.5 KiB Raw Blame History