Brancheneinstufung2/lead-engine/README.md

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

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

2. Zwei Azure Apps für Sicherheit

Wir nutzen zwei getrennte App-Registrierungen, um "Least Privilege" zu wahren:

• App 1 (INFO_...): Hat Schreibrechte (Mail.Send, Calendars.ReadWrite) für das info@robo-planet.de Postfach. Sie sendet E-Mails und erstellt die Termine.
• App 2 (CAL_...): Hat nur Leserechte (Calendars.ReadBasic.All) für den Kalender von e.melcer@robo-planet.de. Sie wird genutzt, um Konflikte zu prüfen, darf aber nichts ändern oder E-Mails lesen.

3. Docker Networking & Public URLs

• Problem: Links in Teams-Nachrichten zeigten auf http://lead-engine:8004 (interner Docker-Name) und waren von außen nicht erreichbar.
• Lösung: Die URL muss immer die öffentliche, vom Nginx-Proxy geroutete URL sein (https://floke-ai.duckdns.org/feedback).
• Konfiguration: Nginx leitet /feedback/ an Port 8004 des lead-engine Containers weiter.

🚀 Inbetriebnahme (Docker)

Die Lead Engine ist als Service in der zentralen docker-compose.yml integriert.

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

# 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]