--- include_toc: true gitea: none --- # Projekt: Automatisierte Unternehmensbewertung & Lead-Generierung v2.2.1 ## 1. Projektübersicht & Architektur Dieses Projekt ist eine modulare "Lead Enrichment Factory", die darauf ausgelegt ist, Unternehmensdaten aus einem D365-CRM-System automatisiert anzureichern, zu analysieren und für Marketing- & Vertriebszwecke aufzubereiten. Die Architektur ist in mehrere, klar voneinander getrennte Funktionseinheiten gegliedert, die im Folgenden detailliert beschrieben werden. ## Architektur im Überblick ```text I. DIE STEUERUNGS-EBENE (API & Ausführung) └── app.py (Flask API Server, startet Jobs) └── brancheneinstufung2.py (Der zentrale Orchestrator / Kommandozeile) II. DIE KERN-PRODUKTIONSLINIE (Datenanreicherung) └── data_processor.py (Der "Motor", führt die Arbeit aus) ├── google_sheet_handler.py (Spezialist für Google Sheets) ├── wikipedia_scraper.py (Spezialist für Wikipedia-Daten) ├── sync_manager.py (Spezialist für den D365-Abgleich) └── helpers.py (Der "Werkzeugkasten" für alle) III. DIE MARKETING-PRODUKTIONSLINIE (Content-Erstellung) └── generate_marketing_text.py (Erstellt E-Mail-Texte) └── INPUT: marketing_wissen_final.yaml (Die Wissensbasis) IV. DIE WISSENSBASIS-FABRIK (ETL-Pipelines zur Erstellung der Wissensbasis) ├── build_knowledge_base.py (Baut die Marketing-KB aus der config.py) ├── expand_knowledge_base.py (Erweitert die Marketing-KB) ├── extract_insights.py (Baut die Marketing-KB aus Word-Dokumenten) └── generate_knowledge_base.py (Erstellt einen Entwurf für die Marketing-KB) V. DAS KLASSIFIZIERUNGS-SYSTEM (Job-Titel-Analyse) ├── contact_grouping.py (Klassifiziert Job-Titel) └── knowledge_base_builder.py (Baut die Wissensbasis FÜR die Klassifizierung) VI. DAS STANDALONE-WERKZEUG └── duplicate_checker_old.py (Eigenständiger Duplikats-Check) VII. DAS FUNDAMENT └── config.py (Einstellungen & Konstanten für ALLE) ``` --- ## 2. Steuerung & Ausführung (Control & Execution) Diese Ebene bildet die Schnittstelle zur Außenwelt und startet die verschiedenen Prozesse. ### `app.py` (API Server) #### Hauptfunktion Das Modul `app.py` implementiert eine einfache Flask-Webanwendung, die als API-Endpunkt für das gesamte System dient. Es ermöglicht das Starten von langlaufenden Skripten (wie dem Duplikats-Check oder der Branchen-Neuklassifizierung) als asynchrone Hintergrundprozesse. Die Anwendung verwaltet diese Prozesse über eindeutige Job-IDs und bietet Endpunkte zum Starten von Aktionen und zum Abrufen des Status dieser Jobs. Dies ermöglicht eine lose Kopplung und die Steuerung des Systems durch externe Aufrufe, z.B. aus einem Frontend oder einem anderen Service. #### Methodenbeschreibung - `status_check()`: Ein einfacher `/status`-Endpunkt (GET), der eine "ok"-Nachricht zurückgibt. Dient als Health-Check, um zu überprüfen, ob die Flask-Anwendung läuft. - `setup_ngrok()`: Eine Hilfsfunktion, die einen `ngrok`-Tunnel startet, um den lokalen Flask-Server über eine öffentliche URL erreichbar zu machen. Dies ist nützlich für das Testen und die Demonstration in Umgebungen ohne öffentliche IP. - `run_script()`: Der Hauptendpunkt `/run-script` (POST), der eine Aktion entgegennimmt (z.B. "run_duplicate_check"). Basierend auf der Aktion wird das entsprechende Python-Skript (`duplicate_checker.py`, `brancheneinstufung2.py`, etc.) als separater Hintergrundprozess gestartet. Für jeden gestarteten Prozess wird eine eindeutige Job-ID generiert und eine initiale Statusdatei im `job_status`-Verzeichnis erstellt. - `get_status()`: Ein `/get-status`-Endpunkt (GET), der den Inhalt aller im `job_status`-Verzeichnis gespeicherten JSON-Dateien ausliest. Dies ermöglicht es, den Fortschritt und den aktuellen Status aller gestarteten und abgeschlossenen Jobs abzufragen. Die Ergebnisse werden als JSON-Array zurückgegeben, wobei die neuesten Jobs zuerst aufgeführt sind. ### `brancheneinstufung2.py` (Orchestrator / Kommandozeile) #### Hauptfunktion Das Skript `brancheneinstufung2.py` ist der zentrale Einstiegspunkt und Orchestrator für die Datenanreicherungs-Pipeline. Es dient nicht der direkten Implementierung der Verarbeitungslogik, sondern dem Parsen von Kommandozeilen-Argumenten, der Initialisierung von Handler-Klassen (`GoogleSheetHandler`, `WikipediaScraper`, `DataProcessor`, `SyncManager`) und dem Starten des vom Benutzer ausgewählten Verarbeitungsmodus. Das Skript ist hochgradig modular und delegiert die eigentliche Arbeit an die `DataProcessor`-Klasse. #### Wichtige Funktionen/Methoden Die Logik des Skripts ist primär in der `main()`-Funktion enthalten und lässt sich in folgende Schritte unterteilen: 1. **Argumenten-Parsing**: Mittels `argparse` wird die Kommandozeile ausgewertet. Der wichtigste Parameter ist `--mode`, der den auszuführenden Prozess festlegt (z.B. `sync`, `full_run`, `reeval`, `predict_technicians`). 2. **Interaktiver Modus**: Wird kein `--mode` übergeben, startet ein interaktiver Modus, in dem der Benutzer aus einer Liste aller verfügbaren Modi auswählen kann. 3. **Initialisierung**: Basierend auf dem gewählten Modus werden die notwendigen Klassen instanziiert. Für die meisten Anreicherungs-Modi wird ein `DataProcessor`-Objekt erstellt. 4. **Modus-Dispatching**: Eine `if/elif/else`-Struktur leitet die Ausführung an die passende Methode weiter (z.B. `sync`, `full_run`, `reeval`, dynamische Aufrufe von `DataProcessor`-Methoden). 5. **Fehlerbehandlung und Logging**: Das gesamte Skript ist von einem `try...except...finally`-Block umschlossen, der Fehler abfängt und protokolliert. --- ## 3. Kern-Produktionslinie: Datenanreicherung Dies ist das Herzstück der Fabrik, in dem die eigentliche Anreicherung der Unternehmensdaten stattfindet. ### `data_processor.py` (Der "Motor") #### Hauptfunktion Die Klasse `DataProcessor` ist das Herzstück der Anreicherungslogik und enthält alle Methoden zur schrittweisen Verarbeitung von Unternehmensdaten. Sie wird vom Orchestrator (`brancheneinstufung2.py`) aufgerufen und nutzt verschiedene Spezialisten-Module, um ihre Aufgaben zu erfüllen. #### Methodenbeschreibung - `setup()`: Initialisiert den `DataProcessor`, lädt das Branchenschema und das ML-Modell. - `process_rows_sequentially(...)`: Führt den vollständigen, schrittweisen Anreicherungsprozess für einen definierten Bereich von Zeilen aus. - `process_reevaluation_rows(...)`: Führt den Anreicherungsprozess für Zeilen aus, die manuell für eine Neubewertung markiert wurden. - `process_website_scraping(...)`: Führt einen Batch-Prozess ausschließlich für das Scrapen von Websites durch. - `process_summarize_website(...)`: Führt einen Batch-Prozess zur Zusammenfassung von Website-Rohtexten mittels KI durch. - `process_branch_batch(...)` / `reclassify_all_branches(...)`: Führt eine (Neu-)Bewertung der Branchenzugehörigkeit im Batch-Verfahren durch. - `process_wiki_verify(...)`: Verifiziert in einem Batch-Prozess, ob ein Wikipedia-Artikel thematisch zum Unternehmen passt. - `process_find_wiki_serp(...)`: Sucht über eine Google-Suche nach einem passenden Wikipedia-Artikel für große Unternehmen. - `process_contact_search(...)`: Führt eine Suche nach LinkedIn-Kontakten für bestimmte Positionen durch. - `train_technician_model()`: Trainiert ein Machine-Learning-Modell zur Vorhersage von Servicetechniker-Anzahlen. - `process_predict_technicians(...)`: Wendet das trainierte ML-Modell auf neue Zeilen an. ### Spezialisten-Module #### `google_sheet_handler.py` (Spezialist für Google Sheets) ##### Hauptfunktion Das Modul `google_sheet_handler.py` dient als zentraler Wrapper für sämtliche Interaktionen mit dem Google Sheet. Es abstrahiert die Komplexität der `gspread` API und stellt eine robuste, wiederverwendbare Schnittstelle bereit. ##### Methodenbeschreibung - `__init__(self, sheet_url=None)`: Initialisiert den Handler. - `load_data(self)`: Lädt den gesamten Inhalt des Haupt-Arbeitsblatts in den internen Speicher. - `get_sheet_as_dataframe(self, sheet_name)`: Gibt ein spezifisches Arbeitsblatt als Pandas DataFrame zurück. - `append_rows(self, sheet_name, values)`: Fügt neue Zeilen am Ende eines Arbeitsblatts an. - `clear_and_write_data(self, sheet_name, data)`: Löscht ein Arbeitsblatt und schreibt neue Daten hinein. - `batch_update_cells(self, update_data)`: Führt eine performante Stapelverarbeitung von Zell-Updates durch. #### `wikipedia_scraper.py` (Spezialist für Wikipedia) ##### Hauptfunktion Das Modul `wikipedia_scraper.py` kapselt alle Interaktionen mit Wikipedia. Seine Hauptaufgabe ist es, den relevantesten Artikel zu finden, zu validieren und strukturierte Daten daraus zu extrahieren. ##### Methodenbeschreibung - `__init__(self, user_agent=None)`: Initialisiert den Scraper. - `serp_wikipedia_lookup(self, company_name, lang='de')`: Nutzt die SerpAPI, um eine Google-Suche nach dem Wikipedia-Artikel durchzuführen. - `search_company_article(self, company_name, ...)`: Orchestriert den gesamten Such- und Validierungsprozess. - `_validate_article(self, page, company_name, ...)`: Führt eine faktenbasierte Überprüfung eines Artikels durch. - `extract_company_data(self, url_or_page)`: Die zentrale Extraktionsmethode, die strukturierte Daten aus der Infobox und dem Text parst. - `_extract_infobox_value(self, soup, target)`: Interne Hilfsmethode zur gezielten Suche in der Infobox. - `_parse_sitz_string_detailed(self, raw_sitz_string_input)`: Spezialisierte Hilfsmethode, um Stadt und Land aus dem Sitz-String zu extrahieren. #### `sync_manager.py` (Spezialist für D365-Abgleich) ##### Hauptfunktion Das Modul `sync_manager.py` ist für den robusten und intelligenten Datenabgleich zwischen einem D365 Excel-Export und dem Google Sheet verantwortlich. Es implementiert einen "Full-Sync"-Mechanismus. ##### Methodenbeschreibung - `__init__(self, sheet_handler, d365_export_path)`: Initialisiert den Manager mit Spaltenzuordnungen und Konfliktlösungsregeln. - `_load_data(self)`: Lädt und bereitet die Daten aus beiden Quellen für den Abgleich vor. - `run_sync(self)`: Orchestriert den gesamten Synchronisationsprozess und führt die Änderungen aus. - `debug_sync(self, debug_id=None)`: Bietet einen Debug-Modus zur Tiefenanalyse einzelner Datensätze. - `simulate_sync(self, debug_id=None)`: Führt eine "Trockenlauf"-Simulation des Syncs durch, ohne Daten zu ändern. --- ## 4. Marketing-Produktionslinie: Content-Erstellung Diese Produktionslinie nutzt die angereicherten Daten, um direkt verwertbaren Marketing-Content zu erstellen. ### `generate_marketing_text.py` (Marketing Text Engine) #### Hauptfunktion Das Modul `generate_marketing_text.py` ist eine spezialisierte Engine zur automatischen Erstellung von hochgradig personalisierten Marketing-Texten. Es kombiniert eine strukturierte Wissensbasis (`marketing_wissen_final.yaml`) mit der Leistungsfähigkeit eines LLM. #### Methodenbeschreibung - `call_openai_with_retry(...)`: Robuste Wrapper-Funktion für OpenAI-API-Aufrufe. - `build_prompt(...)`: Baut dynamisch den "Master-Prompt" für die KI zusammen, inklusive Pain Points und Referenzkunden. - `main(specific_branch=None)`: Die Haupt-Orchestrierungsfunktion, die bestehende Texte lädt, neue Kombinationen identifiziert, Texte generiert und die Ergebnisse in einem Batch an das Google Sheet anhängt. --- ## 5. ETL-Pipeline: Erstellung der Marketing-Wissensbasis Dieser Bereich enthält alle Skripte, die als ETL-Pipelines (Extract, Transform, Load) dienen, um die zentrale Wissensbasis (`marketing_wissen.yaml`) aus verschiedenen Quellen zu erstellen und zu pflegen. ### `build_knowledge_base.py` Erstellt eine umfassende Wissensbasis, indem es die in `config.py` definierten Brancheninformationen nutzt, um mittels KI für jede Branche ein detailliertes Dossier zu erstellen und daraus strukturierte Daten zu extrahieren. ### `expand_knowledge_base.py` Dient dazu, eine bestehende Wissensbasis gezielt zu erweitern, indem es fehlende Branchen aus der `config.py` identifiziert und die entsprechenden Einträge generiert. ### `extract_insights.py` Ein Werkzeug zur automatisierten Erstellung einer Wissensbasis aus unstrukturierten Word-Dokumenten (`.docx`). ### `generate_knowledge_base.py` Ein KI-gestütztes Skript zur Erstellung eines ersten Entwurfs für eine Marketing-Wissensbasis, das Branchen-Pain-Points und den Fokus von Ansprechpartner-Positionen generiert. --- ## 6. Sub-System: Kontakt-Klassifizierung Dies ist ein eigenständiges System innerhalb des Projekts, das sich ausschließlich mit der Analyse und Kategorisierung von Job-Titeln befasst. ### `contact_grouping.py` (Klassifizierer) #### Hauptfunktion Dieses Modul ist für die automatische Klassifizierung von Jobtiteln in vordefinierte Abteilungen zuständig. Es nutzt eine mehrstufige Logik aus regelbasierten Mappings und KI-gestützter Klassifizierung. #### Methodenbeschreibung - `load_knowledge_base(self)`: Lädt die spezifische Wissensbasis für die Jobtitel-Zuordnung. - `_find_best_match(self, job_title, company_branch)`: Die Kernlogik für die regelbasierte Zuordnung. - `_get_ai_classification(self, contacts_to_classify)`: Sendet unklassifizierte Titel zur KI-basierten Klassifizierung. - `_append_learnings_to_source(...)`: Erweitert die Wissensbasis kontinuierlich mit neuen KI-Erkenntnissen. - `process_contacts(self)`: Die Hauptmethode, die den gesamten Klassifizierungsprozess steuert. ### `knowledge_base_builder.py` (Wissensbasis-Ersteller für Klassifizierung) #### Hauptfunktion Dieses Modul ist dafür verantwortlich, die spezifische Wissensbasis für die Jobtitel-Klassifizierung zu erstellen. Es generiert ein exaktes Mapping (`exact_match_map.json`) und Keyword-Regeln (`keyword_rules.json`) aus einer Liste von Beispielen. --- ## 7. Standalone-Werkzeuge Dieser Bereich enthält Skripte, die als eigenständige Werkzeuge für spezifische Aufgaben konzipiert sind. ### `duplicate_checker_old.py` (Duplikats-Check) #### Hauptfunktion Das Skript `duplicate_checker_old.py` ist ein spezialisiertes Werkzeug zur Identifizierung von potenziellen Duplikaten zwischen zwei Unternehmenslisten in Google Sheets. Es verwendet einen gewichteten, heuristischen Algorithmus, um den wahrscheinlichsten Treffer zu finden und zu bewerten. #### Ablauf-Logik 1. **Initialisierung & Daten laden**: Richtet Logging ein und lädt die Daten aus den beiden Google Sheets. 2. **Normalisierung & Index-Erstellung**: Standardisiert Unternehmensnamen und erstellt Indizes zur Optimierung der Suche. 3. **Iteratives Matching**: Durchläuft jeden Datensatz der Matching-Liste, wählt eine kleine, relevante Untergruppe von Kandidaten aus und berechnet einen Ähnlichkeits-Score. 4. **Ergebnis-Aggregation & Rückschreiben**: Sammelt die besten Treffer und schreibt die Ergebnisse zurück in das Google Sheet. --- ## 8. Projekt-Fundament Diese Module stellen grundlegende Funktionen und Konfigurationen für das gesamte Projekt bereit. ### `config.py` (Zentrale Konfiguration) #### Hauptfunktion Dient als zentrale Konfigurationsdatei für das gesamte Projekt. Es bündelt alle globalen Einstellungen, Dateipfade, API-Schlüssel-Pfade, Schwellenwerte und Mappings. #### Methodenbeschreibung - `normalize_for_mapping(text)`: Eine interne Hilfsfunktion zur aggressiven Normalisierung von Strings. - `Config` Klasse: Enthält statische Attribute für Version, URLs, Timeouts, Schwellenwerte, Batch-Größen, Mappings und API-Schlüssel-Pfade. Bietet Methoden zum Laden der API-Schlüssel. - Globale Konstanten: `COLUMN_ORDER` und `COLUMN_MAP` definieren die exakte Struktur des Google Sheets. ### `helpers.py` (Globaler Werkzeugkasten) #### Hauptfunktion Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktionen, die in verschiedenen Modulen des Projekts verwendet werden. #### Methodenbeschreibung (Auszug) - **Decorators:** `retry_on_failure(func)` für robuste API-Aufrufe mit exponentiellem Backoff. - **Logging & Token Counting:** `token_count(...)`, `create_log_filename(...)`. - **Text-, String- & URL-Utilities:** `simple_normalize_url(...)`, `normalize_company_name(...)`, `extract_numeric_value(...)`, etc. - **API Wrappers & Externe Dienste:** `call_openai_chat(...)`, `summarize_website_content(...)`, `serp_website_lookup(...)`, etc. - **Website Scraping & Validierung:** `get_website_raw(...)`, `is_valid_wikipedia_article_url(...)`.