Brancheneinstufung2/docs/BUILDER_APPS_MIGRATION.md

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

CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):

1. 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.
2. 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", um beide je nach Bedarf zu verwenden.
3. 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.
4. 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)

1. SDKs: Stehen google-genai UND google-generativeai in der requirements.txt?
2. Prompts: Sind alle Prompts als r"""...""".format() angelegt?
3. Grounding: Wird vor dem KI-Call die Webseite der Firma gescrapt?
4. Package.json: Sind Build-Tools (vite, typescript) in dependencies (NICHT devDependencies)?
5. Vite Config: Ist base: './' gesetzt?
6. DB-Datei: Wurde die leere .db-Datei auf dem Host via touch erstellt?

---

1. Detaillierte Fehlerlösungen & Code-Vorlagen

Dieser Abschnitt enthält die aus der Git-Historie wiederhergestellten "Lessons Learned".

1.1 Python: Abhängigkeiten & SDKs (Häufigste Fehlerquelle)

Problem 1: ModuleNotFoundError bei geteilten Bibliotheken

• Fehler: Eine kleine App stürzt ab, weil sie helpers.py importiert, aber nicht alle darin verwendeten Bibliotheken (z.B. gspread, pandas) in ihrer eigenen requirements.txt hat.
• Lösung (in helpers.py): "Exotische" Importe optional machen.

  try:
      import gspread
      GSPREAD_AVAILABLE = True
  except ImportError:
      GSPREAD_AVAILABLE = False
      gspread = None # Wichtig, damit Referenzen nicht fehlschlagen
  

• Lösung (in requirements.txt der App): Nur die direkt für die App benötigten Pakete auflisten. Nicht blind die globale requirements.txt kopieren. Für eine typische App sind das oft nur:

  google-generativeai
  google-genai
  Pillow
  requests
  beautifulsoup4
  

Problem 2: ImportError für Schema oder Content

• Fehler: ImportError: cannot import name 'Schema' from 'google.generativeai.types'
• Ursache: Der Code ist für eine neuere Version des google-generativeai-SDK geschrieben, aber im Projekt ist eine ältere Version (z.B. 0.3.0) installiert, in der diese Klassen anders hießen oder nicht existierten.
• Lösung (für Legacy SDKs):
  1. Entferne die direkten Importe für Schema und Content.
  2. Übergebe Konfigurationen wie generation_config als einfaches Python-Dictionary. Das alte SDK ist damit zufrieden.

Problem 3: AttributeError: module 'google.generativeai' has no attribute 'Client'

• Ursache: Der Code verwendet eine veraltete API (genai.Client), die im SDK entfernt wurde.
• Lösung: Den Code auf die moderne GenerativeModel-API umstellen.

  genai.configure(api_key="YOUR_KEY")
  model = genai.GenerativeModel('gemini-1.5-flash-latest')
  response = model.generate_content(...)
  

1.2 Frontend: Build-Prozess & Server

Problem 1: npm run build schlägt im Docker-Container fehl

• Ursache: Wichtige Build-Tools (vite, typescript etc.) stehen fälschlicherweise in devDependencies in der package.json. Der Docker-Build installiert diese standardmäßig nicht.
• Lösung: Alle devDependencies in die dependencies verschieben.

Problem 2: "White Screen" - App lädt nicht

• Ursache: Die App wird unter einem Unterpfad (z.B. /ce/) bereitgestellt, aber Vite sucht die JS/CSS-Dateien im Root (/).
• Lösung (in vite.config.ts): Den Basispfad anpassen.

  export default defineConfig({
    base: './', // Zwingt Vite, relative Pfade zu nutzen
  });
  

1.3 Docker & Datenbank

Problem 1: OperationalError: no such table

• Ursache: Die .db-Datei wurde zwar mit touch erstellt, ist aber leer. Die Tabellen wurden nie initialisiert.
• Lösung: Die Datenbank-Initialisierung (z.B. python3 db_manager.py init) MUSS beim Start des server.cjs automatisch ausgeführt werden.

  // In server.cjs am Anfang
  const { spawn } = require('child_process');
  const dbScript = path.join(__dirname, 'gtm_db_manager.py'); // Pfad anpassen
  spawn('python3', [dbScript, 'init']);
  

Problem 2: Code-Änderungen werden nicht übernommen ("Geisterfehler")

• Ursache: Ein Volume-Mount in docker-compose.yml überschreibt die neueren Dateien im Image mit alten, lokalen Dateien. Besonders tückisch, wenn server.cjs an die falsche Stelle gemountet wird.
• Lösung:
  1. Immer git pull auf dem Host ausführen, bevor docker-compose build aufgerufen wird.
  2. Mount-Pfade präzise setzen. Wenn das Dockerfile server.cjs in /app/server.cjs kopiert, muss der Mount genau dorthin zeigen:

     volumes:
       - ./my-app-folder/server.cjs:/app/server.cjs # Korrekt
       - ./my-app-folder/:/app/my-app-folder/ # Falsch
     

---

Dokumentation wiederhergestellt und erweitert am 15.01.2026.