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. 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:

   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 Dockerfilen oder den requirements.txt/package.json notwendig.

Zugriff

• Das zentrale Dashboard ist unter http://<Server-IP>:8090 erreichbar.
• Das Market Intelligence Tool ist direkt über das Unterverzeichnis http://<Server-IP>: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.

  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.