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

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

```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]*