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 (für die nächste Sitzung)

1. Die neuesten Code-Änderungen pullen (git pull).
2. Das Docker-Image neu bauen, um die Korrektur zu übernehmen: docker build -t market-intel-backend .
3. Den alten Container stoppen/entfernen und den neuen starten: docker run -p 3001:3001 --name market-intel-backend-instance market-intel-backend
4. Den React-Dev-Server starten und den End-to-End-Test erneut durchführen.

5. Aktueller Status und Debugging-Protokoll (Stand: 2025-12-21 - Abschluss der Sitzung)

Status: End-to-End System voll funktionsfähig, Grounded & UX-optimiert!

Wir haben heute das gesamte System von einer instabilen n8n-Abhängigkeit zu einem robusten, autarken Python-Service transformiert.

Wichtigste Errungenschaften:

• Präzises Lookalike-Sourcing: Die Konkurrenten-Identifikation wurde von einer reinen Branchensuche auf eine ICP-basierte Lookalike-Suche umgestellt. Die Ergebnisse sind nun hochrelevant und thematisch am Referenzkunden ausgerichtet.
• Deep Tech Audit mit Beweisführung: Der Audit-Prozess (Schritt 3) nutzt nun eine kaskadierende Suchstrategie (Homepage-Scrape + gezielte SerpAPI-Suchen). Die KI zitiert konkrete Beweise (z.B. aus Stellenanzeigen) und liefert verifizierbare Links ("Proof").
• Echtes Terminal-Feedback: Die UI zeigt nun während des Audits einen echten Live-Log des Agenten an (Searching, Scraping, Analyzing), was die Wartezeit transparent macht.
• Robustes Logging: Umstellung auf Tages-Logdateien (z.B. 2025-12-21_market_intel.log), die im /app/Log Verzeichnis (via Docker Volume) gespeichert werden und den vollständigen Verlauf inkl. Prompts enthalten.
• Optimierte Infrastruktur: Schlankes Docker-Image mit Bind Mounts ermöglicht Hot-Reloading des Python-Codes und direkten Zugriff auf Logs und Keys (serpapikey.txt, gemini_api_key.txt).

Gelöste Probleme heute:

• Abhängigkeits-Chaos: Vollständige Entkopplung von helpers.py und config.py im Backend-Orchestrator.
• API-Endpunkt Fehler: Behebung aller v1beta 404 Fehler durch Umstieg auf direkte REST-Calls (Gemini v1).
• Frontend-Abstürze: Absicherung des Reports gegen fehlende Datenpunkte.

---

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.