115 lines
6.5 KiB
Markdown
115 lines
6.5 KiB
Markdown
# Lead Engine: Multi-Source Automation v1.3 [31988f42]
|
|
|
|
## 🚀 Übersicht
|
|
Die **Lead Engine** ist ein spezialisiertes Modul zur autonomen Verarbeitung von B2B-Anfragen aus verschiedenen Quellen. Sie fungiert als Brücke zwischen dem E-Mail-Postfach und dem **Company Explorer**, um innerhalb von Minuten hochgradig personalisierte Antwort-Entwürfe auf "Human Expert Level" zu generieren.
|
|
|
|
## 🛠 Hauptfunktionen
|
|
|
|
### 1. Intelligenter E-Mail Ingest
|
|
* **Multi-Source:** Überwacht das Postfach `info@robo-planet.de` via **Microsoft Graph API** auf verschiedene Lead-Typen.
|
|
* **Filter & Routing:** Erkennt und unterscheidet Anfragen von **TradingTwins** und dem **Roboplanet-Kontaktformular**.
|
|
* **Parsing:** Spezialisierte HTML-Parser extrahieren für jede Quelle strukturierte Daten (Firma, Kontakt, Bedarf, etc.).
|
|
|
|
### 2. Contact Research (LinkedIn Lookup)
|
|
* **Automatisierung:** Sucht via **SerpAPI** und **Gemini 2.0 Flash** nach der beruflichen Position des Ansprechpartners.
|
|
* **Ergebnis:** Identifiziert Rollen wie "CFO", "Mitglied der Klinikleitung" oder "Facharzt", um den Tonfall der Antwort perfekt anzupassen.
|
|
|
|
### 3. Company Explorer Sync & Monitoring
|
|
* **Integration:** Legt Accounts und Kontakte automatisch im CE an.
|
|
* **Monitor:** Ein Hintergrund-Prozess (`monitor.py`) überwacht asynchron den Status der KI-Analyse im CE.
|
|
* **Daten-Pull:** Sobald die Analyse (Branche, Dossier) fertig ist, werden die Daten in die lokale Lead-Datenbank übernommen.
|
|
|
|
### 4. Expert Response Generator
|
|
* **KI-Engine:** Nutzt Gemini 2.0 Flash zur Erstellung von E-Mail-Entwürfen.
|
|
* **Kontext:** Kombiniert Lead-Daten (Fläche) + CE-Daten (Dossier) + Matrix-Argumente (Pains/Gains).
|
|
* **Persistente Entwürfe:** Generierte E-Mail-Entwürfe werden direkt beim Lead gespeichert und bleiben erhalten.
|
|
|
|
### 5. UI & Qualitätskontrolle
|
|
* **Visuelle Unterscheidung:** Klare Kennzeichnung der Lead-Quelle (z.B. 🌐 für Website, 🤝 für Partner) in der Übersicht.
|
|
* **Status-Tracking:** Visueller Indikator (🆕/✅) für den Synchronisations-Status mit dem Company Explorer.
|
|
* **Low-Quality-Warnung:** Visuelle Kennzeichnung (⚠️) von Leads mit Free-Mail-Adressen oder ohne Firmennamen direkt in der Übersicht.
|
|
|
|
### 6. Trading Twins Autopilot (PRODUKTIV v2.0)
|
|
Der vollautomatische "Zero Touch" Workflow für Trading Twins Anfragen.
|
|
|
|
* **Human-in-the-Loop:** Vor Versand erhält Elizabeta Melcer eine Teams-Nachricht ("Approve/Deny") via Adaptive Card.
|
|
* **Feedback-Server:** Ein integrierter FastAPI-Server (Port 8004) verarbeitet die Klicks aus Teams und gibt sofortiges visuelles Feedback.
|
|
* **Direct Calendar Booking (Eigener Service):**
|
|
* **Problem:** MS Bookings API lässt sich nicht per Application Permission steuern (Erstellung verboten).
|
|
* **Lösung:** Wir haben einen eigenen Micro-Booking-Service gebaut.
|
|
* **Ablauf:** Das System prüft echte freie Slots im Kalender von `e.melcer` (via Graph API).
|
|
* **E-Mail:** Der Kunde erhält eine E-Mail mit zwei konkreten Terminvorschlägen (Links).
|
|
* **Buchung:** Klick auf einen Link -> Server bestätigt -> **Echte Outlook-Kalendereinladung** wird automatisch von `info@` versendet.
|
|
* **Technologie:**
|
|
* **Teams Webhook:** Für interaktive "Adaptive Cards".
|
|
* **Graph API:** Für E-Mail-Versand (`info@`) und Kalender-Check (`e.melcer`).
|
|
* **Orchestrator (`manager.py`):** Steuert den Ablauf (Lead -> CE -> Teams -> Timer -> Mail -> Booking).
|
|
|
|
## 🏗 Architektur
|
|
|
|
```text
|
|
/app/lead-engine/
|
|
├── app.py # Streamlit Web-Interface
|
|
├── trading_twins_ingest.py # E-Mail Importer (Graph API)
|
|
├── monitor.py # Monitor + Trigger für Orchestrator
|
|
├── trading_twins/ # [NEU] Autopilot Modul
|
|
│ ├── manager.py # Orchestrator, FastAPI Server, Graph API Logic
|
|
│ ├── signature.html # HTML-Signatur für E-Mails
|
|
│ └── debug_bookings_only.py # Diagnose-Tool (Legacy)
|
|
├── db.py # Lokale Lead-Datenbank
|
|
└── data/ # DB-Storage
|
|
```
|
|
|
|
## 🚨 Lessons Learned & Troubleshooting (Critical)
|
|
|
|
### 1. Microsoft Bookings API Falle
|
|
* **Problem:** Wir wollten `Bookings.Manage.All` nutzen, um eine Buchungsseite für `info@` zu erstellen.
|
|
* **Fehler:** `403 Forbidden` ("Api Business.Create does not support the token type: App") und `500 Internal Server Error` (bei `GET`).
|
|
* **Erkenntnis:** Eine App (Service Principal) kann zwar Bookings *verwalten*, aber **nicht initial erstellen**. Die erste Seite muss zwingend manuell oder per Delegated-User angelegt werden. Zudem erfordert der Zugriff oft eine User-Lizenz, die Service Principals nicht haben.
|
|
* **Lösung:** Umstieg auf **Direct Calendar Booking** (Graph API `Calendar.ReadWrite`). Wir schreiben Termine direkt in den Outlook-Kalender, statt über die Bookings-Schicht zu gehen. Das ist robuster und voll automatisierbar.
|
|
|
|
### 4. Exchange AppOnly AccessPolicy
|
|
* **Problem:** Trotz globaler `Calendars.ReadWrite` Berechtigung schlug das Erstellen von Terminen im Kalender von `e.melcer@` fehl (`403 Forbidden: Blocked by tenant configured AppOnly AccessPolicy settings`).
|
|
* **Erkenntnis:** Viele Organisationen schränken per Policy ein, auf welche Postfächer eine App zugreifen darf. Ein Zugriff auf "fremde" Postfächer ist oft standardmäßig gesperrt.
|
|
* **Lösung:** Der Termin wird im **eigenen Kalender** des Service-Accounts (`info@robo-planet.de`) erstellt. Der zuständige Mitarbeiter (`e.melcer@`) wird als **erforderlicher Teilnehmer** hinzugefügt. Dies umgeht die Policy-Sperre und stellt sicher, dass der Mitarbeiter den Termin in seinem Kalender sieht und das Teams-Meeting voll steuern kann.
|
|
|
|
## 🚀 Inbetriebnahme (Docker)
|
|
|
|
## 🚀 Inbetriebnahme (Docker)
|
|
|
|
Die Lead Engine ist als Service in der zentralen `docker-compose.yml` integriert.
|
|
|
|
```bash
|
|
# Neustart des Dienstes nach Code-Änderungen
|
|
docker-compose up -d --build --force-recreate lead-engine
|
|
```
|
|
|
|
**Zugriff:** `https://floke-ai.duckdns.org/lead/` (Passwortgeschützt)
|
|
**Feedback API:** `https://floke-ai.duckdns.org/feedback/` (Öffentlich)
|
|
|
|
## 📝 Credentials (.env)
|
|
|
|
Für den Betrieb sind folgende Variablen in der zentralen `.env` zwingend erforderlich:
|
|
|
|
```env
|
|
# App 1: Info-Postfach (Schreiben)
|
|
INFO_Application_ID=...
|
|
INFO_Tenant_ID=...
|
|
INFO_Secret=...
|
|
|
|
# App 2: E.Melcer Kalender (Lesen)
|
|
CAL_APPID=...
|
|
CAL_TENNANT_ID=...
|
|
CAL_SECRET=...
|
|
|
|
# Teams
|
|
TEAMS_WEBHOOK_URL=...
|
|
|
|
# Public URL
|
|
FEEDBACK_SERVER_BASE_URL=https://floke-ai.duckdns.org/feedback
|
|
```
|
|
|
|
---
|
|
*Dokumentationsstand: 5. März 2026*
|
|
*Task: [31988f42]*
|