120 lines
7.3 KiB
Markdown
120 lines
7.3 KiB
Markdown
# Lead Engine: Multi-Source Automation v2.2 [31988f42]
|
|
|
|
## 🚀 Übersicht
|
|
Die **Lead Engine** ist ein spezialisiertes Modul zur autonomen Verarbeitung von B2B-Anfragen. 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**.
|
|
* **Filter & Routing:** Unterscheidet Anfragen von **TradingTwins** und dem **Kontaktformular**.
|
|
* **Parsing:** Spezialisierte HTML-Parser extrahieren strukturierte Daten (Firma, Kontakt, Bedarf).
|
|
|
|
### 2. Contact Research (LinkedIn Lookup)
|
|
* **Automatisierung:** Sucht via **SerpAPI** und **Gemini 2.0 Flash** nach der beruflichen Position.
|
|
* **Ergebnis:** Identifiziert Rollen (z.B. "CFO"), um den Tonfall anzupassen.
|
|
|
|
### 3. Company Explorer Sync & Monitoring
|
|
* **Integration:** Legt Accounts und Kontakte automatisch im CE an.
|
|
* **Monitor:** Hintergrund-Prozess (`monitor.py`) überwacht den Analyse-Status.
|
|
* **Daten-Pull:** Übernimmt Branche und Dossier in die lokale Lead-Datenbank.
|
|
|
|
### 4. Expert Response Generator
|
|
* **KI-Engine:** Gemini 2.0 Flash erstellt E-Mail-Entwürfe.
|
|
* **Kontext:** Kombiniert Lead-Daten + CE-Daten + Matrix-Argumente (Pains/Gains).
|
|
|
|
### 5. Trading Twins Autopilot (PRODUKTIV v2.2)
|
|
Der vollautomatische "Zero Touch" Workflow für Trading Twins Anfragen.
|
|
|
|
* **Human-in-the-Loop:** Elizabeta Melcer erhält eine Teams-Nachricht ("Approve/Deny").
|
|
* **Feedback-Server:** Ein integrierter FastAPI-Server (Port 8004) verarbeitet Klicks.
|
|
* **Direct Calendar Booking (Micro-Service):**
|
|
* **Logik:** Prüft den Kalender von `e.melcer` auf **echte Verfügbarkeit**.
|
|
* **Raster:** Termine starten nur im **15-Minuten-Takt** (:00, :15, :30, :45).
|
|
* **Abstand:** Bietet zwei Termine an, mit ca. **3 Stunden Pause** dazwischen.
|
|
* **Buchung:** Klick auf Link -> Server erstellt Outlook-Termin von `info@` mit `e.melcer` als Teilnehmer.
|
|
|
|
## 🏗 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/ # Autopilot Modul
|
|
│ ├── manager.py # Orchestrator, FastAPI, Graph API Logic
|
|
│ ├── test_calendar_logic.py # Interner Test für Kalender-Zugriff
|
|
│ └── signature.html # HTML-Signatur (mit Bildern im selben Ordner)
|
|
└── db.py # Lokale SQLite Lead-Datenbank
|
|
```
|
|
|
|
## 🚨 Lessons Learned & Critical Fixes
|
|
|
|
### 1. Microsoft Graph API: Kalender-Zugriff
|
|
* **Problem:** `debug_calendar.py` scheiterte oft mit `TimeZoneNotSupportedException`.
|
|
* **Ursache:** Der API-Aufruf zur Abfrage der Verfügbarkeit (`getSchedule`) hat keine explizite Zeitzoneninformation erhalten.
|
|
* **Lösung:** Die Zeitzone ("Europe/Berlin") wird nun explizit im `payload` des API-Aufrufs mitgegeben.
|
|
|
|
### 2. Exchange AppOnly AccessPolicy (Buchungs-Workaround)
|
|
* **Problem:** `Calendars.ReadWrite` erlaubt einer App oft nicht, Termine in *fremden* Kalendern (`e.melcer@`) zu erstellen (`403 Forbidden`).
|
|
* **Lösung:** Der Termin wird im **eigenen Kalender** des Service-Accounts (`info@`) erstellt. Der Mitarbeiter (`e.melcer@`) wird als **Teilnehmer** hinzugefügt. Das umgeht die Policy.
|
|
|
|
### 3. Dynamische HTML-Signatur mit Inline-Bildern
|
|
* **Problem:** Eine statische Signatur in der Konfiguration war unflexibel und konnte keine Bilder enthalten.
|
|
* **Lösung:** Ein Skript (`scripts/extract_signature_assets.py`) extrahiert die vollständige HTML-Signatur und alle eingebetteten Bilder aus einer `.eml`-Datei. Die `send_email`-Funktion wurde überarbeitet, um alle Bilder dynamisch als Inline-Anhänge zu versenden, was eine professionelle Darstellung sicherstellt.
|
|
|
|
### 4. Advanced Debugging & Fehlerbehebung
|
|
* **Problem:** Hintergrund-Tasks schlugen ohne klare Fehlermeldung fehl, was die Diagnose erschwerte.
|
|
* **Lösung:** Umfassendes Logging wurde in allen kritischen Funktionen implementiert. Dadurch konnten Fehler wie ein `NameError` bei der Datumsformatierung und die `TimeZoneNotSupportedException` schnell identifiziert und behoben werden.
|
|
|
|
## 🚀 Inbetriebnahme & Test
|
|
|
|
### Inbetriebnahme
|
|
```bash
|
|
# Neustart des Dienstes
|
|
docker-compose up -d --build --force-recreate lead-engine
|
|
```
|
|
|
|
### Test & Debugging
|
|
* **Allgemeiner Test:** Die URL `https://floke-ai.duckdns.org/feedback/test_lead` löst einen generischen Test-Lead aus.
|
|
* **Spezifischer Test pro Lead:** Im Lead-Tool (`/lead/`) kann für jeden Lead mit einem generierten E-Mail-Entwurf der Button "🧪 Test-Versand (an floke.com@gmail.com)" geklickt werden. Dies startet den gesamten End-to-End-Prozess (Teams-Nachricht & E-Mail-Versand) für den ausgewählten Lead, sendet die E-Mail aber sicher an die Test-Adresse.
|
|
|
|
**Zugriff:** `https://floke-ai.duckdns.org/lead/` (Passwortgeschützt)
|
|
|
|
## 📝 Zukünftige Erweiterungen & Todos
|
|
|
|
### Task: Race-Condition-Schutz bei Überbuchung
|
|
* **Problem:** Wenn mehrere Leads E-Mails mit denselben Terminvorschlägen erhalten, kann es zu "Race Conditions" kommen, bei denen mehrere Personen denselben Slot fast zeitgleich buchen.
|
|
* **Lösung:** Implementierung eines "Live-Checks" im Feedback-Server.
|
|
1. **Trigger:** Ein Nutzer klickt auf einen Buchungslink.
|
|
2. **Aktion:** Bevor der Termin im Kalender erstellt wird, sendet der Server eine *erneute* `getSchedule`-Anfrage an die Graph API für exakt diesen Zeit-Slot.
|
|
3. **Logik:**
|
|
* **Slot frei:** Der Termin wird wie geplant gebucht und der Job-Status auf `booked` gesetzt.
|
|
* **Slot belegt:** Der Nutzer erhält eine freundliche Nachricht ("Dieser Termin wurde gerade vergeben."). Idealerweise werden ihm dynamisch zwei neue, freie Termine vorgeschlagen, die er direkt auf der Seite buchen kann.
|
|
* **Ziel:** Sicherstellen, dass der Kalender die "Single Source of Truth" ist und doppelte Buchungen zuverlässig verhindert werden.
|
|
|
|
### Task: Integration der Buchungs-Seiten in WordPress
|
|
* **Ziel:** Eine nahtlose User Experience schaffen, bei der Termin-Bestätigungen auf der Haupt-Website (`robo-planet.de`) statt auf der direkten API-URL angezeigt werden.
|
|
* **Phase 1 (Kurzfristig): Einbettung via iFrame**
|
|
* **Umsetzung:** Eine Seite in WordPress anlegen und die URL des Feedback-Servers (z.B. `https://floke-ai.duckdns.org/feedback/book_slot/...`) in einem iFrame laden.
|
|
* **Vorteil:** Kein Programmieraufwand auf unserer Seite nötig, sofort umsetzbar.
|
|
* **Phase 2 (Langfristig): Native API-Integration**
|
|
* **Umsetzung:** Die Links in der E-Mail führen direkt zu einer WordPress-Seite (z.B. `robo-planet.de/termin-bestaetigen`). Ein Skript auf dieser Seite ruft im Hintergrund unsere `/book_slot` API auf.
|
|
* **Vorteil:** Perfekte Integration ins Corporate Design, volle Kontrolle über die Erfolgs- und Fehlermeldungen. Die API ist dafür bereits ausgelegt.
|
|
|
|
|
|
```env
|
|
# Info-Postfach (App 1 - Schreiben)
|
|
INFO_Application_ID=...
|
|
INFO_Tenant_ID=...
|
|
INFO_Secret=...
|
|
|
|
# E.Melcer Kalender (App 2 - Lesen)
|
|
CAL_APPID=...
|
|
CAL_TENNANT_ID=...
|
|
CAL_SECRET=...
|
|
|
|
# URLs
|
|
TEAMS_WEBHOOK_URL=...
|
|
FEEDBACK_SERVER_BASE_URL=https://floke-ai.duckdns.org/feedback
|
|
``` |