From 0f87ef192f7bbb47369179bf99616795c7e66efe Mon Sep 17 00:00:00 2001 From: Floke Date: Mon, 19 Jan 2026 07:38:37 +0000 Subject: [PATCH] docs: Restore missing content in migration plan --- MIGRATION_PLAN.md | 183 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 179 insertions(+), 4 deletions(-) diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 5ca4ac23..55638b16 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -4,8 +4,151 @@ **Ziel:** Ablösung von Google Sheets/CLI durch eine Web-App ("Company Explorer") mit SQLite-Backend. ## 1. Strategische Neuausrichtung -... (rest of the file remains the same) -... + +| Bereich | Alt (Legacy) | Neu (Robotics Edition) | +| :--- | :--- | :--- | +| **Daten-Basis** | Google Sheets | **SQLite** (Lokal, performant, filterbar). | +| **Ziel-Daten** | Allgemein / Kundenservice | **Robotics-Signale** (SPA-Bereich? Intralogistik? Werkschutz?). | +| **Branchen** | KI-Vorschlag (Freitext) | **Strict Mode:** Mapping auf feste CRM-Liste (z.B. "Hotellerie", "Maschinenbau"). | +| **Texterstellung** | Pain/Gain Matrix (Service) | **Pain/Gain Matrix (Robotics)**. "Übersetzung" des alten Wissens auf Roboter. | +| **Analytics** | Techniker-ML-Modell | **Deaktiviert**. Vorerst keine Relevanz. | +| **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 | +| **Signal Detector** | **NEU.** Analysiert Website-Text auf Roboter-Potential.
*Logik:* Wenn Branche = Hotel & Keyword = "Wellness" -> Potential: Reinigungsroboter. | 1 | +| **Classifier** | Brancheneinstufung. **Strict Mode:** Prüft gegen `config/allowed_industries.json`. | 2 | +| **Marketing Engine** | Ersetzt `generate_marketing_text.py`. Nutzt neue `marketing_wissen_robotics.yaml`. | 3 | + +### 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. +* **View 3: "List Matcher":** Upload einer Excel-Liste -> Anzeige von Duplikaten -> Button "Neue importieren". + +## 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: + * OpenAI/Gemini Wrapper (Retry Logic). + * Text Cleaning (`clean_text`, `normalize_string`). + * URL Normalization. + +* **Quelle:** Andere Gemini Apps (`duckdns`, `gtm-architect`, `market-intel`) +* **Aktion:** Wir betrachten diese als Referenz. Nützliche Logik (z.B. die "Grit"-Prompts aus `market-intel`) wird explizit in die neuen Service-Module kopiert. + +## 4. Datenstruktur (SQLite Schema) + +### Tabelle `companies` (Stammdaten) +* `id` (PK) +* `name` (String) +* `website` (String) +* `crm_id` (String, nullable - Link zum D365) +* `industry_crm` (String - Die "erlaubte" Branche) +* `city` (String) +* `country` (String - Standard: "DE" oder aus Impressum) +* `status` (Enum: NEW, IMPORTED, ENRICHED, QUALIFIED) + +### Tabelle `signals` (Roboter-Potential) +* `company_id` (FK) +* `signal_type` (z.B. "has_spa", "has_large_warehouse", "has_security_needs") +* `confidence` (Float) +* `proof_text` (Snippet von der Website) + +### Tabelle `contacts` (Ansprechpartner) +* `id` (PK) +* `account_id` (FK -> companies.id) +* `gender` (Selection: "männlich", "weiblich") +* `title` (Text, z.B. "Dr.") +* `first_name` (Text) +* `last_name` (Text) +* `email` (Email) +* `job_title` (Text - Visitenkarte) +* `language` (Selection: "De", "En") +* `role` (Selection: "Operativer Entscheider", "Infrastruktur-Verantwortlicher", "Wirtschaftlicher Entscheider", "Innovations-Treiber") +* `status` (Selection: Siehe Prozess-Status) +* `is_primary` (Boolean - Nur einer pro Account) + +### Tabelle `industries` (Branchen-Fokus) +* `id` (PK) +* `name` (String, Unique) +* `description` (Text - Abgrenzung/Definition) +* `is_focus` (Boolean) +* `primary_category_id` (FK -> robotics_categories.id) + +### Tabelle `job_role_mappings` (Rollen-Logik) +* `id` (PK) +* `pattern` (String - Regex oder Text-Pattern für Jobtitles) +* `role` (String - Zielrolle im Verkaufsprozess) + +### Tabelle `duplicates_log` +* Speichert Ergebnisse von Listen-Abgleichen ("Upload X enthielt 20 bekannte Firmen"). + +## 5. Phasenplan Umsetzung + +1. **Housekeeping:** Archivierung des Legacy-Codes (`_legacy_gsheets_system`). +2. **Setup:** Init `company-explorer` (Backend + Frontend Skeleton). +3. **Foundation:** DB-Schema + "List Matcher" (Deduplizierung ist Prio A für Operations). +4. **Enrichment:** Implementierung des Scrapers + Signal Detector (Robotics). +5. **UI:** React Interface für die Daten. +6. **CRM-Features:** Contacts Management & Marketing Automation Status. + +## 6. Spezifikation: Contacts & Marketing Status (v0.5.0) + +*(Hinzugefügt am 15.01.2026)* + +**Konzept:** +Contacts stehen in 1:n Beziehung zu Accounts. Accounts können einen "Primary Contact" haben. + +**Datenfelder:** +* **Geschlecht:** Selection (männlich / weiblich) +* **Vorname:** Text +* **Nachname:** Text +* **E-Mail:** Type: E-Mail +* **Jobtitle:** Text (Titel auf der Visitenkarte) +* **Sprache:** Selection (De / En) + +**Rollen (Funktion im Verkaufsprozess):** +* Operativer Entscheider +* Infrastruktur-Verantwortlicher +* Wirtschaftlicher Entscheider +* Innovations-Treiber + +**Status (Marketing Automation):** +* *Manuell:* + * Soft Denied (freundliche Absage) + * Bounced (E-Mail invalide) + * Redirect (ist nicht verantwortlich) + * Interested (ist interessiert) + * Hard denied (nicht mehr kontaktieren) +* *Automatisch:* + * Init (Kontakt soll in die Automation hineinlaufen) + * 1st Step (Kontakt hat die erste Nachricht erhalten) + * 2nd Step (Kontakt hat die zweite Nachricht erhalten) + * Not replied (Kontakt hat die dritte Nachricht erhalten und nicht geantwortet) + +**Branchen-Fokus (Settings):** +* **Name:** Eindeutiger Name der Branche (CRM-Mapping). +* **Beschreibung:** Textuelle Abgrenzung, was zu dieser Branche gehört. +* **Is Focus:** Markiert Branchen, die prioritär bearbeitet werden. +* **Primäre Produktkategorie:** Zuordnung einer Robotics-Kategorie (z.B. Hotel -> Cleaning). + +**Job-Rollen Mapping (Settings):** +* **Pattern:** Text-Muster (z.B. "Technischer Leiter", "CTO"), das in Jobtitles gesucht wird. +* **Zugeordnete Rolle:** Die funktionale Interpretation (z.B. Operativer Entscheider). ## 7. Historie & Fixes (Jan 2026) @@ -44,5 +187,37 @@ * **Zeitstempel:** Anzeige des Erstellungsdatums für jeden Anreicherungsdatensatz (Wikipedia, AI Dossier, Impressum) in der Detailansicht. * **Manuelle Impressum-URL:** Möglichkeit zur manuellen Eingabe einer Impressum-URL in der Detailansicht, um die Extraktion von Firmendaten zu erzwingen. * **Frontend-Fix:** Behebung eines Build-Fehlers (`Unexpected token`) in `Inspector.tsx` durch Entfernung eines duplizierten JSX-Blocks. -... (rest of the file remains the same) -... \ No newline at end of file + +* **[UPGRADE] v2.6.2: Report Completeness & Edit Mode** + * **Edit Hard Facts:** Neue Funktion in Phase 1 ("Edit Raw Data") erlaubt die manuelle Korrektur der extrahierten technischen JSON-Daten. + * **Report-Update:** Phase 5 Prompt wurde angepasst, um explizit die Ergebnisse aus Phase 2 (ICPs & Data Proxies) im finalen Report aufzuführen. + * **Backend-Fix:** Korrektur eines Fehlers beim Speichern von JSON-Daten, der auftrat, wenn Datenbank-Inhalte als Strings vorlagen. + +* **[UPGRADE] v2.6.1: Stability & UI Improvements** + * **White Screen Fix:** Robuste Absicherung des Frontends gegen `undefined`-Werte beim Laden älterer Sitzungen (`optional chaining`). + * **Session Browser:** Komplettes Redesign der Sitzungsübersicht zu einer übersichtlichen Listenansicht mit Icons (Reinigung/Service/Transport/Security). + * **URL-Anzeige:** Die Quell-URL wird nun als dedizierter Link angezeigt und das Projekt automatisch basierend auf dem erkannten Produktnamen umbenannt. + +* **[UPGRADE] v2.6: Rich Session Browser** + * **Neues UI:** Die textbasierte Liste für "Letzte Sitzungen" wurde durch eine dedizierte, kartenbasierte UI (`SessionBrowser.tsx`) ersetzt. + * **Angereicherte Daten:** Jede Sitzungskarte zeigt nun den Produktnamen, die Produktkategorie (mit Icon), eine Kurzbeschreibung und einen Thumbnail-Platzhalter an. + * **Backend-Anpassung:** Die Datenbankabfrage (`gtm_db_manager.py`) wurde erweitert, um diese Metadaten direkt aus der JSON-Spalte zu extrahieren und an das Frontend zu liefern. + * **Verbesserte UX:** Deutlich verbesserte Übersichtlichkeit und schnellere Identifikation von vergangenen Analysen. + +* **[UPGRADE] v2.5: Hard Fact Extraction** + * **Phase 1 Erweiterung:** Implementierung eines sekundären Extraktions-Schritts für "Hard Facts" (Specs). + * **Strukturiertes Daten-Schema:** Integration von `templates/json_struktur_roboplanet.txt`. + * **Normalisierung:** Automatische Standardisierung von Einheiten (Minuten, cm, kg, m²/h). + * **Frontend Update:** Neue UI-Komponente zur Anzeige der technischen Daten (Core Data, Layer, Extended Features). + * **Sidebar & Header:** Update auf "ROBOPLANET v2.5". + +* **[UPGRADE] v2.4:** + * Dokumentation der Kern-Engine (`helpers.py`) mit Dual SDK & Hybrid Image Generation. + * Aktualisierung der Architektur-Übersicht und Komponenten-Beschreibungen. + * Versionierung an den aktuellen Code-Stand (`v2.4.0`) angepasst. + +* **[UPGRADE] v2.3:** + * Einführung der Session History (Datenbank-basiert). + * Implementierung von Markdown-Cleaning (Stripping von Code-Blocks). + * Prompt-Optimierung für tabellarische Markdown-Ausgaben in Phase 5. + * Markdown-File Import Feature.