[31388f42] Update documentation: Append external lead ingestion to MIGRATION_PLAN and create Lead Engine README
This commit is contained in:
@@ -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).
|
||||
|
||||
68
lead-engine/README.md
Normal file
68
lead-engine/README.md
Normal file
@@ -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]*
|
||||
Reference in New Issue
Block a user