From 3a304602dc4c0733494e80cf9cbbd3aaf11bf8df Mon Sep 17 00:00:00 2001 From: Floke Date: Sun, 8 Mar 2026 12:27:07 +0000 Subject: [PATCH] [30388f42] docs: Restore full legacy content and structure project documentation --- ARCHIVE_legacy_scripts/README_LEGACY.md | 252 +++++++++++++++++++++++- 1 file changed, 248 insertions(+), 4 deletions(-) diff --git a/ARCHIVE_legacy_scripts/README_LEGACY.md b/ARCHIVE_legacy_scripts/README_LEGACY.md index c46b267a..8018bb47 100644 --- a/ARCHIVE_legacy_scripts/README_LEGACY.md +++ b/ARCHIVE_legacy_scripts/README_LEGACY.md @@ -1,6 +1,35 @@ # Legacy Dokumentation: Monolithische Python-Skripte (v2.x) -**⚠️ HINWEIS:** Diese Dokumentation bezieht sich auf die alte, skript-basierte Architektur (`brancheneinstufung2.py`), die weitgehend durch die neue Docker-Microservice-Architektur (GTM Engine) abgelöst wurde. Sie dient hier nur noch als Referenz. +**⚠️ HINWEIS:** Diese Dokumentation ist ein vollständiges Archiv der ursprünglichen `readme.md`. Sie enthält wertvolle Informationen über die Entstehungsgeschichte, spezifische Bugfixes (z.B. Metric Parser) und die alte Architektur. Teile davon sind in den neuen Microservices aufgegangen, aber die Logik-Beschreibungen bleiben als Referenz relevant. + +--- + +## 💎 Historische Lessons Learned & Best Practices (Kritisch) + +Diese Erkenntnisse stammen aus der harten Debugging-Phase (Jan/Feb 2026) und sind essenziell für das Verständnis der Parser-Logik im `company-explorer`. + +1. **Numeric Extraction (German Locale):** + * **Problem:** "1.005 Mitarbeiter" wurde als "1" extrahiert (Punkt als Dezimaltrenner). + * **Lösung:** Kontext-Logik. Punkt gefolgt von exakt 3 Ziffern (ohne Komma) = Tausendertrennzeichen. + * **Revenue:** Bei Umsatz (`is_revenue=True`) werden Punkte meist als Dezimalzeichen gewertet (z.B. "375.6 Mio"), außer es ist eindeutig. + +2. **The Wolfra/Greilmeier/Erding Fixes (Advanced Metric Parsing):** + * **Problem:** Einfache Regex scheitert an komplexen Sätzen mit Jahreszahlen oder Präfixen. + * **Solution (Hybrid Extraction):** + 1. **LLM Guidance:** LLM liefert `expected_value` (z.B. "8.000 m²"). + 2. **Robust Python Parser (`MetricParser`):** Reinigt `expected_value` und sucht intelligent im Text. + 3. **Specific Bug Fixes:** + - **Year-Suffix:** Entfernt angehängte Jahreszahlen (z.B. "802020" -> "80"). + - **Year-Prefix:** Ignoriert Jahreszahlen (1900-2100) als Metrik-Kandidaten. + - **Sentence Truncation:** Logik entfernt, die Sätze zu früh abschnitt. + +3. **LLM JSON Stability:** + * **Problem:** Markdown-Blöcke (` ```json `) zerstören `json.loads()`. + * **Solution:** Immer `clean_json_response` Helper nutzen. + +4. **Scraping Navigation:** + * **Problem:** Impressum oft nicht auf der Landingpage. + * **Solution:** 2-Hop Strategie (Root Domain + "Kontakt" Link Prüfung). --- @@ -400,9 +429,9 @@ Das Ziel ist es, die automatische und präzise Klassifizierung neuer, unbekannte ---- -## 7. Standalone-Werkzeuge (Legacy) +## 7. Standalone-Werkzeuge -Dieser Bereich enthält Skripte, die als eigenständige Werkzeuge für spezifische Aufgaben konzipiert waren. +Dieser Bereich enthält Skripte, die als eigenständige Werkzeuge für spezifische Aufgaben konzipiert sind. ### `company_deduplicator.py` (Duplikats-Check) @@ -414,9 +443,63 @@ Das Skript `company_deduplicator.py` (ehemals `duplicate_checker_old.py`) ist ei Es verwendet einen gewichteten, heuristischen Algorithmus, um Ähnlichkeiten zu bewerten und nutzt bekannte Unternehmenshierarchien (`Parent Account`), um Falsch-Positive zu reduzieren. +### Meeting Assistant (Transcription Tool) + +Ein lokaler Micro-Service zur Transkription und Analyse von Audio-Dateien (Meetings, Calls, Interviews). Nutzt Gemini 2.0 Flash für kostengünstige, hochqualitative Ergebnisse. + +* **Dokumentation:** [TRANSCRIPTION_TOOL.md](TRANSCRIPTION_TOOL.md) +* **Funktionen:** Upload (MP3/WAV), Automatisches Chunking (FFmpeg), Transkription mit Timestamps. +* **Zugriff:** Über das Dashboard `/tr/`. + +### `import_competitive_radar.py` (Competitor Import) + +#### Hauptfunktion +Dieses Skript dient dem einmaligen Import von Wettbewerbsanalyse-Daten aus einer JSON-Datei in die Notion-Datenbanken. Es liest eine spezifische JSON-Datei (`analysis_robo-planet.de-4.json`), die die Ergebnisse einer externen Analyse enthält, und legt die entsprechenden Einträge für Unternehmen, Produkte und deren Verknüpfungen in Notion an. Das Skript ist zustandsbewusst, d.h. es prüft vor dem Anlegen, ob ein Eintrag bereits existiert, um Duplikate zu vermeiden. + +#### Neue Features (Interne Deduplizierung) +- **Zwei-Modi-Betrieb:** Das Skript fragt beim Start interaktiv ab, ob ein externer Vergleich oder eine interne Deduplizierung durchgeführt werden soll. +- **Gruppierung & ID-Zuweisung:** Im internen Modus werden gefundene Duplikatspaare zu Clustern zusammengefasst (z.B. wenn A=B und B=C, dann ist A,B,C eine Gruppe). Jede Gruppe erhält eine eindeutige ID (z.B. `Dup_0001`), die in eine neue Spalte `Duplicate_ID` im `CRM_Accounts`-Sheet geschrieben wird. +- **Nutzung von Unternehmenshierarchien:** Das Skript liest die Spalte `Parent Account` aus dem `CRM_Accounts`-Sheet. Bekannte Eltern-Kind-Beziehungen werden automatisch von der Duplikatsprüfung ausgeschlossen, was die Genauigkeit erheblich verbessert. +- **Handlungsempfehlungen:** Findet das Skript eine Duplikatsgruppe, in der bei keinem der Mitglieder ein `Parent Account` gepflegt ist, wird dies in einer neuen Spalte `Duplicate_Hint` vermerkt. Dies dient als Hinweis, dass hier möglicherweise eine Hierarchie im CRM nachgepflegt werden sollte. + +#### Abhängigkeiten +- **`pandas`**: Zur Datenmanipulation und -analyse. +- **`thefuzz`**: Für Fuzzy-String-Vergleiche zur Bewertung der Namensähnlichkeit. +- **`gspread`, `oauth2client`**: Für die Interaktion mit der Google Sheets API. +- **Lokale Module**: + - `helpers.py`: Stellt Normalisierungsfunktionen (`normalize_company_name`, `simple_normalize_url`) und eine optionale Web-Suche (`serp_website_lookup`) bereit. + - `config.py`: Zentralisiert Konfigurationswerte und API-Schlüssel. + - `google_sheet_handler.py`: Kapselt die Logik für den Zugriff auf Google Sheets. + +#### Konfiguration +Die Logik des Skripts wird durch mehrere Konstanten am Anfang der Datei gesteuert: +- **Sheet-Namen**: `CRM_SHEET_NAME` und `MATCHING_SHEET_NAME`. +- **Score-Schwellenwerte**: `SCORE_THRESHOLD` (Standard: 80) und `SCORE_THRESHOLD_WEAK` (95), ein strengerer Wert für Treffer ohne starke Indikatoren wie Domain- oder Standortübereinstimmung. +- **Penalties**: `CITY_MISMATCH_PENALTY` (30) und `COUNTRY_MISMATCH_PENALTY` (40) werden vom Score abgezogen, wenn Standorte voneinander abweichen. +- **Prefiltering**: `PREFILTER_MIN_PARTIAL` (70) und `PREFILTER_LIMIT` (30) zur Vorauswahl potenzieller Kandidaten, um die Performance zu verbessern. +- **Stop-Wörter**: `STOP_TOKENS_BASE` und `CITY_TOKENS` (dynamisch generiert) enthalten Begriffe, die bei Namensvergleichen ignoriert werden, um die Signalqualität zu erhöhen. + +#### Ablauf-Logik (Gekürzt) +1. **Modus-Auswahl**: Das Skript fragt den Benutzer nach dem gewünschten Modus (Extern vs. Intern). +2. **Initialisierung & Daten laden**: Richtet das Logging ein und lädt die relevanten Google Sheets. Im internen Modus wird auch die `Parent Account`-Spalte geladen. +3. **Normalisierung & Index-Erstellung**: Unternehmensnamen, Domains, Orte und Parent Accounts werden standardisiert. Zur Optimierung der Suche werden "Blocking"-Indizes (z.B. für Domains und Namens-Tokens) erstellt. +4. **Matching-Prozess**: + - **Extern:** Jeder Eintrag aus `Matching_Accounts` wird mit Kandidaten aus `CRM_Accounts` verglichen. + - **Intern:** Jeder Eintrag aus `CRM_Accounts` wird mit nachfolgenden Kandidaten aus derselben Liste verglichen, wobei bekannte Hierarchien übersprungen werden. +5. **Scoring & Gruppierung**: Kandidatenpaare werden bewertet. Im internen Modus werden Paare über dem Schwellenwert zu Gruppen zusammengefasst. +6. **Daten zurückschreiben**: + - **Extern:** Die Ergebnisse (`Match`, `Score`) werden in das `Matching_Accounts`-Sheet geschrieben. + - **Intern:** Die `Duplicate_ID` und `Duplicate_Hint` werden in neue Spalten im `CRM_Accounts`-Sheet geschrieben. + +#### To-Dos & Nächste Schritte +- **Scoring-Schwellenwert erhöhen:** Der `SCORE_THRESHOLD` von 80 ist für die interne Deduplizierung zu niedrig und sollte auf 95 oder höher angehoben werden, um Falsch-Positive zu reduzieren. +- **Stop-Wort-Liste erweitern:** Die `STOP_TOKENS_BASE`-Liste um generische Branchenbegriffe wie 'energy', 'services', 'group', 'solutions' etc. erweitern. +- **Scoring-Logik anpassen:** Die Gewichtung sollte angepasst werden, sodass eine hohe Namensähnlichkeit in Kombination mit einem Standort-Match stärker bewertet wird. +- **Debugging-Log verbessern:** Die Log-Ausgabe für gefundene Paare sollte die komplette Scoring-Zusammensetzung ausgeben, um die Analyse von Ergebnissen zu erleithert. + ---- -## 8. Projekt-Fundament (Legacy) +## 8. Projekt-Fundament Diese Module stellen grundlegende Funktionen und Konfigurationen für das gesamte Projekt bereit. @@ -544,3 +627,164 @@ Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktio - **Zweck:** Überprüft, ob eine gegebene URL tatsächlich auf einen existierenden Wikipedia-Artikel verweist und nicht auf eine "Seite existiert nicht"-Seite. - **Input:** `url` (die zu prüfende Wikipedia-URL). - **Output:** `True`, wenn der Artikel existiert, andernfalls `False`. + +---- + +## 9. Konsolidierte Architektur & Web-Anwendungen (Historie v2.x) + +Um die verschiedenen Werkzeuge zugänglicher und wartbarer zu machen, wurden der **B2B Marketing Assistant** und das **Market Intelligence Tool** in einer einzigen, Docker-basierten Architektur konsolidiert. Diese neue Struktur bietet einen zentralen, passwortgeschützten Einstiegspunkt und optimiert sowohl die Entwicklung als auch den Betrieb. + +### Architektur im Überblick + +Die konsolidierte Lösung besteht aus fünf Haupt-Containern, die von `docker-compose.yml` gesteuert werden: + +1. **Proxy (Nginx):** + * **Zentraler Einstiegspunkt:** Der Proxy lauscht auf Port `8090` und ist der einzige von außen erreichbare Punkt. + * **Passwortschutz:** Sichert den gesamten Zugriff mit HTTP Basic Authentication (Benutzer: `admin`, Passwort: `gemini`). + * **Routing:** Leitet Anfragen an die richtigen Anwendungs-Container weiter: + * `/` -> Dashboard (Landingpage) + * `/b2b/` -> B2B Marketing Assistant + * `/market/` -> Market Intelligence Tool + * `/gtm/` -> GTM Architect + +2. **Dashboard:** + * Eine simple Nginx-Instanz, die eine statische HTML-Seite (`dashboard/index.html`) ausliefert. + * Diese Seite dient als Landingpage und verlinkt auf die drei untergeordneten Anwendungen. + +3. **B2B Marketing Assistant (`b2b-app`):** + * Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik enthält. + * Erreichbar über das Unterverzeichnis `/b2b/`. + +4. **Market Intelligence (`market-frontend` & `market-backend`):** + * Diese Anwendung bleibt in Frontend- und Backend-Container aufgeteilt, wird aber nun ebenfalls über den zentralen Proxy unter `/market/` geroutet. + +5. **GTM Architect (`gtm-app`):** + * Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik kapselt. + * Erreichbar über das Unterverzeichnis `/gtm/`. + +### Vorteile dieser Architektur + +- **Zentraler & Sicherer Zugriff:** Nur ein Port muss freigegeben werden, und der Zugang ist einheitlich geschützt. +- **Einfache Skalierbarkeit:** Die einzelnen Komponenten sind voneinander entkoppelt und können unabhängig voneinander aktualisiert werden. +- **Optimierte Builds:** Durch die Verwendung von `.dockerignore` und Python-Basis-Images werden die Build-Zeiten verkürzt und die Image-Größen reduziert. +- **Effiziente Entwicklung:** Die Python-Skripte (`*.py`) werden als Volumes eingebunden ("Sideloading"). Änderungen am Python-Code erfordern daher **keinen** kompletten Docker-Rebuild, sondern nur einen Neustart des Containers. + +### API-Authentifizierung (Company Explorer) + +Der `company-explorer` Dienst erfordert nun eine HTTP Basic Authentication für alle API-Endpunkte (`/api/*`). Dies dient dem internen Zugriffsschutz. + +Um den Dienst zu nutzen, müssen folgende Umgebungsvariablen in der `docker-compose.yml` (oder in einer `.env`-Datei, wenn diese konfiguriert ist) gesetzt werden: + +```yaml +services: + company-explorer: + # ... andere Konfigurationen ... + environment: + API_USER: "IhrBenutzername" # Legen Sie hier Ihren gewünschten Benutzernamen fest + API_PASSWORD: "IhrSicheresPasswort" # Legen Sie hier Ihr gewünschtes sicheres Passwort fest +``` + +Stellen Sie sicher, dass Sie diese Werte vor dem Start des `company-explorer` Dienstes festlegen. Nach dem Aktualisieren der `docker-compose.yml` müssen Sie den Dienst neu starten: + +```bash +docker-compose restart company-explorer +``` + +---- + +## 11. Market Intelligence: Funktionsweise v2.2 (Update Dez. 2025) + +Das "Market Intelligence Tool" wurde in Version 2.2 massiv überarbeitet, um robuster und präziser zu arbeiten. + +### Neue Features + +1. **Robuste Audit-Strategie (Graceful Fallback):** + * Bisher führten blockierte Webseiten (403 Forbidden, Timeouts) zum Abbruch der Analyse. + * **Neu:** Wenn der Scraper blockiert wird, schaltet das System automatisch in einen "Digital Footprint Mode". Es analysiert dann Snippets aus der Google-Suche (Tech-Stack-Spuren, Job-Postings, News), um trotzdem eine Bewertung abzugeben. Der Status wird transparent als "Website Access Denied - Relying on External Signals" gekennzeichnet. + +2. **Präzisere Lookalike-Suche:** + * Die KI wurde neu instruiert, strikt zwischen dem "Jäger" (Context/Hochgeladener Report) und der "Beute" (Referenzkunde/URL) zu unterscheiden. + * Die Suche nach "Lookalikes" basiert nun explizit auf dem Geschäftszweck des Referenzkunden, nicht auf dem Angebot des Nutzers. + +3. **Erweiterter Report:** + * Der finale Report enthält nun drei neue, strategische Sektionen: + * **Search Strategy ICP:** Detaillierte Beschreibung des idealen Kundenprofils basierend auf der Analyse. + * **Digital Signals:** Konkrete digitale Indikatoren (z.B. "Nutzt MS Teams", "Sucht Projektleiter"), auf die geachtet wurde. + * **Target Pages:** Eine Liste der wichtigsten Unterseiten auf der Ziel-Website (z.B. Karriere, Über uns) für die Recherche. + +### Technische Verbesserungen + +* **URL Auto-Fix:** URLs ohne `https://` werden automatisch korrigiert. +* **Modern User-Agent:** Der Scraper gibt sich als moderner Chrome-Browser aus, um Blockaden zu minimieren. +* **Frontend-Integration:** Die neuen Datenfelder werden nahtlos im React-Frontend und im Markdown-Export angezeigt. + +---- + +## 12. Infrastructure & Operations + +### DNS & Connectivity +Um eine stabile Erreichbarkeit der Dienste zu gewährleisten, wurde eine Docker-basierte DynDNS-Lösung implementiert. + +* **[DuckDNS & Monitoring Setup](duckdns_setup.md):** Dokumentation zur Einrichtung des `duckdns` Updaters und des `dns-monitor` Sidecars, um Verbindungsprobleme und Caching-Fehler zu beheben. + +---- + +## 13. Funktionsweise im Detail + +### Analyse-Tiefe der "Digital Signals" im Market Intelligence Tool + +Die Identifizierung von digitalen Signalen bei Zielunternehmen erfolgt über einen pragmatischen, zweistufigen Prozess, um ein Gleichgewicht zwischen analytischer Tiefe und Performance zu gewährleisten: + +1. **Vollständiges Parsen der Unternehmens-Homepage:** + * Die Haupt-URL des zu analysierenden Unternehmens wird einmalig vollständig gecrawlt. Der extrahierte Text (`homepage_text`) dient dem Sprachmodell als grundlegender Kontext, um das Geschäftsmodell und die Kernaussagen des Unternehmens zu verstehen. + +2. **Analyse von Suchergebnis-Snippets für Signale:** + * Für die gezielte Suche nach spezifischen Signalen (z.B. eingesetzte Konkurrenzprodukte, offene Stellen, strategische Initiativen) wird die SerpAPI (Google-Suche) genutzt. + * **Wichtig:** Die in den Suchergebnissen gefundenen Ziel-URLs werden **nicht** erneut besucht und geparst. Stattdessen werden ausschließlich der **Titel (`title`)** und der von der Suchmaschine generierte **Textschnipsel (`snippet`)** als "Beweismittel" (`evidence`) an das Sprachmodell übergeben. + * Dieser Ansatz ist ein bewusster Kompromiss: Er ist extrem schnell und kosteneffizient, da er aufwändiges Crawling vermeidet. Die Snippets sind in der Regel aussagekräftig genug, um das Vorhandensein eines Signals mit hoher Wahrscheinlichkeit zu validieren. + +### Zukünftige Erweiterung: Detaillierte Analyse von Stellenausschreibungen + +Als eine zukünftige, sehr wertvolle Erweiterung ist die detaillierte, automatisierte Analyse von Stellenausschreibungen vorgemerkt. + +* **Strategischer Mehrwert:** + * **Einblick in die Wirtschaftslage:** Die Art und Anzahl der offenen Stellen (z.B. Vertrieb vs. Entwicklung vs. Verwaltung) kann Aufschluss über die aktuelle Wachstums-, Konsolidierungs- oder Krisenphase eines Unternehmens geben. + * **IT-Landkarte & Tech-Stack:** Insbesondere IT-Stellenanzeigen sind eine Goldgrube für Technographic-Daten. Sie listen oft explizit die eingesetzten Programmiersprachen, Frameworks, Datenbanken, ERP-Systeme (z.B. SAP, D365) und Cloud-Anbieter auf. Dies erlaubt eine einzigartig detaillierte Erstellung der "IT-Landkarte" eines Zielunternehmens. +* **Herausforderung:** + * Der technische Aufwand für ein robustes System, das Karriereseiten findet, die verschiedenen Job-Portale parst und die relevanten Informationen extrahiert, ist immens. +* **Status:** + * Diese Erweiterung wird für eine spätere Entwicklungsphase vorgemerkt und sollte aufgrund der Komplexität in einem klar abgegrenzten, überschaubaren Rahmen umgesetzt werden. + + +---- + +## 14. Test-Übersicht & Qualitätssicherung + +Um die Stabilität und Korrektheit der automatisierten Prozesse zu gewährleisten, verfügt das Projekt über eine Reihe von automatisierten Tests, die in verschiedene Kategorien unterteilt sind. + +### A. SuperOffice Connector Tests +Diese Tests befinden sich im Ordner `connector-superoffice/tests/` und validieren die Kommunikation zwischen SuperOffice und dem Company Explorer. + +* **`test_e2e_flow.py`**: Der umfassendste Integrationstest. Er simuliert den gesamten Datenzyklus: + 1. Anlage eines Accounts in SuperOffice (Webhook-Simulation). + 2. Provisionierung im Company Explorer (CE). + 3. Automatisches Zurückschreiben der Branche (Vertical) nach SuperOffice. + 4. Anlage einer Person & Generierung personalisierter Marketing-Texte basierend auf Rolle und Branche. + 5. Simulation einer manuellen Branchenänderung im CRM inkl. Kaskaden-Update für alle zugehörigen Personen. +* **`test_client.py`**: Verifiziert die grundlegende Funktionalität des SuperOffice API-Clients (Authentifizierung, Token-Refresh, einfache GET/POST/PUT Operationen). + +### B. Company Explorer Backend Tests +Diese Tests befinden sich in `company-explorer/backend/tests/` und prüfen die internen Logik-Komponenten. + +* **`test_metric_parser.py`**: **Kritische Regressions-Tests** für die numerische Extraktion (deutsche Lokalisierung). Prüft komplexe Fälle wie: + * Tausender-Trennzeichen vs. Dezimalpunkte. + * Verkettete Zahlen und Jahre (z.B. "802020"). + * Ignorieren von Jahreszahlen als Kennzahlen. +* **`test_classification_service.py`**: Validiert die KI-basierte Einstufung von Unternehmen in Branchen-Verticals und die Bewertung des Automatisierungspotenzials. +* **`test_opener_logic.py`**: Prüft die Generierung der personalisierten Einleitungssätze (Openers) basierend auf Website-Scrapes und Branchen-Pains. + +### C. Infrastruktur & API Tests +Allgemeine Tests im Hauptverzeichnis zur Absicherung der Schnittstellen. + +* **`test_opener_api.py`**: Testet spezifisch den `/api/provision/superoffice-contact` Endpunkt des Company Explorers. +* **`test_core_functionality.py`**: Basis-Checks für die System-Integrität (Datenbank-Verbindung, API-Health). \ No newline at end of file