From ceb7b4ba32f48ba34a71e5d37f46b1619ee70e1b Mon Sep 17 00:00:00 2001 From: Moltbot-Jarvis Date: Wed, 18 Feb 2026 13:04:17 +0000 Subject: [PATCH] docs: highly detailed logic for database fields and CLI tasks --- MIGRATION_PLAN.md | 213 +++++++---------------------- company-explorer/MIGRATION_PLAN.md | 213 +++++++---------------------- 2 files changed, 106 insertions(+), 320 deletions(-) diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 3badf0de..b52b96dc 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -1,181 +1,74 @@ -# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.7.4) +# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.8.5) -**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. +**Kontext:** Strategische Neuausrichtung der Lead-Analyse für RoboPlanet. +**Zentrale Philosophie:** Trennung von CRM-Historie ("Was wir wissen") und KI-Recherche ("Was aktuell wahr ist"). -## 1. Strategische Neuausrichtung +## 14. Detaillierte Logik der neuen Datenfelder (v2.0) -| 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. | +Um Gemini CLI (dem Bautrupp) die Umsetzung zu ermöglichen, hier die semantische Bedeutung und Implementierungs-Logik der neuen Spalten: -## 2. Architektur & Komponenten-Mapping +### 14.1 Qualitäts- & Abgleich-Metriken (Tabelle `companies`) -Das System wird in `company-explorer/` neu aufgebaut. Wir lösen Abhängigkeiten zur Root `helpers.py` auf. +* **`confidence_score` (FLOAT, 0.0 - 1.0):** + * **Bedeutung:** Vertrauensindex der KI-Klassifizierung. + * **UI-Logik:** + * `>= 0.8`: Status "Grün". Vertrauenswürdige Daten. + * `0.5 - 0.79`: Status "Gelb". Erfordert manuellen Check (Review). + * `< 0.5`: Status "Rot". KI-Ergebnis unsicher. + * **Hintergrund:** Verhindert, dass Sniper-Texte auf Basis falscher Branchen-Zuordnungen generiert werden. -### A. Core Backend (`backend/`) +* **`data_mismatch_score` (FLOAT, 0.0 - 1.0):** + * **Bedeutung:** Metrik für die Abweichung zwischen SuperOffice-Bestand und Web-Recherche. + * **Rechenweg:** Die KI vergleicht Name, Adresse und Website. + * `0.0`: Identisch (Voll-Treffer). + * `0.5`: Teil-Mismatch (z.B. Firma heißt im Web leicht anders oder ist innerhalb der Stadt umgezogen). + * `1.0`: Voller Mismatch (Zwei komplett verschiedene Firmen). + * **UI-Ziel:** Im Inspector soll bei Werten `> 0.3` eine Warnung erscheinen: *"Achtung: Stammdaten weichen von Recherche ab!"* -| 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 | +* **`crm_name`, `crm_address`, `crm_website`, `crm_vat`:** + * **Zweck:** Read-Only Snapshot aus SuperOffice. + * **Wichtig:** Diese Felder werden nie durch die Web-Recherche überschrieben. Sie dienen dem Side-by-Side Vergleich. -**Identifizierte Hauptdatei:** `company-explorer/backend/app.py` +* **Status-Flags:** + * **`website_scrape_status`**: Zeigt an, ob die Firmenwebsite erfolgreich ausgelesen wurde (`SUCCESS`, `FAILED`, `BLOCKED`). + * **`wiki_search_status`**: Dokumentiert, ob ein Wikipedia-Eintrag gefunden wurde (`FOUND`, `NOT_FOUND`). -### B. Frontend (`frontend/`) - React +### 14.2 Strategie-Parameter (Tabelle `industries`) -* **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` +* **`pains` / `gains`:** + * Enthalten formatierte Textblöcke. + * **Struktur:** + `[Primary Product: Cleaning]` + `- Pain A` + `- Pain B` + + `[Secondary Product: Service]` + `- Pain C` + * **Anforderung:** Das Frontend muss diese Blöcke sauber formatiert (whitespace-aware) anzeigen. -### 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. +* **`ops_focus_secondary` (BOOLEAN):** + * **Strategischer Hebel:** Wenn auf `True` gesetzt, muss die Lead-Engine für operative Rollen (z.B. "Pflegedienstleitung") automatisch das Sekundärprodukt wählen, da hier der "Teller-Transport" wichtiger ist als die "Bodenreinigung". --- -## 15. Offene Arbeitspakete (Bauleitung) +## 15. Anweisungen für Gemini CLI (Arbeitspakete) -Anweisungen für den "Bautrupp" (Gemini CLI). +### Task 1: UI-Implementierung "Data Match & Strategy" -### Task 1: UI-Anpassung - Side-by-Side CRM View & Settings +**1. Inspector.tsx (Account Detail):** +* Implementiere eine `CRMComparisonCard`. +* Vergleiche `crm_name` vs `name` und `crm_website` vs `website`. +* Visualisiere den `data_mismatch_score` als Ampel oder Score-Balken. +* **Fix:** Korrigiere den Aufruf der `ContactsManager` Komponente (erwartet `contacts` Array). -**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. +**2. RoboticsSettings.tsx (Settings):** +* Erweitere die `Industries`-Tabelle um die Spalten `Pains`, `Gains`, `Priorität` und `Secondary Product`. +* Ermögliche das Ein-/Auskappen von langen Pain-Texten zur besseren Übersicht. --- -## 12. Deployment & Access Notes (NAS) +## 16. Deployment-Referenz (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` +* **Pfad:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer` +* **DB:** `/app/companies_v3_fixed_2.db` +* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py` diff --git a/company-explorer/MIGRATION_PLAN.md b/company-explorer/MIGRATION_PLAN.md index 3badf0de..b52b96dc 100644 --- a/company-explorer/MIGRATION_PLAN.md +++ b/company-explorer/MIGRATION_PLAN.md @@ -1,181 +1,74 @@ -# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.7.4) +# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.8.5) -**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. +**Kontext:** Strategische Neuausrichtung der Lead-Analyse für RoboPlanet. +**Zentrale Philosophie:** Trennung von CRM-Historie ("Was wir wissen") und KI-Recherche ("Was aktuell wahr ist"). -## 1. Strategische Neuausrichtung +## 14. Detaillierte Logik der neuen Datenfelder (v2.0) -| 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. | +Um Gemini CLI (dem Bautrupp) die Umsetzung zu ermöglichen, hier die semantische Bedeutung und Implementierungs-Logik der neuen Spalten: -## 2. Architektur & Komponenten-Mapping +### 14.1 Qualitäts- & Abgleich-Metriken (Tabelle `companies`) -Das System wird in `company-explorer/` neu aufgebaut. Wir lösen Abhängigkeiten zur Root `helpers.py` auf. +* **`confidence_score` (FLOAT, 0.0 - 1.0):** + * **Bedeutung:** Vertrauensindex der KI-Klassifizierung. + * **UI-Logik:** + * `>= 0.8`: Status "Grün". Vertrauenswürdige Daten. + * `0.5 - 0.79`: Status "Gelb". Erfordert manuellen Check (Review). + * `< 0.5`: Status "Rot". KI-Ergebnis unsicher. + * **Hintergrund:** Verhindert, dass Sniper-Texte auf Basis falscher Branchen-Zuordnungen generiert werden. -### A. Core Backend (`backend/`) +* **`data_mismatch_score` (FLOAT, 0.0 - 1.0):** + * **Bedeutung:** Metrik für die Abweichung zwischen SuperOffice-Bestand und Web-Recherche. + * **Rechenweg:** Die KI vergleicht Name, Adresse und Website. + * `0.0`: Identisch (Voll-Treffer). + * `0.5`: Teil-Mismatch (z.B. Firma heißt im Web leicht anders oder ist innerhalb der Stadt umgezogen). + * `1.0`: Voller Mismatch (Zwei komplett verschiedene Firmen). + * **UI-Ziel:** Im Inspector soll bei Werten `> 0.3` eine Warnung erscheinen: *"Achtung: Stammdaten weichen von Recherche ab!"* -| 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 | +* **`crm_name`, `crm_address`, `crm_website`, `crm_vat`:** + * **Zweck:** Read-Only Snapshot aus SuperOffice. + * **Wichtig:** Diese Felder werden nie durch die Web-Recherche überschrieben. Sie dienen dem Side-by-Side Vergleich. -**Identifizierte Hauptdatei:** `company-explorer/backend/app.py` +* **Status-Flags:** + * **`website_scrape_status`**: Zeigt an, ob die Firmenwebsite erfolgreich ausgelesen wurde (`SUCCESS`, `FAILED`, `BLOCKED`). + * **`wiki_search_status`**: Dokumentiert, ob ein Wikipedia-Eintrag gefunden wurde (`FOUND`, `NOT_FOUND`). -### B. Frontend (`frontend/`) - React +### 14.2 Strategie-Parameter (Tabelle `industries`) -* **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` +* **`pains` / `gains`:** + * Enthalten formatierte Textblöcke. + * **Struktur:** + `[Primary Product: Cleaning]` + `- Pain A` + `- Pain B` + + `[Secondary Product: Service]` + `- Pain C` + * **Anforderung:** Das Frontend muss diese Blöcke sauber formatiert (whitespace-aware) anzeigen. -### 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. +* **`ops_focus_secondary` (BOOLEAN):** + * **Strategischer Hebel:** Wenn auf `True` gesetzt, muss die Lead-Engine für operative Rollen (z.B. "Pflegedienstleitung") automatisch das Sekundärprodukt wählen, da hier der "Teller-Transport" wichtiger ist als die "Bodenreinigung". --- -## 15. Offene Arbeitspakete (Bauleitung) +## 15. Anweisungen für Gemini CLI (Arbeitspakete) -Anweisungen für den "Bautrupp" (Gemini CLI). +### Task 1: UI-Implementierung "Data Match & Strategy" -### Task 1: UI-Anpassung - Side-by-Side CRM View & Settings +**1. Inspector.tsx (Account Detail):** +* Implementiere eine `CRMComparisonCard`. +* Vergleiche `crm_name` vs `name` und `crm_website` vs `website`. +* Visualisiere den `data_mismatch_score` als Ampel oder Score-Balken. +* **Fix:** Korrigiere den Aufruf der `ContactsManager` Komponente (erwartet `contacts` Array). -**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. +**2. RoboticsSettings.tsx (Settings):** +* Erweitere die `Industries`-Tabelle um die Spalten `Pains`, `Gains`, `Priorität` und `Secondary Product`. +* Ermögliche das Ein-/Auskappen von langen Pain-Texten zur besseren Übersicht. --- -## 12. Deployment & Access Notes (NAS) +## 16. Deployment-Referenz (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` +* **Pfad:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer` +* **DB:** `/app/companies_v3_fixed_2.db` +* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py`