[30388f42] Infrastructure Hardening: Repaired CE/Connector DB schema, fixed frontend styling build, implemented robust echo shield in worker v2.1.1, and integrated Lead Engine into gateway.
This commit is contained in:
159
docs/market_intel_backend_plan.md
Normal file
159
docs/market_intel_backend_plan.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# 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://<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.
|
||||
```bash
|
||||
docker-compose restart market-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Status Update (2026-01-14) - Quality & Stability Refinements
|
||||
|
||||
|
||||
|
||||
**Erreichte Meilensteine:**
|
||||
|
||||
|
||||
|
||||
1. **Anti-Halluzinations-Fix (Technographic Audit):**
|
||||
|
||||
* **Problem:** Die KI hat aufgrund von Suggestiv-Prompts ("Look for SAP Ariba") oft Technologien halluziniert oder irrelevante Systeme als Wettbewerber eingestuft.
|
||||
|
||||
* **Lösung:** Entfernung aller festcodierten "Suggestiv-Listen" aus dem Code. Der Audit sucht nun rein faktenbasiert oder basierend auf der expliziten Strategie-Eingabe.
|
||||
|
||||
* **Ergebnis:** Keine "falschen Feinde" mehr. Wenn keine Konkurrenz-Hardware gefunden wird, wird korrekt "Greenfield" (Status Quo: Manuell) erkannt.
|
||||
|
||||
|
||||
|
||||
2. **Outreach-Optimierung ("Strategic Observer"):**
|
||||
|
||||
* **Prompting:** Radikale Überarbeitung des Outreach-Prompts.
|
||||
|
||||
* **Stil:** Weg vom "Verkäufer", hin zum "Scharfsinnigen Branchenbeobachter".
|
||||
|
||||
* **Opportunity Bridge:** Die E-Mails schlagen in der ersten Nachricht sofort die Brücke von der Beobachtung (z.B. "Expansion") zur Lösungskategorie (z.B. "Autonome Reinigungsrobotik"), ohne plump Features zu verkaufen.
|
||||
|
||||
* **Kontext-Sensitivität:** Technologische Signale (wie ERP-Systeme) werden nur noch bei Rollen erwähnt, für die sie relevant sind (CIO, CFO), aber bei operativen Rollen (Facility Management) ausgeblendet, um Verwirrung zu vermeiden.
|
||||
|
||||
|
||||
|
||||
3. **Produktionsreife:**
|
||||
|
||||
* Der Prozess liefert nun konsistent hochwertige, C-Level-taugliche Ansprachen, die strategische Schmerzpunkte mit operativen Lösungen verbinden.
|
||||
|
||||
|
||||
|
||||
### Nächste Schritte:
|
||||
|
||||
* **Regelbetrieb & Monitoring:** Überwachung der Qualität bei neuen Branchen.
|
||||
|
||||
--- End of content ---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user