first commit

README.md

@@ -0,0 +1,202 @@
+# 📋 Workflow-Beschreibung: LinkedIn Lead Research & Enrichment
+
+## 🎯 Zweck
+Automatisierte LinkedIn-Recherche mit KI-gestützter Datenanreicherung für Lead-Generierung. Der Workflow sucht LinkedIn-Profile nach definierten Kriterien, extrahiert Basis-Informationen und reichert diese intelligent mit Kontaktdaten und Unternehmensinformationen an.
+
+---
+
+## 🔄 Workflow-Ablauf
+
+### **Phase 1: Initialisierung & Suche**
+
+1. **Manual Trigger**
+   - Startet den Workflow manuell
+   
+2. **Get Status** (DataTable)
+   - Holt alle vorbereiteten Suchaufträge aus der DataTable
+   - Filtert auf `ready = true` (bereite Jobs)
+   - Liefert typisch ~80 Suchanfragen mit Kriterien (Titel, Stadt, etc.)
+
+3. **Check City**
+   - Validiert ob erforderliche Felder vorhanden sind
+   - Prüft: `city` nicht leer ODER `finished = false`
+   - Filtert ungültige/bereits bearbeitete Einträge aus
+
+4. **Prepare Search**
+   - Bereitet die Suchparameter vor
+   - Kombiniert: `title` + `city` zu Suchstring
+   - Format: z.B. "Steuerberater München"
+
+5. **Get Search Results** (Sub-Workflow)
+   - Ruft externes Workflow "Google: Get Search Results" auf
+   - Suche mit: `"[title] [city] site:linkedin.com/in"`
+   - Parameter: Seiten-Anzahl, Start-Index
+   - Liefert LinkedIn-URLs und Metadaten zurück
+
+6. **Fill Sheet** (Google Sheets)
+   - Schreibt Basis-Daten in "Leads-N8N-2" Tabelle
+   - Felder: ID, Titel, Beschreibung, Link, Vorname, Nachname
+   - Verwendet `appendOrUpdate` mit ID als Matching-Key
+   - Duplikate werden automatisch aktualisiert
+
+---
+
+### **Phase 2: Datenanreicherung (AI-Loop)**
+
+7. **Get row(s) in sheet** (Google Sheets)
+   - Holt frisch geschriebene Daten zurück
+   - Prüft Status der einzelnen Einträge
+   - Identifiziert Einträge die noch angereichert werden müssen
+
+8. **IF** (Conditional Check)
+   - Prüft ob das Feld "Branche" leer ist
+   - Nur leere Einträge werden weiterverarbeitet
+   - Verhindert doppelte AI-Verarbeitung (Kosten-Optimierung)
+
+9. **Loop Over Items** (Split in Batches)
+   - **Batch Size: 5** Items pro Durchlauf
+   - Begrenzt Token-Verbrauch bei ChatGPT
+   - Verhindert Rate-Limiting und Timeouts
+   - Loop läuft bis alle Items verarbeitet sind
+
+10. **Research Data** (AI Agent)
+    - **OpenAI Chat Model** (GPT-4 oder GPT-4o)
+    - **Structured Output Parser** für konsistente Datenstruktur
+    - Extrahiert aus LinkedIn-Profil + Websuche:
+      - ✉️ E-Mail-Adresse
+      - 📞 Telefonnummer
+      - 🌐 Website
+      - 🏢 Branche/Industry
+      - 📍 Vollständige Adresse (Straße, PLZ, Ort, Land)
+    - **Settings:**
+      - Temperature: **0.0** (maximale Konsistenz)
+      - top_p: **0.1** (deterministisch)
+      - Execute Once: **OFF** (verarbeitet jedes Item einzeln)
+
+11. **Fill Sheet Ergebnisse** (Google Sheets)
+    - Schreibt angereicherte Daten zurück
+    - Verwendet ID als Matching-Key für Updates
+    - Felder: Vorname, Nachname, Straße, PLZ, Ort, Land, Mail, Telefon, Website, Branche
+
+12. **Update row index** (Google Sheets)
+    - Markiert verarbeitete Einträge
+    - Verhindert Re-Processing im nächsten Loop
+    - Aktualisiert Status-Felder
+
+13. **Loop zurück** zu Step 9
+    - Verarbeitet nächsten Batch (5 Items)
+    - Wiederholt bis alle Items durch sind
+    - Automatische Loop-Beendigung wenn keine Items mehr
+
+---
+
+### **Phase 3: Abschluss**
+
+14. **Finish Dataset** (DataTable)
+    - Markiert den ursprünglichen Job als `finished = true`
+    - Verhindert Re-Processing bei erneutem Workflow-Start
+    - Aktualisiert Statistiken/Timestamps
+
+---
+
+## 📊 Datenfluss
+
+```
+Eingabe (DataTable "scraper"):
+├─ title: "Steuerberater"
+├─ city: "München"  
+├─ ready: true
+└─ finished: false
+
+    ↓ [Google Search]
+
+Zwischen-Output (Sheet "Leads-N8N-2"):
+├─ ID: "linkedin.com/in/max-mustermann"
+├─ Titel: "Max Mustermann - Steuerberater München"
+├─ Vorname: "Max"
+├─ Nachname: "Mustermann"
+└─ Branche: [LEER] ← Trigger für AI
+
+    ↓ [AI Research]
+
+End-Output (Sheet "Leads-N8N-Ergebnisse"):
+├─ ID: "linkedin.com/in/max-mustermann"
+├─ Vorname: "Max"
+├─ Nachname: "Mustermann"
+├─ Straße: "Maximilianstraße 15"
+├─ PLZ: "80539"
+├─ Ort: "München"
+├─ Land: "Deutschland"
+├─ Mail: "max@stb-mustermann.de"
+├─ Telefon: "+49 89 123456"
+├─ Website: "www.stb-mustermann.de"
+└─ Branche: "Steuerberatung"
+```
+
+---
+
+## ⚙️ Technische Details
+
+### **Performance:**
+- **Verarbeitungsgeschwindigkeit:** ~5-10 Items pro Minute
+- **Batch-Größe:** 5 Items (Token-Optimierung)
+- **Durchsatz:** ~80 Leads in 30-45 Minuten
+
+### **Token-Verbrauch (geschätzt):**
+- Pro Item: ~700 Tokens (Input + Output)
+- Pro Batch (5 Items): ~3.500 Tokens
+- Gesamt (80 Items): ~56.000 Tokens
+
+### **Kosten (GPT-4o):**
+- Input: ~$0.28 (56k Tokens × $5/1M)
+- Output: ~$0.84 (56k Tokens × $15/1M)
+- **Total: ~$1.12 pro Workflow-Durchlauf**
+
+### **Error Handling:**
+- Retry on Fail: Aktiviert im Research Data Node
+- Loop-basierte Verarbeitung: Fehler stoppen nicht den gesamten Workflow
+- Duplikat-Prevention: ID-basiertes Matching verhindert doppelte Einträge
+
+---
+
+## 🎯 Use Cases
+
+**Ideal für:**
+- 🔍 Lead-Generierung für B2B-Sales
+- 📊 Marktforschung & Wettbewerbsanalyse
+- 🎯 Account-Based Marketing (ABM)
+- 📈 CRM-Datenanreicherung
+- 🤝 Recruiting & Headhunting
+
+**Branchen:**
+- Steuerberatung
+- Unternehmensberatung
+- Rechtsberatung
+- IT-Dienstleistungen
+- Finanzdienstleistungen
+
+---
+
+## 🔒 Datenschutz & Compliance
+
+**Wichtig:** 
+- Daten stammen aus **öffentlich zugänglichen LinkedIn-Profilen**
+- Keine Speicherung sensibler persönlicher Daten
+- DSGVO-konform bei korrekter Verwendung (Opt-out respektieren)
+- Nur geschäftliche Kontaktdaten werden verarbeitet
+
+---
+
+## 🚀 Vorteile
+
+✅ **Skalierbar:** Verarbeitet hunderte Leads automatisch  
+✅ **Kosteneffizient:** ~$0.014 pro Lead (bei GPT-4o)  
+✅ **Konsistent:** Temperature 0.0 = reproduzierbare Ergebnisse  
+✅ **Robust:** Loop-basiert, fehlertoleranz durch Batch-Verarbeitung  
+✅ **Wartbar:** Modularer Aufbau, einfach erweiterbar  
+
+---
+
+**Version:** 3.0 (Stable)  
+**Erstellt:** Januar 2026  
+**Status:** Production-Ready ✅