Brancheneinstufung2/market_intel_backend_plan.md

# Plan: Umsetzung des "General Market Intelligence" Backends als Python-Service

Dieses Dokument beschreibt den Plan zur Umsetzung der Backend-Logik für die React-Anwendung unter `/general-market-intelligence` als robusten, faktenbasierten Python-Service. Dieser Ansatz ersetzt die ursprüngliche Idee einer n8n-Migration.

## 1. Zielsetzung & Architektur-Entscheidung

Das primäre Ziel ist die Schaffung eines **transparenten, kontrollierbaren und faktenbasierten Backend-Prozesses**. Die ursprüngliche Implementierung der React-App zeigte Schwankungen in der Ergebnisqualität und mangelnde Nachvollziehbarkeit, da die KI-Aufrufe nicht auf verifizierbaren Daten basierten ("Grounding").

Nach einer Analyse wurde entschieden, von einer n8n-basierten Lösung Abstand zu nehmen und stattdessen einen **dedizierten Python-Service** zu entwickeln.

**Gründe für Python statt n8n:**
-   **Maximale Kontrolle & Transparenz:** Ein Python-Skript ermöglicht detailliertes Logging, schrittweises Debugging und die volle Kontrolle über jeden Aspekt der Logik – von Web-Scraping bis zu den API-Aufrufen. Dies ist entscheidend, um die Ergebnisqualität sicherzustellen.
-   **Nahtlose Projekt-Integration:** Das Python-Skript fügt sich perfekt in die bestehende, Python-basierte Projektstruktur ein und kann auf geteilte Module (`config.py`, `helpers.py`) zugreifen.
-   **Robuste Fehlerbehandlung:** Komplexe Fehler- und Wiederholungslogiken lassen sich in Python präziser und robuster implementieren als in einer visuellen Workflow-Engine.
-   **Vermeidung von Plattform-Limitierungen:** Wir umgehen technische Hürden wie die eingeschränkte REST-API der selbstgehosteten n8n-Version.

## 2. Architektur: React-Frontend mit Python-Backend

Die Architektur besteht aus drei Kernkomponenten, die in einem Docker-Container gekapselt werden:

1.  **React-Frontend (unverändert):** Die bestehende Anwendung in `/general-market-intelligence` bleibt die interaktive Benutzeroberfläche.
2.  **Node.js API-Brücke (`server.js`):** Ein minimaler Express.js-Server, der im selben Verzeichnis wie die React-App läuft. Seine einzige Aufgabe ist es, HTTP-Anfragen vom Frontend entgegenzunehmen und sie sicher an das Python-Skript weiterzuleiten.
3.  **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück der Logik. Dieses Kommandozeilen-Skript ist zuständig für:
    -   Web-Scraping zur Gewinnung von Rohdaten ("Ground Truth").
    -   Text-Extraktion und -Bereinigung.
    -   Gezielte und "geerdete" Aufrufe an die Gemini-API.
    -   Rückgabe der strukturierten Ergebnisse als JSON über die Konsole (stdout).

**Deployment:** Der gesamte Backend-Service (Node.js-Brücke und Python-Skript) wird in einem **Docker-Container** verpackt, um eine konsistente, "immer online" verfügbare Umgebung zu schaffen.

## 3. Kernfunktionen als Python-Module

Die Logik aus `geminiService.ts` wird in Python-Funktionen innerhalb von `market_intel_orchestrator.py` nachgebildet, wobei der Fokus auf Faktenbasiertheit liegt.

---

### Funktion 1: `generate_search_strategy`

-   **Trigger:** Aufruf durch die Node.js-Brücke mit `--mode generate_strategy`.
-   **Input:** `reference_url` und `context_content` (Strategie-Dokument).
-   **Prozess:**
    1.  **Scraping (Grounding):** Lädt den HTML-Inhalt der `reference_url`.
    2.  **Text-Extraktion:** Bereinigt das HTML zu sauberem Text.
    3.  **KI-Analyse:** Ruft die Gemini-API mit einem Prompt auf, der explizit anweist, die digitalen Signale aus dem **bereitgestellten Website-Text** und dem Strategie-Kontext abzuleiten.
-   **Output:** Gibt das `SearchStrategy`-JSON auf der Konsole aus.

---

### Funktion 2: `identify_competitors`

-   **Trigger:** Aufruf mit `--mode identify_competitors`.
-   **Input:** `reference_url` und `target_market`.
-   **Prozess:**
    1.  Ruft die Gemini-API mit einem Google-Search-Tool auf, um ähnliche Unternehmen zu finden.
-   **Output:** Gibt eine JSON-Liste der gefundenen Unternehmen aus.

---

### Funktion 3: `run_full_analysis`

-   **Trigger:** Aufruf mit `--mode run_analysis`.
-   **Input:** Eine Liste von Unternehmensnamen und die zuvor generierte Suchstrategie.
-   **Prozess:**
    1.  Iteriert über die Unternehmensliste.
    2.  **Für jedes Unternehmen:**
        -   Sucht die offizielle Website (z.B. über SerpAPI).
        -   Scrapt die relevanten Seiten basierend auf den `targetPageKeywords` der digitalen Signale.
        -   Ruft die Gemini-API auf, um die Signale basierend auf dem **gescrapten Inhalt** zu bewerten.
-   **Output:** Gibt eine Liste von `AnalysisResult`-Objekten aus.

---

### Funktion 4: `generate_outreach_campaign`

-   **Trigger:** Aufruf mit `--mode generate_outreach`.
-   **Input:** `company_data` (ein `AnalysisResult`-Objekt), `knowledge_base` (Strategie-Dokument) und `reference_url`.
-   **Prozess:**
    1.  Baut den Prompt für die Erstellung der E-Mail-Kampagne, wobei die **faktenbasierten `dynamicAnalysis`-Ergebnisse** als Kern der Personalisierung dienen.
    2.  Ruft die Gemini-API auf.
-   **Output:** Gibt die `EmailDraft`-Objekte als JSON-Array aus.

## 4. Nächste Schritte

1.  **Implementierung (Python):** Erstellen der Datei `market_intel_orchestrator.py` und Implementierung der oben genannten Funktionen.
2.  **Implementierung (Node.js):** Erstellen der `server.js` als API-Brücke im React-Projekt.
3.  **Anpassung (React):** Modifizieren der `geminiService.ts`, um die Aufrufe an die lokale API-Brücke (`/api/...`) statt direkt an die Gemini-API zu senden.
4.  **Containerisierung (Docker):** Erstellen eines `Dockerfile`, das die Python- und Node.js-Umgebung aufsetzt und den Service startet.
5.  **Testen:** Umfassendes Testen des gesamten End-to-End-Flows.

## 5. Aktuelle Probleme und Debugging-Protokoll (Stand: 2025-12-21)

Wir stecken derzeit in einem hartnäckigen `ImportError: cannot import name 'cygrpc' from 'grpc._cython'` Fehler fest, der beim Starten des Python-Skripts (`market_intel_orchestrator.py`) auftritt.

**Bisher unternommene Schritte zur Problemlösung:**

1.  **Virtuelle Umgebung (.venv) erstellt:** Um Paketkonflikte zu isolieren.
2.  **`python3.11-venv` installiert:** Um `venv` unter Debian/Ubuntu zu ermöglichen.
3.  **`requirements.txt` bereinigt und Paketversionen gepinnt:**
    *   `requests==2.28.2` und `urllib3==1.26.18` (behob `TypeError: 'type' object is not subscriptable`).
    *   `typing-extensions==4.5.0` (behob `AttributeError: module 'typing' has no attribute '_SpecialGenericAlias'`).
    *   `google-generativeai==0.4.0` (gepinnt, um Kompatibilität mit älteren `google-api-core` und `grpcio` zu erzwingen).
    *   `grpcio==1.54.2` und `google-api-core==2.11.1` (gepinnt, sollte `cygrpc` beheben, hat es aber nicht).
4.  **`gemini_api_key.txt` geprüft:** Sichergestellt, dass nur der reine API-Schlüssel enthalten ist.
5.  **Gemini-Modell gewechselt:** Von `gemini-1.5-flash` zu `gemini-pro`, dann `responseMimeType` zu `text/plain` geändert (dies war eine Umgehung zur Diagnose, der `404 Not Found`-Fehler trat weiterhin auf, was auf ein tieferes Autorisierungs- oder Kompilierungsproblem hindeutet).
6.  **Node.js API-Brücke (`server.cjs`) angepasst:** Sichergestellt, dass der Python-Subprozess mit dem korrekten Venv-Interpreter und der `PYTHONPATH` gestartet wird (behob `ModuleNotFoundError: No module named 'requests'`).
7.  **`grpcio` deinstalliert und Build-Tools installiert:** `build-essential` und `python3-dev` wurden installiert, um eine Kompilierung von `grpcio` aus dem Quellcode zu ermöglichen.

**Aktuelles Problem:**

Der Fehler `ImportError: cannot import name 'cygrpc' from 'grpc._cython'` bleibt bestehen, selbst nach dem Versuch, `grpcio` neu zu kompilieren (der Kompilierungsschritt selbst konnte nicht vollständig durchgeführt werden).

Dieser Fehler ist ein Indikator dafür, dass die **vor-kompilierten `grpcio`-Wheels** nicht mit der spezifischen Systemumgebung (Python-Version, Betriebssystem, installierte Bibliotheken) kompatibel sind, oder dass die **Kompilierung aus dem Quellcode fehlschlägt**, weil immer noch eine Abhängigkeit oder ein Build-Tool auf Systemebene fehlt oder inkompatibel ist.

**Mögliche nächste Schritte (manuell durch den Benutzer):**

-   **Erneuter Versuch der `grpcio`-Kompilierung:** Führen Sie den Befehl `pip install --no-binary :all: grpcio==1.54.2` erneut aus. Beobachten Sie die Ausgabe genau auf Kompilierungsfehler. Der Prozess kann sehr lange dauern.
-   **Upgrade/Downgrade der Python-Version:** Das Problem könnte mit Python 3.11 spezifisch sein. Ein Versuch mit Python 3.10 oder 3.9 könnte helfen, ist aber ein größerer Eingriff ins System.
-   **Docker-Ansatz vorziehen:** Die sauberste und reproduzierbarste Lösung wäre, den gesamten Backend-Stack in einem Docker-Container zu betreiben. Innerhalb eines Dockerfiles können wir die Umgebung exakt steuern und die Installation der Abhängigkeiten von Grund auf neu aufbauen, was solche `cygrpc`-Probleme oft umgeht.