From aa38c555d8ec00165de66d1cdcb03646d4eab656 Mon Sep 17 00:00:00 2001 From: Floke Date: Mon, 2 Mar 2026 15:08:41 +0000 Subject: [PATCH] [31388f42] Update documentation: Append external lead ingestion to MIGRATION_PLAN and create Lead Engine README --- MIGRATION_PLAN.md | 40 +++++++++++++++---------- lead-engine/README.md | 68 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 15 deletions(-) create mode 100644 lead-engine/README.md diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 48091d92..fa3118b6 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -410,19 +410,29 @@ Der Company Explorer unterstützt nun den Parameter `campaign_tag`. Der Connecto --- +## 19. External Lead Ingestion & Contact API (v3.5 - March 2, 2026) + +**Kontext:** Automatisierte Verarbeitung von externen Lead-Quellen (Tradingtwins) direkt in den Company Explorer. + +### 19.1 API-Erweiterung: Externer Kontakt-Sync +Um Kontakte von externen Tools (wie der Lead-Engine) ohne SuperOffice-Kontext zu übernehmen, wurde die API erweitert. + +* **Neuer Endpunkt:** `POST /api/contacts` +* **Funktionalität:** + * Anlage von Personen-Stammdaten (Vorname, Nachname, E-Mail). + * **Automatisches Role-Mapping:** Der Endpunkt integriert den `RoleMappingService`. Eingehende Job-Titel (z.B. "CFO") werden automatisch gegen die interne Muster-Datenbank geprüft und der passenden Persona (z.B. "Wirtschaftlicher Entscheider") zugeordnet. + * **De-Duplizierung:** Existiert eine E-Mail bereits für ein Unternehmen, wird der Datensatz aktualisiert statt neu angelegt. + +### 19.2 Standardisierung der Datenfelder +Zur Verbesserung der asynchronen Zusammenarbeit zwischen Lead-Engine und CE wurden die Feldnamen in der API-Antwort vereinheitlicht: +* **Branche:** `industry_ai` (Primärfeld für die KI-Klassifizierung). +* **Analyse:** `research_dossier` (Das vollständige KI-generierte Firmendossier). + +### 19.3 Synchronisations-Workflow (Connector) +Der `company_explorer_connector.py` unterstützt nun den erweiterten Workflow: +1. `check_company_existence` (Suche via Name) +2. `create_company` (Anlage falls neu) +3. `create_contact` (Integration der Person inkl. Role-Mapping) +4. `trigger_discovery` / `trigger_analysis` (Asynchroner Start der Intelligence-Phase) + --- - -## 18. Offene Arbeitspakete (Stand: 27.02.2026) - -### Prio A: Operative Automatisierung -* **Webhook-Aktivierung:** Registrierung des Live-Webhooks für `online3`, sobald Admin-Rechte für den API-User vorliegen (`register_webhook.py`). -* **Full Matrix Generation:** Ausführung der KI-Generierung für alle 25 Verticals (englische IDs), sobald die "Pains" in Notion finalisiert wurden. -* **Campaign-Validation:** Erstellung von Test-Szenarien für mindestens 3 verschiedene Kampagnen-Tags zur Verifizierung der Weichenstellung. - -### Prio B: Marketing-Execution -* **Sending Logic:** Implementierung der Logik für den tatsächlichen E-Mail-Versand (oder Export zu einem E-Mail-Provider) basierend auf den befüllten UDFs. -* **Unsubscribe-Frontend:** Visuelle Gestaltung der HTML-Bestätigungsseite für den Unsubscribe-Link. - -### Prio C: Daten-Optimierung -* **Google Maps API:** Einbindung zur Validierung von Firmenadressen bei Diskrepanzen zwischen CRM und Scraper. -* **Deduplication 2.0:** Verfeinerung des Matchings bei Firmen mit mehreren Standorten (Filial-Logik). diff --git a/lead-engine/README.md b/lead-engine/README.md new file mode 100644 index 00000000..e369c7c5 --- /dev/null +++ b/lead-engine/README.md @@ -0,0 +1,68 @@ +# Lead Engine: Tradingtwins Automation v1.0 [31388f42] + +## 🚀 Ü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 +* **Quelle:** Überwacht das Postfach `info@robo-planet.de` via **Microsoft Graph API**. +* **Filter:** Erkennt gezielt Anfragen von Partnern wie Tradingtwins. +* **Parsing:** Ein spezialisierter HTML-Parser extrahiert strukturierte Daten: + * Firma, Ansprechpartner, E-Mail, Telefon. + * Bedarfsdaten (Reinigungsfläche, Einsatzzweck, gewünschte Funktionen wie Nassreinigung). + * Datum der ursprünglichen Anfrage. + +### 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). +* **Logik:** + * Wählt automatisch das passende Produkt (z.B. Scrubber 75 für > 5.000m²). + * Berücksichtigt Multi-Product Needs (Service-Roboter bei Gastronomie-Wünschen). + * Vermeidet KI-Floskeln und nutzt eine seniorige Business-Tonalität. + +### 5. Qualitätskontrolle +* Erkennt automatisch "Low Quality Leads" (Free-Mail Provider wie Gmail/Web.de oder fehlende Firmennamen) für potenzielle Reklamationen. + +## 🏗 Architektur + +```text +/app/lead-engine/ +├── app.py # Streamlit Web-Interface +├── trading_twins_ingest.py # E-Mail Importer (Graph API) +├── lookup_role.py # LinkedIn/Role Research (SerpAPI + Gemini) +├── generate_reply.py # Email Draft Generator (Gemini) +├── monitor.py # Asynchroner CE-Status Monitor +├── db.py # Lokale SQLite Lead-Datenbank +└── data/ # DB-Storage +``` + +## 🚀 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 lead-engine +``` + +**Zugriff:** `https://floke-ai.duckdns.org/lead/` (Passwortgeschützt) + +## 📝 Nutzungshinweise +1. **Ingest:** Klicke in der Web-App auf "2. Ingest Real Emails". +2. **Sync:** Wähle einen Lead und klicke auf "Sync to Company Explorer". +3. **Wait:** Der Monitor erkennt automatisch, wenn die Analyse im CE fertig ist. +4. **Draft:** Klicke auf "Generate Expert Reply" für den fertigen Entwurf. + +--- +*Dokumentationsstand: 2. März 2026* +*Task: [31388f42]*