Brancheneinstufung2/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.
    ```python
    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:
    ```text
    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.
    ```python
    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.
    ```typescript
    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.
    ```javascript
    // 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:
        ```yaml
        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.*