# 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. Deployment & Betrieb in der Konsolidierten Architektur Das Market Intelligence Tool ist nun vollständig in die zentrale Docker-Compose-Architektur des Projekts integriert. Das separate Bauen und Starten einzelner Container, wie in den alten Abschnitten beschrieben, ist nicht mehr der richtige Weg. ### Zentraler Start via Docker Compose Der gesamte Anwendungs-Stack (Proxy, Dashboard, B2B Assistant, Market Intelligence) wird über die `docker-compose.yml`-Datei im Hauptverzeichnis des Projekts verwaltet und gestartet. 1. **Navigieren Sie in das Projekt-Hauptverzeichnis.** 2. **Starten Sie alle Dienste:** ```bash docker-compose up -d --build ``` Der `--build`-Parameter sorgt dafür, dass alle Docker-Images neu erstellt werden. Dies ist bei Änderungen am Frontend (`App.tsx`), an den `Dockerfile`n oder den `requirements.txt`/`package.json` notwendig. ### Zugriff - Das zentrale Dashboard ist unter `http://:8090` erreichbar. - Das **Market Intelligence Tool** ist direkt über das Unterverzeichnis `http://:8090/market/` zugänglich. - Der Zugang ist durch Basic Authentication geschützt (Benutzer: `admin`, Passwort: `gemini`). ### Entwicklung (Sideloading) Für eine schnelle Entwicklung ist "Sideloading" für die Python-Logik aktiviert. Das bedeutet, die `market_intel_orchestrator.py` wird als Volume in den Container gemountet. - **Nach Änderungen am Python-Skript:** Ein einfacher Neustart des Containers genügt, um die Änderungen zu übernehmen. Ein kompletter Rebuild ist nicht erforderlich. ```bash docker-compose restart market-backend ``` --- ## 6. Status Update (2025-12-22) - Campaign Engine & Reporting ### Erreichte Meilensteine: 1. **Rollenbasierte Campaign-Engine:** * Die Funktion `generate_outreach_campaign` wurde komplett überarbeitet. * Sie nutzt nun die volle Tiefe der Knowledge Base (`yamaichi_neu.md`), um **personalisierte Sequenzen für spezifische Rollen** (z.B. "Hardware-Entwickler" vs. "Einkäufer") zu erstellen. * Die Ansprache erfolgt strikt im "Partner auf Augenhöhe"-Tonfall. * **Social Proof Integration:** Der Absender (`reference_url`) wird als Beweis der Kompetenz inkl. passender KPIs im Abbinder integriert. * **"Grit"-Prompting:** Der Prompt wurde massiv geschärft, um operative Schmerzpunkte ("ASNs", "Bandstillstand") statt Marketing-Bla-Bla zu nutzen. 2. **Report Polishing (Frontend):** * Der Markdown-Export (`StepReport.tsx`) wurde erweitert. * Er enthält nun die **"Proof-Links"** (Beweise/URLs) direkt in den Tabellenzellen, sauber formatiert. Damit ist die Herleitung der Ergebnisse (z.B. "Warum nutzt der Kunde Ariba?") auch im Export transparent nachvollziehbar. 3. **Frontend UX & Bugfixes:** * **Kein doppelter Upload:** `StepOutreach.tsx` wurde angepasst, um den Strategie-Kontext aus Schritt 1 direkt zu übernehmen. * **Lösch-Bug:** `StepReview.tsx` wurde korrigiert, sodass gelöschte Unternehmen sofort aus der UI verschwinden. * **Crash-Fix:** Die Behandlung der API-Antwort in `geminiService.ts` wurde gehärtet, um die neue verschachtelte Antwortstruktur der Campaign-Engine korrekt zu verarbeiten. ### Nächste Schritte: * **Stabilitäts-Test:** Ausführung eines Batch-Audits mit >20 Firmen, um Rate-Limits und Fehlerbehandlung unter Last zu prüfen.