docs: Umstellung des Market Intelligence Backends von n8n auf Python

Aktualisiert die Planungs- und Readme-Dateien, um den neuen Architekturansatz widerzuspiegeln, der ein Python-Skript, eine Node.js-API-Brücke und Docker für verbesserte Kontrolle, Transparenz und faktenbasierte Ergebnisse verwendet.

market_intel_backend_plan.md

@@ -0,0 +1,88 @@
+# 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.

n8n_migration_plan.md

@@ -1,93 +0,0 @@
-# Plan zur Migration des "General Market Intelligence" Skripts nach n8n (Hybrid-Ansatz)
-
-Dieses Dokument beschreibt den Plan zur Nachbildung der Funktionalität der React-Anwendung unter `/general-market-intelligence` als Backend-Logik in der Automatisierungsplattform n8n.
-
-## 1. Zielsetzung (Hybrid-Ansatz)
-
-Das Ziel ist die **Auslagerung der Kernlogik** (insbesondere der Gemini API-Aufrufe) aus der React-Anwendung in n8n-Workflows. Dies erhöht die **Transparenz, Kontrolle und Stabilität** der Ergebnisse.
-
--   Die **bestehende React-Anwendung bleibt als interaktives Frontend** für die Benutzerführung und Datenvisualisierung erhalten.
--   **n8n fungiert als reines Backend-API**, das von der React-Anwendung aufgerufen wird, um die rechenintensiven Aufgaben auszuführen.
-
-Dieser Ansatz kombiniert das Beste aus beiden Welten: eine reaktionsschnelle, benutzerfreundliche Oberfläche und ein robustes, leicht anpassbares Backend.
-
-## 2. Analyse der Kernfunktionalität
-
-Die bestehende Anwendung führt fünf Hauptschritte aus, die nun als separate, aufrufbare n8n-Workflows modelliert werden:
-
-1.  **Strategie-Erstellung:** Generiert eine Suchstrategie aus einem Strategie-Dokument und einer Referenz-URL.
-2.  **Lead-Identifizierung:** Findet ähnliche Unternehmen basierend auf der Referenz-URL.
-3.  **Manuelle Überprüfung:** **Dieser Schritt verbleibt vollständig im React-Frontend.** Die App zeigt die Liste an und ermöglicht die Kuratierung.
-4.  **Tiefenanalyse:** Analysiert die vom Nutzer kuratierte Liste von Unternehmen.
-5.  **Kampagnen-Erstellung:** Generiert personalisierte E-Mail-Entwürfe.
-
-## 3. Hybrid-Architektur: Zusammenspiel von React & n8n
-
-Die Kommunikation zwischen Frontend und Backend erfolgt über Webhooks:
-
-1.  **n8n-Workflows als API-Endpunkte:** Jeder Kernprozess wird als eigener n8n-Workflow mit einem **Webhook-Trigger** erstellt. Dieser Trigger stellt eine einzigartige URL bereit, die auf Anfragen wartet.
-2.  **React-App als Client:** Die Funktionen in der `geminiService.ts`-Datei der React-App werden so angepasst, dass sie nicht mehr direkt die Gemini-API, sondern die entsprechenden n8n-Webhook-URLs aufrufen (mittels `fetch` oder `axios`).
-3.  **Datenfluss (Beispiel):**
-    -   Der Nutzer lädt in der React-App eine Strategie-Datei hoch und klickt auf "Strategie erstellen".
-    -   Die React-App sendet den Dateiinhalt und die Referenz-URL per `POST`-Request an den n8n-Webhook für die Strategie-Erstellung.
-    -   Der n8n-Workflow wird ausgelöst, führt den Gemini-Call aus und sendet das Ergebnis (das `SearchStrategy`-JSON) als Antwort auf den Webhook-Request zurück.
-    -   Die React-App empfängt die JSON-Antwort und zeigt dem Nutzer den nächsten Schritt an.
-
-## 4. Benötigte n8n-Workflows (API-Endpunkte)
-
-Die folgenden Workflows müssen in n8n erstellt werden, um die Logik aus `geminiService.ts` abzubilden.
-
----
-
-### Workflow 1: `generateSearchStrategy`
-
--   **Trigger:** `Webhook` (erwartet `POST`-Request)
--   **Input (JSON Body):** `{ "referenceUrl": "...", "contextContent": "..." }`
--   **Aktion:**
-    1.  Nimmt die Eingabedaten entgegen.
-    2.  Baut den Prompt für die Strategie-Generierung.
-    3.  Ruft den `Gemini`-Knoten auf.
--   **Output:** `Respond to Webhook`-Knoten, der das `SearchStrategy` JSON-Objekt zurückgibt.
-
----
-
-### Workflow 2: `identifyCompetitors`
-
--   **Trigger:** `Webhook` (erwartet `POST`-Request)
--   **Input (JSON Body):** `{ "referenceUrl": "...", "targetMarket": "..." }`
--   **Aktion:**
-    1.  Baut den Prompt zur Identifizierung von Wettbewerbern.
-    2.  Ruft den `Gemini`-Knoten auf.
--   **Output:** `Respond to Webhook`-Knoten, der die Liste der gefundenen Unternehmen als JSON-Array zurückgibt.
-
----
-
-### Workflow 3: `runFullAnalysis`
-
-Dieser Workflow führt die Tiefenanalyse für eine ganze Liste von Unternehmen durch.
-
--   **Trigger:** `Webhook` (erwartet `POST`-Request)
--   **Input (JSON Body):** `{ "strategy": { ... }, "companies": [ { "name": "..." }, ... ] }`
--   **Aktion:**
-    1.  Nutzt den `Loop Over Items`-Knoten, um über die `companies`-Liste zu iterieren.
-    2.  **Innerhalb des Loops:** Ruft für jedes Unternehmen den `Gemini`-Knoten mit dem Prompt für die Tiefenanalyse (`analyzeCompanyWithStrategy`) auf.
-    3.  Sammelt die Ergebnisse aller Iterationen.
--   **Output:** `Respond to Webhook`-Knoten, der eine vollständige Liste von `AnalysisResult`-Objekten als JSON zurückgibt.
-
----
-
-### Workflow 4: `generateOutreachCampaign`
-
--   **Trigger:** `Webhook` (erwartet `POST`-Request)
--   **Input (JSON Body):** `{ "companyData": { ... }, "knowledgeBase": "...", "referenceUrl": "..." }`
--   **Aktion:**
-    1.  Baut den Prompt für die Erstellung der E-Mail-Kampagne.
-    2.  Ruft den `Gemini`-Knoten auf.
--   **Output:** `Respond to Webhook`-Knoten, der die `EmailDraft`-Objekte als JSON-Array zurückgibt.
-
-## 5. Nächste Schritte
-
-1.  **Umsetzung in n8n:** Erstellen der vier beschriebenen Workflows, beginnend mit `generateSearchStrategy`.
-2.  **Anpassung der React-App:** Modifizieren der `geminiService.ts`, um die `fetch`-Aufrufe auf die neuen n8n-Webhook-URLs umzuleiten.
-3.  **Konfiguration:** Die URLs der n8n-Webhooks müssen in der React-Anwendung als Umgebungsvariablen (`.env.local`) konfiguriert werden, um Flexibilität zwischen Entwicklungs- und Produktionsumgebungen zu gewährleisten.
-4.  **Sicherheit:** Absicherung der n8n-Webhooks, z.B. durch einen geheimen Header-Parameter, um unbefugte Aufrufe zu verhindern.

readme.md

@@ -662,44 +662,44 @@ Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktio
 
 ## 9. Standalone Tool: Market Intelligence App
 
-### Funktionsweise
+### Funktionsweise und Architektur
 
-Das Skript ist eine mehrstufige Webanwendung, die als B2B-Marktanalyse- und Lead-Qualifizierungs-Tool dient. Es nutzt die Gemini-API, um basierend auf strategischen Dokumenten eines Unternehmens potenzielle Kunden zu finden, zu analysieren und personalisierte Ansprachen zu generieren. Der Prozess ist in mehrere logische Schritte unterteilt:
+Das Market Intelligence Tool ist eine mehrstufige Webanwendung für die B2B-Marktanalyse und Lead-Qualifizierung. Es kombiniert eine interaktive React-Oberfläche mit einem robusten, faktenbasierten Python-Backend, um potenzielle Kunden zu finden, zu analysieren und personalisierte Ansprachen zu generieren.
+
+Der entscheidende Unterschied zur ursprünglichen Implementierung liegt im Backend-Ansatz: Statt direkter, potenziell inkonsistenter KI-Aufrufe aus dem Frontend wird ein kontrollierter, transparenter und auf echten Daten basierender Prozess eingesetzt, um die Qualität und Nachvollziehbarkeit der Ergebnisse massiv zu verbessern.
+
+#### Technische Umsetzung und Architektur
+
+Die Anwendung ist als Service in einem **Docker-Container** gekapselt und besteht aus drei Hauptkomponenten:
+
+1.  **React-Frontend:** Die Benutzeroberfläche unter `general-market-intelligence/` bleibt der interaktive Arbeitsbereich für den Benutzer. Alle Eingaben und die Visualisierung der Ergebnisse finden hier statt.
+2.  **Node.js API-Brücke:** Ein minimaler Express.js-Server, der als Schnittstelle zwischen dem Frontend und der Python-Logik dient. Er nimmt die Anfragen der App entgegen und ruft das Python-Skript als sicheren Unterprozess auf.
+3.  **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück des Systems. Dieses Skript führt die Kernlogik aus und ist nach dem Prinzip **"Grounding first"** konzipiert:
+    -   **Web-Scraping als "Ground Truth":** Bevor eine KI-Analyse stattfindet, werden die relevanten Webseiten der Unternehmen (Referenzkunden, Zielunternehmen) gescrapt. Der extrahierte, bereinigte Text dient als unveränderliche Faktenbasis.
+    -   **Gezielte KI-Analyse:** Die Gemini-API wird erst im zweiten Schritt aufgerufen. Sie erhält den extrahierten Website-Text als primären Kontext und die Anweisung, ihre Analyse (z.B. die Identifizierung digitaler Signale) ausschließlich auf diesen realen Daten zu basieren.
+
+Dieser Ansatz stellt sicher, dass die Ergebnisse nicht "halluziniert" sind, sondern auf den tatsächlichen Inhalten der Unternehmens-Websites beruhen, was zu konsistenteren und validierbareren Analysen führt.
+
+#### Der Analyse-Prozess im Überblick
+
+Der Prozess für den Benutzer bleibt weitgehend gleich, ist aber technisch solider untermauert:
 
 **Schritt 1: Input & Strategie-Erstellung**
-
+-   **Dateneingabe:** Der Benutzer lädt ein **Strategie-Dokument** hoch und gibt die **URL eines Referenzkunden** an.
-1.  **Dateneingabe:** Der Benutzer startet, indem er zwei primäre Informationen bereitstellt:
+-   **Backend-Prozess:**
-    *   Ein **Strategie-Dokument** (eine Markdown-Datei wie `yamaichi_neu.md`). Dieses Dokument ist das Herzstück und enthält detaillierte Informationen über das eigene Angebot, die Zielgruppen (Unternehmen und Personas), deren Schmerzpunkte (Pain Points) und den Nutzen der eigenen Lösung.
+    1.  Das Python-Skript scrapt die Website des Referenzkunden, um eine Faktenbasis ("Ground Truth") zu schaffen.
-    *   Die **URL eines Referenzkunden**. Diese URL dient als Kalibrierung, um ähnliche Unternehmen ("Lookalikes") zu finden.
+    2.  Die KI analysiert den Website-Inhalt im Kontext des Strategie-Dokuments und leitet daraus ein faktenbasiertes **"Ideal Customer Profile" (ICP)** und eine Liste hochrelevanter **"Digitaler Signale"** ab.
-2.  **Strategie-Generierung:** Das Skript sendet den Inhalt des Strategie-Dokuments und die Referenz-URL an die Gemini-API (`generateSearchStrategy`). Die KI analysiert diese Informationen und erstellt eine "Suchstrategie". Diese Strategie ist ein JSON-Objekt, das drei Kernpunkte enthält:
-    *   Eine kurze Zusammenfassung des Angebots.
-    *   Ein detailliertes "Ideal Customer Profile" (ICP).
-    -   Eine Liste von 3-5 spezifischen **"Digitalen Signalen"**. Das sind konkrete Merkmale, nach denen auf den Websites potenzieller Kunden gesucht werden soll (z.B. "verwendet eine bestimmte Technologie", "hat eine komplexe Retourenrichtlinie", "sucht Mitarbeiter mit bestimmten Skills").
 
 **Schritt 2: Identifizierung & Überprüfung der Zielunternehmen**
-
+-   **Lead-Findung:** Basierend auf der Referenz-URL wird eine Liste ähnlicher Unternehmen generiert.
-1.  **Lead-Findung:** Basierend auf der Referenz-URL und einem definierten Zielmarkt (z.B. "Deutschland") fragt das Skript die Gemini-API (`identifyCompetitors`), eine Liste von ca. 10 Konkurrenten oder ähnlichen Unternehmen zu erstellen.
+-   **Manuelle Überprüfung:** Der Benutzer kuratiert diese Liste im Frontend.
-2.  **Manuelle Überprüfung:** Die generierte Liste wird dem Benutzer angezeigt. Er hat die Möglichkeit, unpassende Unternehmen zu entfernen oder manuell weitere hinzuzufügen.
 
 **Schritt 3: Tiefenanalyse der Unternehmen (Audit)**
+-   **Backend-Prozess:**
+    1.  Für jedes Unternehmen auf der finalen Liste werden die relevanten Webseiten-Inhalte gescrapt.
+    2.  Die KI prüft für jedes Unternehmen das Vorhandensein der zuvor definierten "Digitalen Signale" **basierend auf dem gescrapten Text**.
+    3.  Die Ergebnisse werden zusammen mit einer Handlungsempfehlung aufbereitet.
 
-1.  **Iterative Analyse:** Für jedes Unternehmen auf der finalen Liste führt das Skript eine detaillierte Analyse durch (`analyzeCompanyWithStrategy`).
+**Schritt 4 & 5: Reporting & Personalisierte Ansprache**
-2.  **Analyse-Prozess:** Für jedes einzelne Unternehmen wird ein neuer Aufruf an die Gemini-API gesendet. Die KI erhält den Firmennamen und die zuvor erstellte "Suchstrategie" als Anweisung. Sie führt dann folgende Aufgaben aus:
+-   **Ergebnis-Darstellung:** Die faktenbasierten Analyseergebnisse werden im Frontend angezeigt.
-    *   **Firmographics:** Recherche von Basisdaten wie Umsatz und Mitarbeiterzahl.
+-   **Kampagnen-Generierung:** Die KI nutzt die validierten "Digitalen Signale" als Aufhänger, um hyper-personalisierte und extrem treffsichere E-Mail-Entwürfe zu erstellen.
-    *   **Signal-Prüfung:** Überprüfung der Website des Unternehmens auf die definierten "Digitalen Signale".
-    *   **Klassifizierung:** Einordnung des Unternehmens in Tiers (Größe) und Status (z.B. "Potenzieller Kunde", "Wettbewerber").
-    *   **Empfehlung:** Formulierung einer kurzen, prägnanten Handlungsempfehlung für den Vertrieb.
-
-**Schritt 4: Reporting**
-
-1.  **Ergebnis-Darstellung:** Alle Analyseergebnisse werden in einer übersichtlichen Tabelle zusammengefasst und angezeigt.
-2.  **Export:** Der gesamte Bericht kann als Markdown-Datei heruntergeladen werden.
-
-**Schritt 5: Personalisierte Ansprache (Outreach)**
-
-1.  **Kampagnen-Generierung:** Der Benutzer kann aus dem Report ein vielversprechendes Unternehmen auswählen, um eine personalisierte E-Mail-Kampagne zu erstellen.
-2.  **Kontext-Anreicherung:** Das Skript fragt nach einer "Wissensdatenbank" (typischerweise das gleiche Strategie-Dokument wie in Schritt 1).
-3.  **E-Mail-Entwurf:** Die KI (`generateOutreachCampaign`) erhält alle gesammelten Informationen über das Zielunternehmen, die Wissensdatenbank und den Referenzkunden. Basierend darauf erstellt sie drei hyper-personalisierte, sofort einsatzbereite E-Mail-Entwürfe, die auf verschiedene Personas (z.B. COO, HR-Leiter) zugeschnitten sind und die gefundenen "Digitalen Signale" als Aufhänger nutzen.
-4.  **Finalisierung:** Die Entwürfe können angesehen, bei Bedarf in andere Sprachen übersetzt und zur weiteren Verwendung kopiert werden.
-
-Zusammenfassend automatisiert das Skript den gesamten Prozess von der strategischen Planung über die Lead-Generierung und -qualifizierung bis hin zur Erstellung des ersten personalisierten Anschreibens.