Brancheneinstufung2/company-explorer/MIGRATION_PLAN.md

Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.7.4)

Kontext: Neuanfang für die Branche Robotik & Facility Management. Ziel: Ablösung von Google Sheets/CLI durch eine Web-App ("Company Explorer") mit SQLite-Backend.

1. Strategische Neuausrichtung

Bereich	Alt (Legacy)	Neu (Robotics Edition)
Daten-Basis	Google Sheets	SQLite (Lokal, performant, filterbar).
Ziel-Daten	Allgemein / Kundenservice	Quantifizierbares Potenzial (z.B. 4500m² Fläche, 120 Betten).
Branchen	KI-Vorschlag (Freitext)	Strict Mode: Mapping auf definierte Notion-Liste (z.B. "Hotellerie", "Automotive").
Bewertung	0-100 Score (Vage)	Data-Driven: Rohwert (Scraper/Search) -> Standardisierung (Formel) -> Potenzial.
Analytics	Techniker-ML-Modell	Deaktiviert. Fokus auf harte Fakten.
Operations	D365 Sync (Broken)	Excel-Import & Deduplizierung. Fokus auf Matching externer Listen gegen Bestand.

2. Architektur & Komponenten-Mapping

Das System wird in company-explorer/ neu aufgebaut. Wir lösen Abhängigkeiten zur Root helpers.py auf.

A. Core Backend (backend/)

Komponente	Aufgabe & Neue Logik	Prio
Database	Ersetzt GoogleSheetHandler. Speichert Firmen & "Enrichment Blobs".	1
Importer	Ersetzt SyncManager. Importiert Excel-Dumps (CRM) und Event-Listen.	1
Deduplicator	Ersetzt company_deduplicator.py. Kern-Feature: Checkt Event-Listen gegen DB. Muss "intelligent" matchen (Name + Ort + Web).	1
Scraper (Base)	Extrahiert Text von Websites. Basis für alle Analysen.	1
Classification Service	NEU (v0.7.0). Zweistufige Logik: 1. Strict Industry Classification. 2. Metric Extraction Cascade (Web -> Wiki -> SerpAPI).	1
Marketing Engine	Ersetzt generate_marketing_text.py. Nutzt neue marketing_wissen_robotics.yaml.	3

Identifizierte Hauptdatei: company-explorer/backend/app.py

B. Frontend (frontend/) - React

• View 1: Der "Explorer": DataGrid aller Firmen. Filterbar nach "Roboter-Potential" und Status.
• View 2: Der "Inspector": Detailansicht einer Firma. Zeigt gefundene Signale ("Hat SPA Bereich"). Manuelle Korrektur-Möglichkeit.
  • Identifizierte Komponente: company-explorer/frontend/src/components/Inspector.tsx
• View 3: "List Matcher": Upload einer Excel-Liste -> Anzeige von Duplikaten -> Button "Neue importieren".
• View 4: "Settings": Konfiguration von Branchen, Rollen und Robotik-Logik.
  • Frontend "Settings" Komponente: company-explorer/frontend/src/components/RoboticsSettings.tsx

C. Architekturmuster für die Client-Integration

Um externen Diensten (wie der lead-engine) eine einfache und robuste Anbindung an den company-explorer zu ermöglichen, wurde ein standardisiertes Client-Connector-Muster implementiert.

Komponente	Aufgabe & Neue Logik
company_explorer_connector.py	NEU: Ein zentrales Python-Skript, das als "offizieller" Client-Wrapper für die API des Company Explorers dient. Es kapselt die Komplexität der asynchronen Enrichment-Prozesse.
handle_company_workflow()	Die Kernfunktion des Connectors. Sie implementiert den vollständigen "Find-or-Create-and-Enrich"-Workflow: 1. Prüfen: Stellt fest, ob ein Unternehmen bereits existiert. 2. Erstellen: Legt das Unternehmen an, falls es neu ist. 3. Anstoßen: Startet den asynchronen discover-Prozess. 4. Warten (Polling): Überwacht den Status des Unternehmens, bis eine Website gefunden wurde. 5. Analysieren: Startet den asynchronen analyze-Prozess. Vorteil: Bietet dem aufrufenden Dienst eine einfache, quasi-synchrone Schnittstelle und stellt sicher, dass die Prozessschritte in der korrekten Reihenfolge ausgeführt werden.

3. Umgang mit Shared Code (helpers.py & Co.)

Wir kapseln das neue Projekt vollständig ab ("Fork & Clean").

• Quelle: helpers.py (Root)
• Ziel: company-explorer/backend/lib/core_utils.py
• Aktion: Wir kopieren nur relevante Teile und ergänzen sie (z.B. safe_eval_math, run_serp_search).

4. Datenstruktur (SQLite Schema)

Tabelle companies (Stammdaten & Analyse)

• id (PK)
• name (String)
• website (String)
• crm_id (String, nullable - Link zum D365)
• industry_crm (String - Die "erlaubte" Branche aus Notion)
• city (String)
• country (String - Standard: "DE" oder aus Impressum)
• status (Enum: NEW, IMPORTED, ENRICHED, QUALIFIED)
• NEU (v0.7.0):
  • calculated_metric_name (String - z.B. "Anzahl Betten")
  • calculated_metric_value (Float - z.B. 180)
  • calculated_metric_unit (String - z.B. "Betten")
  • standardized_metric_value (Float - z.B. 4500)
  • standardized_metric_unit (String - z.B. "m²")
  • metric_source (String - "website", "wikipedia", "serpapi")

Tabelle signals (Deprecated)

• Veraltet ab v0.7.0. Wird durch quantitative Metriken in companies ersetzt.

Tabelle contacts (Ansprechpartner)

• id (PK)
• account_id (FK -> companies.id)
• gender, title, first_name, last_name, email
• job_title (Visitenkarte)
• role (Standardisierte Rolle: "Operativer Entscheider", etc.)
• status (Marketing Status)

Tabelle industries (Branchen-Fokus - Synced from Notion)

• id (PK)
• notion_id (String, Unique)
• name (String - "Vertical" in Notion)
• description (Text - "Definition" in Notion)
• metric_type (String - "Metric Type")
• min_requirement (Float - "Min. Requirement")
• whale_threshold (Float - "Whale Threshold")
• proxy_factor (Float - "Proxy Factor")
• scraper_search_term (String - "Scraper Search Term")
• scraper_keywords (Text - "Scraper Keywords")
• standardization_logic (String - "Standardization Logic")

Tabelle job_role_mappings (Rollen-Logik)

• id (PK)
• pattern (String - Regex für Jobtitles)
• role (String - Zielrolle)

7. Historie & Fixes (Jan 2026)

*   **[CRITICAL] v0.7.4: Service Restoration & Logic Fix (Jan 24, 2026)**
*   **[STABILITY] v0.7.3: Hardening Metric Parser & Regression Testing (Jan 23, 2026)**
*   **[STABILITY] v0.7.2: Robust Metric Parsing (Jan 23, 2026)**
*   **[STABILITY] v0.7.1: AI Robustness & UI Fixes (Jan 21, 2026)**
*   **[MAJOR] v0.7.0: Quantitative Potential Analysis (Jan 20, 2026)**
*   **[UPGRADE] v0.6.x: Notion Integration & UI Improvements**

14. Upgrade v2.0 (Feb 18, 2026): "Lead-Fabrik" Erweiterung

Dieses Upgrade transformiert den Company Explorer in das zentrale Gehirn der Lead-Generierung.

14.1 Detaillierte Datenmodell-Erweiterung

Tabelle: companies

Um Bestandsdaten sauber von KI-Ergebnissen zu trennen, wurden folgende Spalten hinzugefügt:

• crm_name (TEXT): Name des Unternehmens im CRM.
• crm_website (TEXT): Website-URL im CRM.
• crm_address (TEXT): Adresse im CRM (Straße, PLZ, Stadt).
• crm_vat (TEXT): Umsatzsteuer-ID im CRM.
• confidence_score (FLOAT): Gesamt-Konfidenz der KI-Analyse (0.0 - 1.0).
• data_mismatch_score (FLOAT): Grad der Abweichung zwischen CRM- und KI-Daten (0.0 = Match, 1.0 = kompletter Mismatch).
• website_scrape_status (TEXT): Status der Website-Analyse (PENDING, SUCCESS, FAILED, BLOCKED).
• wiki_search_status (TEXT): Status der Wikipedia-Suche (PENDING, FOUND, NOT_FOUND).

Tabelle: industries

Erweiterung um strategische Inhalte aus Notion (Voraussetzung für Sniper-Texte):

• pains (TEXT): Branchenspezifische Schmerzpunkte.
• gains (TEXT): Branchenspezifische Nutzungsversprechen.
• priority (TEXT): Strategischer Status (z.B. "Freigegeben", "Klärungsbedarf").
• notes (TEXT): Interne Anmerkungen zur Branche.
• ops_focus_secondary (BOOLEAN): Flag, ob für operative Rollen das Sekundärprodukt priorisiert werden soll.
• secondary_category_id (INTEGER): Fremdschlüssel auf das alternative Produkt.

---

15. Offene Arbeitspakete (Bauleitung)

Anweisungen für den "Bautrupp" (Gemini CLI).

Task 1: UI-Anpassung - Side-by-Side CRM View & Settings

Ziel: Die neuen Datenfelder an der Oberfläche sichtbar machen.

Anforderungen:

1. Inspector-Update (src/components/Inspector.tsx):

   • Implementiere eine neue Sektion "Data Match (CRM vs. AI)".
   • Zeige links die crm_* Felder (grau hinterlegt/ReadOnly).
   • Zeige rechts die aktuellen Research-Daten (name, website).
   • Visualisiere den data_mismatch_score.
   • Wichtig: Entferne ungenutzte Imports wie Save oder Calendar, um Build-Fehler zu vermeiden!
   • Fixe den Aufruf der ContactsManager Komponente (Props-Mismatch beheben).

2. Settings-Update (src/components/RoboticsSettings.tsx):

   • Erweitere die Branchen-Übersicht (Industries) um die neuen Spalten.
   • Zeige Pains, Gains und Priorität für jedes Vertical an.
   • Diese Daten werden schreibgeschützt aus der DB angezeigt (Quelle ist Notion).

Akzeptanzkriterien:

• Das Frontend lässt sich fehlerfrei bauen (npm run build).
• In der Account-Detailansicht ist der Vergleich zwischen CRM- und Web-Daten sichtbar.
• In den Einstellungen sind die strategischen Inhalte (Pains/Gains) sichtbar.

---

12. Deployment & Access Notes (NAS)

Pfad auf NAS: /volume1/homes/Floke/python/brancheneinstufung/company-explorer Restart: docker-compose restart company-explorer Build: docker-compose up -d --build company-explorer