1591 lines
119 KiB
Markdown
1591 lines
119 KiB
Markdown
# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.8.1)
|
|
|
|
**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. **Neu (v5.0):** Hochpräzises Matching mit Domain-Veto (überstimmt Namen), Generic Name Protection (Stop-Wörter like 'Klinikum') und strikter Location-Penalty. | 1 |
|
|
| **Scraper (Base)** | Extrahiert Text von Websites. Basis für alle Analysen. | 1 |
|
|
| **Classification Service** | **NEU (v0.7.0).** Zweistufige Logik: <br> 1. Strict Industry Classification. <br> 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: <br> 1. **Prüfen:** Stellt fest, ob ein Unternehmen bereits existiert. <br> 2. **Erstellen:** Legt das Unternehmen an, falls es neu ist. <br> 3. **Anstoßen:** Startet den asynchronen `discover`-Prozess. <br> 4. **Warten (Polling):** Überwacht den Status des Unternehmens, bis eine Website gefunden wurde. <br> 5. **Analysieren:** Startet den asynchronen `analyze`-Prozess. <br> **Vorteil:** Bietet dem aufrufenden Dienst eine einfache, quasi-synchrone Schnittstelle und stellt sicher, dass die Prozessschritte in der korrekten Reihenfolge ausgeführt werden. |
|
|
|
|
### 2.1 Der End-to-End Datenfluss (Lead-Fabrik)
|
|
|
|
Diese Grafik visualisiert den gesamten Prozess von der Anlage eines Kontakts im CRM über die KI-Analyse bis zur fertigen Marketing-Automation.
|
|
|
|
```mermaid
|
|
graph TD
|
|
%% Nodes
|
|
User((Vertriebs-User))
|
|
SO_CRM[SuperOffice CRM]
|
|
Connector[Connector Service]
|
|
CE_Core[Company Explorer Core]
|
|
CE_AI[AI Analysis Engine]
|
|
CE_DB[(SQLite DB)]
|
|
MA_System[Marketing Automation]
|
|
|
|
%% Flow
|
|
User -- Erstellt Contact (Firma / Person) --> SO_CRM
|
|
SO_CRM -- Webhook (New Contact) --> Connector
|
|
Connector -- POST /provision --> CE_Core
|
|
|
|
subgraph "Intelligence Phase (Asynchron)"
|
|
CE_Core -- 1. Scrape & Research --> CE_AI
|
|
CE_AI -- 2. Vertical & Metriken (Potential) --> CE_Core
|
|
CE_AI -- 3. Generiere Atomic Opener --> CE_Core
|
|
end
|
|
|
|
subgraph "Matrix Logic (Matching)"
|
|
CE_Core -- 4. Rolle & Branche Identifizieren --> CE_DB
|
|
CE_DB -- 5. Hole Matrix-Texte (Subject/Intro) --> CE_Core
|
|
Note[Logik: Primary vs Secondary Product<br>z.B. Healthcare: Pflege -> Transport]
|
|
end
|
|
|
|
CE_Core -- Angereichertes Profil + Texte --> Connector
|
|
Connector -- UPDATE Person (UDFs) --> SO_CRM
|
|
|
|
SO_CRM -- Daten verfügbar --> MA_System
|
|
MA_System -- Textblöcke ins Template einsetzen --> Email(E-Mail Automation läuft an)
|
|
```
|
|
|
|
**Prozess-Schritte:**
|
|
1. **Trigger:** Ein Vertriebsmitarbeiter legt eine Person oder firma in SuperOffice an.
|
|
2. **Transport:** Der Connector empfängt den Webhook und beauftragt den Company Explorer (`/provision`).
|
|
3. **Intelligence:**
|
|
* Die Website wird gescraped and analysiert.
|
|
* Die KI bestimmt das **Vertical** (z.B. "Healthcare - Hospital") und berechnet das **Potenzial** (z.B. Bettenanzahl).
|
|
* Ein individueller **Atomic Opener** wird generiert, der auf die spezifische Situation des Unternehmens eingeht.
|
|
4. **Matrix Match:**
|
|
* Basierend auf der Job-Rolle (z.B. "Pflegedienstleitung") wird die **Persona** ("Operativer Entscheider") bestimmt.
|
|
* Die Engine prüft das `Ops Focus: Secondary` Flag (z.B. bei Krankenhäusern).
|
|
* Die passenden Textbausteine (Betreff, Intro, Social Proof) werden aus der vor-generierten Matrix geladen.
|
|
5. **Sync Back:** Alle Texte (Opener + Matrix-Bausteine) werden in die benutzerdefinierten Felder (UDFs) der Person in SuperOffice zurückgeschrieben.
|
|
6. **Execution:** Die Marketing-Automation nutzt diese Felder (`{udf_opener}`, `{udf_intro}`), um hoch-personalisierte E-Mails zu versenden.
|
|
|
|
## 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 for Jobtitles)
|
|
* `role` (String - Zielrolle)
|
|
|
|
## 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 for Operations).
|
|
4. **Enrichment:** Implementierung des Scrapers + Signal Detector (Robotics).
|
|
5. **UI:** React Interface for die Daten.
|
|
6. **CRM-Features:** Contacts Management & Marketing Automation Status.
|
|
|
|
## 6. Spezifikation: Contacts & Marketing Status (v0.5.0)
|
|
|
|
**Konzept:**
|
|
Contacts stehen in 1:n Beziehung zu Accounts. Accounts können einen "Primary Contact" have.
|
|
|
|
**Rollen (Funktion im Verkaufsprozess):**
|
|
* Operativer Entscheider
|
|
* Infrastruktur-Verantwortlicher
|
|
* Wirtschaftlicher Entscheider
|
|
* Innovations-Treiber
|
|
|
|
**Status (Marketing Automation):**
|
|
* *Manuell:* Soft Denied, Bounced, Redirect, Interested, Hard denied.
|
|
* *Automatisch:* Init, 1st Step, 2nd Step, Not replied, Unsubscribed.
|
|
|
|
### 6.1 Feature: Unsubscribe-Funktionalität (v2.1 - Feb 2026)
|
|
|
|
**Konzept:**
|
|
Um DSGVO-konforme Marketing-Automatisierung zu ermöglichen, wurde eine sichere Unsubscribe-Funktion implementiert.
|
|
|
|
**Technische Umsetzung:**
|
|
1. **Token:** Jeder Kontakt in der `contacts`-Tabelle erhält ein einzigartiges, nicht erratbares `unsubscribe_token` (UUID).
|
|
2. **Link-Generierung:** Der Company Explorer generiert einen vollständigen, personalisierten Link (z.B. `https://<APP_BASE_URL>/unsubscribe/<token>`).
|
|
3. **API-Endpunkt:** Ein öffentlicher GET-Endpunkt `/unsubscribe/{token}` nimmt Abmeldungen ohne Authentifizierung entgegen.
|
|
4. **Logik:**
|
|
* Bei Aufruf des Links wird der Status des zugehörigen Kontakts auf `"unsubscribed"` gesetzt.
|
|
* Der Benutzer erhält eine simple HTML-Bestätigungsseite.
|
|
5. **CRM-Integration:** Der generierte Link wird über die Provisioning-API an den `connector-superoffice` zurückgegeben, der ihn in ein entsprechendes UDF in SuperOffice schreibt.
|
|
|
|
**Update (März 2026): Infrastruktur-Stabilisierung & Sicherheit**
|
|
* **Routing-Schutz:** Um den Company Explorer (Port 8000) nicht komplett dem Internet auszusetzen, wurde ein präziser Bypass im externen IT-Proxy eingerichtet: Die Route `location /ce/unsubscribe/` leitet exakt und nur Abmeldungen an das interne Gateway (Port 8090) durch. Alle anderen Pfade bleiben hinter dem VPN/Passwort-Schutz.
|
|
* **Konfiguration:** Damit das Backend korrekte externe Links generiert, muss die Umgebungsvariable `APP_BASE_URL` (z.B. `https://gtm.robo-planet.de/ce`) in der `.env`-Datei gesetzt und in der `docker-compose.yml` an den Container durchgereicht werden.
|
|
* **Zertifikate:** WICHTIG: Externe Aufrufe benötigen eine vollständige SSL-Zertifikatskette (`_fullchain.crt` inkl. Intermediate Certificates), da Endkunden-Browser sonst eine Sicherheitswarnung werfen, selbst wenn `curl` das Zertifikat akzeptiert.
|
|
|
|
## 7. Historie & Fixes (Jan 2026)
|
|
|
|
* **[MAJOR] v0.9.8: User Identity & Enhanced Error Transparency (May 22, 2026)**
|
|
* **Identity Injection:** Integrated Entra ID (Microsoft) identity headers (`X-User-Email`) via the Nginx proxy, enabling the backend to automatically identify the reporting user without manual input.
|
|
* **Automated Attribution:** Error reports in the Sales Dashboard now automatically capture and prepend the reporter's email address to the comment field.
|
|
* **UI Transparency:** Enhanced the "Reported Data Mistakes" table in Settings to display the exact **reporting date/time** and the **identifying reporter** for all new entries.
|
|
* **Guided Feedback:** Refactored the error reporting modal to guide users with specific prompts (Asking for: "What value/date was wrong?" and "What should have been the correct value?").
|
|
* **[MAJOR] v0.9.9: Admin Activity Report & Tool-Influenced ROI (May 23, 2026)**
|
|
* **Lückenlose Protokollierung:** Jede manuell über das Sales Dashboard versendete E-Mail (Rückrufbitte, Magic Wand) wird nun als echte Aktivität (`Mailing per Email`) in der lokalen SQLite-Datenbank protokolliert.
|
|
* **Identity-Sicherheit:** Die Zuordnung zum Sales Manager erfolgt nun präzise über den `X-User-Email` Header (Auth-Service). Vermeidung von ID-Kollisionen mit SuperOffice durch die Generierung eindeutiger **negativer Unique-IDs**.
|
|
* **ROI-Tracking (Live-Start):** Implementierung einer Analyse-Logik, die Folgereaktionen (insbesondere protokollierte **Telefonate**) innerhalb von 14 Tagen nach einer Dashboard-Mail misst (Fokus: Daten ab 01.05.2026).
|
|
* **ROI Dashboard:** Integration eines neuen interaktiven Widgets im Sales Dashboard (Controlling / Expert Mode), das den Beitrag des Tools zur Vertriebseffizienz pro Manager transparent visualisiert (Aktueller Stand Sebastian: 62 Mails / 6 Reaktionen).
|
|
* **[MAJOR] v5.0.0: Deduplicator High-Precision Upgrade (April 10, 2026)**
|
|
* **Domain Veto:** Domain mismatches (e.g., `ukaachen.de` vs `uniklinik-freiburg.de`) now definitively block false positive matches (score 0), even if the names are extremely similar or identical.
|
|
* **Generic Name Protection:** Added critical public institution identifiers (e.g., `Universitätsklinikum`, `Klinik`, `Spital`) to the `STOP_TOKENS_BASE` to prevent generic name collisions across different cities.
|
|
* **Strict Location Penalty:** Heavily increased the fuzzy matching penalty (up to 50 points) when two companies share a generic name but are located in different cities.
|
|
* **[MAJOR] v0.9.5: Marketing Matrix Full Scale & Masterclass Integration (March 27, 2026)**
|
|
* **10/10 Masterclass:** Integrated elite B2B copywriting rules from Lead-Engine (No rhetorical questions, no platitudes, "Show, don't tell").
|
|
* **Implicit Relevance:** Removed explicit role naming (e.g., "For you as...") in introductions to prevent friction and focus on implicit value via Pains and KPIs.
|
|
* **Full Scale Generation:** Successfully generated and verified 125 unique combinations (25 Industries x 5 Personas) in the local SQLite database.
|
|
* **Notion Sync Härtung:** Stabilized synchronization for Personas (`Role` property), Industries and Products including environment variable handling for Docker environments.
|
|
* **Strategy Switch:** Verified automated product priority switching (Primary vs. Secondary) based on the `ops_focus_secondary` flag for operational personas.
|
|
* **[MAJOR] v0.8.6: Report Mistakes Feature Completion (March 2026)**
|
|
* **UI Enhancements:** Added report mistake buttons (Flag icon) directly next to relevant data points (Website, Industry, Metric, Address, VAT) in the Inspector for quick reporting.
|
|
* **Contextual Reporting:** The report form now pre-fills the field name and current value, and includes a dedicated field for "Quote from Source". Smooth scrolling anchors the user to the form.
|
|
* **Backend Application:** Implemented logic in the API to automatically apply "APPROVED" mistakes directly to the company record (`companies` table).
|
|
* **Data Protection:** The AI analysis pipeline (`ClassificationService`) now fetches approved mistakes and strictly prevents overwriting these human-verified values during subsequent enrichment runs.
|
|
* **[MAJOR] v0.9.0: Role Matching Optimization & Portability (March 2026)**
|
|
* **Pattern Optimizer:** Asynchrones Hintergrund-System zur automatischen Konsolidierung von Einzel-Matches in mächtige Regex-Regeln via Gemini. Inklusive Konfliktprüfung gegen andere Rollen. Nutzt `ast.literal_eval` for robustes Regex-Parsing.
|
|
* **Database Management:** Direkter Up- & Download der SQLite-Datenbank aus dem UI heraus. Automatisches Backup-System bei Upload.
|
|
* **Regex Sandbox:** Integriertes Test-Tool for Muster vor der Speicherung in der Datenbank.
|
|
* **Smart Suggestions:** Live-Analyse der Kontaktdaten zur Identifikation häufiger Schlüsselwörter pro Rolle als Klick-Vorschläge.
|
|
* **[MAJOR] v0.9.1: Regex Export & Robust Matching (March 2026)**
|
|
* **Export:** Neues Feature im UI (Settings -> Database & Regex) hinzugefügt, um die Job-Rollen-Pattern als CSV (mit Semikolon getrennt) for die Offline-Regex-Optimierung herunterzuladen.
|
|
* **Robustes Parsing:** KI-Batch-Klassifizierung gehärtet, um "List of Dicts" Antworten und `Invalid \uXXXX escape` Fehler von Gemini abzufangen (Fallback auf `ast.literal_eval`).
|
|
* **Fuzzy Matching:** Die Zuweisung der von der KI gelieferten Rollen an die Datenbank-Personas ist nun fehlertolerant (ignoriert Groß-/Kleinschreibung und Bindestriche).
|
|
* **Infrastruktur:** Alle Datenbanken (inklusive `companies_v3_fixed_2.db` und `connector_queue.db`) wurden von "Named Volumes" auf Host-Bind-Mounts (`./data/`) umgestellt, um Backup-Verluste zu verhindern.
|
|
* **[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**
|
|
|
|
## 8. Eingesetzte Prompts (Account-Analyse v0.7.4)
|
|
|
|
### 8.1 Strict Industry Classification
|
|
|
|
Ordnet das Unternehmen einer definierten Branche zu.
|
|
|
|
```python
|
|
prompt = f"""
|
|
Act as a strict B2B Industry Classifier.
|
|
Company: {company_name}
|
|
Context: {website_text[:3000]}
|
|
|
|
Available Industries:
|
|
{json.dumps(industry_definitions, indent=2)}
|
|
|
|
Task: Select the ONE industry that best matches the company.
|
|
If none match well, select 'Others'.
|
|
"""
|
|
```
|
|
|
|
### 8.2 Metric Extraction
|
|
|
|
Extrahiert den spezifischen Zahlenwert ("Scraper Search Term") und liefert JSON for den `MetricParser`.
|
|
|
|
```python
|
|
prompt = f"""
|
|
Extract the following metric for the company in industry '{industry_name}':
|
|
Target Metric: "{search_term}"
|
|
|
|
Source Text:
|
|
{text_content[:6000]}
|
|
|
|
Return a JSON object with 'raw_value', 'raw_unit', 'proof_text'.
|
|
"""
|
|
```
|
|
|
|
## 9. Notion Integration (Single Source of Truth)
|
|
|
|
Das System nutzt Notion als zentrales Steuerungselement for strategische Definitionen.
|
|
|
|
### 9.1 Datenfluss
|
|
1. **Definition:** Branchen und Robotik-Kategorien werden in Notion gepflegt.
|
|
2. **Synchronisation:** Das Skript `sync_notion_industries.py` zieht die Daten via API (Upsert).
|
|
3. **App-Nutzung:** Der `ClassificationService` nutzt sie als "System-Anweisung" for das LLM.
|
|
|
|
## 10. Database Migration
|
|
|
|
Bei Schema-Änderungen: `docker exec -it company-explorer python3 backend/scripts/migrate_db.py`.
|
|
|
|
## 11. Lessons Learned (Retrospektive Jan 24, 2026)
|
|
|
|
1. **FastAPI Routing:** Spezifische Endpunkte immer VOR dynamischen Endpunkten deklarieren.
|
|
2. **Docker Persistence:** Datenbankdatei muss zwingend als Volume gemountet sein.
|
|
3. **Formel-Robustheit:** Bereinigung von Einheiten/Kommentaren vor `eval()`.
|
|
|
|
## 12. Deployment & Access Notes
|
|
|
|
* **Pfad auf NAS:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer`
|
|
* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py`
|
|
|
|
## 13. Feature: Report Mistakes
|
|
|
|
Benutzer können Fehler im Inspector melden. Diese werden in `reported_mistakes` gespeichert und in den Settings zur Prüfung angezeigt.
|
|
* **User Tracking:** Das System identifiziert den meldenden User automatisch über den Entra ID (Microsoft) Header des Proxy-Servers.
|
|
* **Historie:** Jede Meldung wird mit einem präzisen Zeitstempel (created_at) versehen und in der Übersicht unter Settings chronologisch dargestellt.
|
|
* **Guided Input:** Das Formular im Sales Dashboard fordert Benutzer gezielt auf, fehlerhafte Werte und korrekte Alternativen (inkl. Daten) anzugeben.
|
|
|
|
## 14. Upgrade v2.0 (Feb 18, 2026): "Lead-Fabrik" Erweiterung
|
|
|
|
Dieses Upgrade transformiert den Company Explorer in das zentrale Gehirn der Lead-Generierung (Vorratskammer).
|
|
|
|
### 14.1 Detaillierte Logik der neuen Datenfelder
|
|
|
|
* **`confidence_score` (FLOAT):** Indikator for die Sicherheit der KI-Klassifizierung. `> 0.8` = Grün.
|
|
* **`data_mismatch_score` (FLOAT):** Abweichung zwischen CRM-Bestand und Web-Recherche (z.B. Umzug).
|
|
* **`crm_name`, `crm_address`, `crm_website`, `crm_vat`:** Read-Only Snapshot aus SuperOffice zum Vergleich.
|
|
* **Status-Flags:** `website_scrape_status` und `wiki_search_status`.
|
|
|
|
#### Tabelle `industries` (Strategie-Parameter)
|
|
|
|
* **`pains` / `gains`:** Strukturierte Textblöcke (getrennt durch `[Primary Product]` and `[Secondary Product]`).
|
|
* **`ops_focus_secondary` (BOOLEAN):** Steuerung for rollenspezifische Produkt-Priorisierung.
|
|
|
|
---
|
|
|
|
## 15. Offene Arbeitspakete (Bauleitung)
|
|
|
|
### Task 1: UI-Anpassung - Side-by-Side CRM View & Settings
|
|
(In Arbeit / Teilweise erledigt durch Gemini CLI)
|
|
|
|
### Task 2: Intelligenter CRM-Importer (Bestandsdaten)
|
|
|
|
**Ziel:** Importieren der `demo_100.xlsx` in die SQLite-Datenbank.
|
|
1. **PLZ-Handling:** Zwingend als **String** einlesen.
|
|
2. **Matching:** Kaskade über CRM-ID, VAT, Domain, Fuzzy Name.
|
|
|
|
---
|
|
|
|
## 16. Deployment-Referenz (NAS)
|
|
* **Pfad:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer`
|
|
* **DB:** `/app/companies_v3_fixed_2.db`
|
|
|
|
---
|
|
|
|
## 17. Analyse-Logik v3.0 (Feb 2026): Quantitative Potenzialanalyse & "Atomic Opener"
|
|
|
|
### 17.1 Das Gesamtbild: Vom Content zur fertigen Analyse
|
|
|
|
1. Branchen-Klassifizierung -> 2. Quantitative Potenzialanalyse -> 3. "Atomic Opener" Generierung -> 4. Finales Commit.
|
|
|
|
### 17.2 Quantitative Potenzialanalyse im Detail
|
|
|
|
**Ziel:** Für jedes Unternehmen einen `standardized_metric_value` in `m²` zu ermitteln.
|
|
* **Stufe 1:** Direkte Flächensuche ("Fläche", "m²").
|
|
* **Stufe 2:** Proxy-Metrik-Suche (z.B. Betten * 100).
|
|
|
|
### 17.3 "Atomic Opener" Generierung im Detail (Zweistufiger Prozess, Feb 22, 2026)
|
|
|
|
**Ziel:** Zwei hoch-personalisierte, schlagkräftige Einleitungssätze (2-3 Sätze).
|
|
* **Schritt 1:** Das Website-Dossier (Extraktion & Komprimierung).
|
|
* **Schritt 2:** Formulierung des Openers (Scharfsinnige Beobachtung).
|
|
|
|
### 17.7 Marketing Matrix Schärfung (v3.2 - Feb 22, 2026)
|
|
|
|
Die Qualität der Marketing-Matrix (Subject, Intro, Social Proof) ist entscheidend for den Erfolg des Outreachs.
|
|
|
|
**Kern-Konzept: Der Strategische Brückenschlag**
|
|
Die KI agiert nicht mehr als reiner Copywriter, sondern als **scharfsinniger B2B-Strategieberater** ("Lösungsberater").
|
|
|
|
**Neues Feature: "Ops Focus: Secondary" (Die Rollen-Weiche)**
|
|
Wenn in Notion das Flag `Ops Focus: Secondary` aktiv ist, wechselt die Engine for die Persona **"Operativer Entscheider"** automatisch auf das **Sekundärprodukt** (z.B. Service-Roboter/Transport).
|
|
|
|
**Der "Lösungsberater" Prompt (Auszug):**
|
|
```python
|
|
prompt = f"""
|
|
Du bist ein kompetenter Lösungsberater und brillanter Texter.
|
|
AUFGABE: Erstelle 3 Textblöcke (Subject, Introduction_Textonly, Industry_References_Textonly) for eine E-Mail an einen Entscheider.
|
|
|
|
--- KONTEXT ---
|
|
ZIELBRANCHE: {industry.name}
|
|
BRANCHEN-HERAUSFORDERUNGEN (PAIN POINTS): {industry_pains}
|
|
FOKUS-PRODUKT (LÖSUNG): {target_scope} ({product_context})
|
|
ANSPRECHPARTNER (ROLLE): {persona.name}
|
|
PERSÖNLICHE HERAUSFORDERUNGEN: {persona_pains}
|
|
"""
|
|
```
|
|
|
|
### 17.8 Erweiterte Matrix-Multiplikation: Primary vs. Secondary (Update Feb 24, 2026)
|
|
|
|
**Konzept:** Strikte Trennung zwischen `[Primary Product]` and `[Secondary Product]` zur Vermeidung logischer Brüche.
|
|
|
|
### 17.9 Deep Persona Injection (Update Feb 24, 2026)
|
|
|
|
**Ziel:** Maximale Relevanz durch Einbezug psychografischer und operativer Rollen-Details ("Voll ins Zentrum").
|
|
|
|
**Die Erweiterung:**
|
|
- **Vollständiger Daten-Sync:** Übernahme von `Beschreibung/Denkweise`, `Was ihn überzeugt` und `KPIs` aus der Notion "Personas / Roles" Datenbank in das lokale Schema.
|
|
- **Rollenspezifische Tonalität:** Die KI nutzt diese Details, um den "Ton" der jeweiligen Persona perfekt zu treffen (z.B. technischer Fokus beim Infrastruktur-Leiter vs. betriebswirtschaftlicher Fokus beim CFO).
|
|
|
|
**Beispiel-Kaskade (Klinikum Erding):**
|
|
1. **Opener:** "Klinikum Erding trägt maßgeblich zur regionalen Versorgung bei... Dokumentation lückenloser Hygiene stellt eine operative Herausforderung dar."
|
|
2. **Matrix-Anschluss (Infrastruktur):** "...minimieren Ausfallzeiten um 80-90% durch proaktives Monitoring... planbare Wartung und Transparenz durch feste **SLAs**." (Direkter Bezug auf hinterlegte Überzeugungsargumente).
|
|
3. **Matrix-Anschluss (Wirtschaftlich):** "...Reduktion operativer Personalkosten um 10-25%... wirkt sich direkt auf **ROI** und **Amortisationszeit** aus." (Direkter Bezug auf hinterlegte KPIs).
|
|
|
|
### 17.10 Production Switch & Multi-Campaign Architecture (Feb 27, 2026)
|
|
|
|
Das System wurde erfolgreich von der Sandbox auf die SuperOffice-Produktionsumgebung migriert. Alle technischen Hürden (Auth, ProgIDs, REST-Besonderheiten) wurden beseitigt.
|
|
|
|
#### A. Umgebungsparameter (Production)
|
|
* **Base URL (OAuth):** `https://online.superoffice.com/login/common/oauth/tokens`
|
|
* **Base URL (API):** `https://online3.superoffice.com/Cust26720/api/v1/`
|
|
* **Tenant ID:** `Cust26720`
|
|
* **Client ID:** `0fd8272803551846f7212a961a1a0046`
|
|
|
|
#### B. Finales UDF Mapping (ProgIDs)
|
|
Verifizierte IDs for den Mandanten `Cust26720`:
|
|
|
|
| Zweck | Entität | ProgID | Format / Logik |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **MA Subject** | Person | `SuperOffice:19` | Text |
|
|
| **MA Intro** | Person | `SuperOffice:20` | Text |
|
|
| **MA Social Proof** | Person | `SuperOffice:21` | Text |
|
|
| **MA Unsubscribe** | Person | `SuperOffice:22` | URL (DSGVO konform) |
|
|
| **MA Campaign** | Person | `SuperOffice:23` | Liste (Auflösung via `:DisplayText`) |
|
|
| **Vertical** | Contact | `SuperOffice:83` | Liste (Mapping siehe unten) |
|
|
| **AI Summary** | Contact | `SuperOffice:84` | Truncated (< 135 Zeichen) |
|
|
| **AI Last Update** | Contact | `SuperOffice:85` | Datum: `[D:MM/DD/YYYY HH:MM:SS]` |
|
|
| **Opener Primary** | Contact | `SuperOffice:86` | Text (Infrastruktur/Cleaning) |
|
|
| **Opener Secondary**| Contact | `SuperOffice:87` | Text (Service/Logistik) |
|
|
| **Last Outreach** | Contact | `SuperOffice:88` | Datum |
|
|
|
|
#### C. Vollständige Vertical-Liste (Produktiv-IDs)
|
|
Die Liste `udlist331` steuer die Branchenzuordnung. Der Connector nutzt folgendes Mapping:
|
|
`Automotive - Dealer: 1613, Corporate - Campus: 1614, Energy - Grid & Utilities: 1615, Energy - Solar/Wind: 1616, Healthcare - Care Home: 1617, Healthcare - Hospital: 1618, Hospitality - Gastronomy: 1619, Hospitality - Hotel: 1620, Industry - Manufacturing: 1621, Infrastructure - Communities: 1622, Infrastructure - Public: 1623, Infrastructure - Transport: 1624, Infrastructure - Parking: 1625, Leisure - Entertainment: 1626, Leisure - Fitness: 1627, Leisure - Indoor Active: 1628, Leisure - Outdoor Park: 1629, Leisure - Wet & Spa: 1630, Logistics - Warehouse: 1631, Others: 1632, Reinigungsdienstleister: 1633, Retail - Food: 1634, Retail - Non-Food: 1635, Retail - Shopping Center: 1636, Tech - Data Center: 1637`.
|
|
|
|
#### D. Technische Meilensteine (Lessons Learned)
|
|
|
|
1. **Atomic PATCH Workflow:** Um API-Timeouts und Inkonsistenzen zu vermeiden, bündelt der `worker.py` (v1.8) alle Änderungen an einem Kontakt in einem einzigen `PATCH`-Request an `/Contact/{id}`.
|
|
2. **Website-Sync (REST-Korrektur):** Die Aktualisierung der Website erfolgt über das `Urls`-Array (nicht `UrlAddress`). Format: `"Urls": [{"Value": "...", "Description": "AI Discovered"}]`.
|
|
3. **Listen-Auflösung (Optimierung):** Kampagnen-Namen werden ohne zusätzliche API-Calls über das Pseudo-Feld `ProgID:DisplayText` (z.B. `SuperOffice:23:DisplayText`) direkt im Payload des Personen-Abrufs gelesen.
|
|
4. **Längenbegrenzung:** Da viele UDFs in SuperOffice standardmäßig auf 254 Zeichen begrenzt sind, wird das AI-Dossier (Summary) hart auf 132 Zeichen (+ "...") gekürzt, um 400er Fehler beim Update zu vermeiden.
|
|
5. **Docker Orchestrierung:** Der Wechsel auf `env_file: .env` in der `docker-compose.yml` stellt sicher, dass alle Services (CE + Connector) konsistent auf dieselben Mappings zugreifen.
|
|
|
|
#### E. Kampagnen-Steuerung (Multi-Template)
|
|
Der Company Explorer unterstützt nun den Parameter `campaign_tag`. Der Connector sendet den Namen des gewählten Listeneintrags (z.B. "First Contact") an den CE. Dieser liefert spezifische Texte aus der `MarketingMatrix`, sofern vorhanden (Fallback: "standard").
|
|
|
|
### 17.11 Marketing Matrix v3.5 (March 27, 2026): 10/10 Masterclass & Full Scale Generation
|
|
|
|
**Ziel:** Vollständige Befüllung der Matrix for alle 25 Branchen und 5 Personas nach dem Elite-Standard der Lead-Engine.
|
|
|
|
**Angewendete 10/10 Masterclass Regeln:**
|
|
1. **Red Sea Strategie ("Show, don't tell"):** Vermeidung von Floskeln ("strategischer Partner"). Wertbeweis durch fundiertes Branchenverständnis.
|
|
2. **Keine rhetorischen Fragen:** Fragezeichen sind in der Einleitung (`intro`) verboten (nur in `subject` erlaubt). Souveräne Feststellung statt unsicherer Frage.
|
|
3. **Feature-to-Benefit:** Technische Features werden in messbaren Nutzen übersetzt (z.B. "spart X Stunden Personalaufwand").
|
|
4. **Implicit Address:** Die Rolle des Empfängers wird nicht explizit genannt (kein "Für Sie als Leiter..."). Die Relevanz wird implizit durch den Fokus auf seine KPIs und Schmerzpunkte hergestellt.
|
|
|
|
---
|
|
|
|
## 19. External Lead Ingestion & Contact API (v3.5 - March 2, 2026)
|
|
|
|
**Kontext:** Automatisierte Verarbeitung von externen Lead-Quellen (Tradingtwins) direkt in den Company Explorer.
|
|
|
|
### 19.1 API-Erweiterung: Externer Kontakt-Sync
|
|
Um Kontakte von externen Tools (wie der Lead-Engine) ohne SuperOffice-Kontext zu übernehmen, wurde die API erweitert.
|
|
|
|
* **Neuer Endpunkt:** `POST /api/contacts`
|
|
* **Funktionalität:**
|
|
* Anlage von Personen-Stammdaten (Vorname, Nachname, E-Mail).
|
|
* **Automatisches Role-Mapping:** Der Endpunkt integriert den `RoleMappingService`. Eingehende Job-Titel (z.B. "CFO") werden automatisch gegen die interne Muster-Datenbank geprüft und der passenden Persona (z.B. "Wirtschaftlicher Entscheider") zugeordnet.
|
|
* **De-Duplizierung:** Existiert eine E-Mail bereits for ein Unternehmen, wird der Datensatz aktualisiert statt neu angelegt.
|
|
|
|
### 19.2 Standardisierung der Datenfelder
|
|
Zur Verbesserung der asynchronen Zusammenarbeit zwischen Lead-Engine und CE wurden die Feldnamen in der API-Antwort vereinheitlicht:
|
|
* **Branche:** `industry_ai` (Primärfeld for die KI-Klassifizierung).
|
|
* **Analyse:** `research_dossier` (Das vollständige KI-generierte Firmendossier).
|
|
|
|
### 19.3 Synchronisations-Workflow (Connector)
|
|
Der `company_explorer_connector.py` unterstützt nun den erweiterten Workflow:
|
|
1. `check_company_existence` (Suche via Name)
|
|
2. `create_company` (Anlage falls neu)
|
|
3. `create_contact` (Integration der Person inkl. Role-Mapping)
|
|
4. `trigger_discovery` / `trigger_analysis` (Asynchroner Start der Intelligence-Phase)
|
|
|
|
---
|
|
|
|
## 19. Zentraler Account-Matching-Service (März 2026)
|
|
|
|
**Ziel:** Zentralisierung der Duplikatsprüfung for alle Microservices (Lead-Engine, SuperOffice-Connector).
|
|
|
|
| Bereich | Details |
|
|
| :--- | :--- |
|
|
| **Technologie** | Python-Service im CE-Backend, SQLite-Lookup. |
|
|
| **Algorithmus** | Heuristische Fuzzy-Logik (v2.15). Bereinigt Rechtsformen, prüft Domains und wendet City-Penalties an. |
|
|
| **API** | `POST /api/match-company` |
|
|
| **Integration** | Lead-Engine (`book_slot`) prüft nun vor der Buchung gegen den CE-Bestand. |
|
|
|
|
**Vorteil:** Verhindert Dubletten in SuperOffice und ermöglicht die Wiederverwendung bestehender CRM-Datensätze for neue Leads.
|
|
|
|
|
|
|
|
## 20. Massendatenverarbeitung & Full-Sync (April 2026)
|
|
|
|
Um die ~16.000 Accounts aus SuperOffice effizient in das System aufzunehmen, wurde die Infrastruktur des Company Explorers massiv in Richtung **Batch Processing** skaliert. Der Einzel-Aufruf (Provisionierung) bleibt for neue Inbound-Leads bestehen, aber der Bestands-Sync wird nun über dedizierte Hochleistungs-Skripte abgewickelt.
|
|
|
|
### 20.1 Die "Landkarten-Strategie" (Import)
|
|
Anstatt die fehleranfällige und langsame SuperOffice REST API zu nutzen, um 16.000 Firmen abzufragen, basiert der Full-Sync auf einem initialen Excel/CSV-Export aus dem CRM.
|
|
* **Skript:** `import_csv_to_db.py`
|
|
* **Logik:** Liest die CSV, dedupliziert anhand der `crm_id` gegen den CE-Bestand und legt zehntausende Firmen in Sekundenbruchteilen im Status `IMPORTED` an.
|
|
* **Kontakte:** Ein Begleitskript (`import_contacts_csv.py`) importiert die Ansprechpartner, ignoriert "Luft-Personen" (ohne E-Mail/Namen) und führt bereits beim Import das Role-Mapping (KI-Regex) durch.
|
|
* **Update 10.04.2026:** Da die anfängliche Kontakt-Extraktion und Provisionierung unvollständige Namen (`null` oder nur Firmennamen statt echten Vor- und Nachnamen) erzeugt hatte, wurde ein dedizierter Fix-Lauf (`fix_names_from_csv.py`) mit einer neuen "CG_Personen_ROBO_neu.csv" durchgeführt. Hierdurch wurden **4.777 Kontakte repariert** (Vorname, Nachname, E-Mail, Gender und Position aktualisiert).
|
|
* Das Connector-Provisioning (`worker.py`) sowie die interne CE-API (`/ce/api/contacts/all`) wurden gehärtet, um Vornamen und Nachnamen zwingend zu verarbeiten und korrekt in der UI (`ContactsManager.tsx` / `ContactsTable.tsx`) auszugeben. Des Weiteren wurde das `is_primary` feld typensicher gemacht (`Optional[bool] = False`), um "500 Internal Server Errors" beim Aufruf noch unvollständiger Kontakte zu vermeiden.
|
|
|
|
### 20.2 Batch-Scraping (Phase 1)
|
|
Ein neues asynchrones Skript löst den synchronen Single-Scraper ab.
|
|
* **Skript:** `batch_scrape.py`
|
|
* **Technologie:** Multi-Threading gepaart mit einem zweistufigen Fallback.
|
|
* **Fallback:** Scheitert das Standard-`requests`-Scraping (z.B. bei modernen SPAs), wird im Hintergrund ein headless **Playwright (Chromium)** Browser gestartet, der die Seite rendert und den echten `inner_text` extrahiert.
|
|
* **Ziel-Status:** `DISCOVERED`
|
|
|
|
### 20.3 Batch-Enrichment (Phase 2)
|
|
Eine radikale Optimierung der KI-Token-Nutzung.
|
|
* **Skript:** `batch_enrich.py`
|
|
* **Logik (Klassifizierung):** Anstatt die teuren System-Prompts (alle 25 Branchen-Definitionen) for jede firma neu an Gemini zu senden, fasst das Skript bis zu **50 Firmen in einen einzigen LLM-Aufruf** zusammen. Die KI antwortet mit einem sauberen JSON-Mapping (ID -> Branche).
|
|
* **Logik (Qualität):** Erst *nach* der Batch-Klassifizierung werden die komplexen "Masterclass-Opener" und Metriken individuell (aber parallelisiert) berechnet, um Halluzinationen bei langen Texten zu vermeiden.
|
|
* **Ziel-Status:** `ENRICHED`
|
|
|
|
### 20.4 Massen-Rückspiel nach SuperOffice (Phase 3)
|
|
Ein dediziertes Skript im Connector pusht die Ergebnisse in das CRM.
|
|
* **Skript:** `mass_sync_to_so.py` (In Planung for die nächste Sitzung, basierend auf `dry_sync_safe.py`).
|
|
* **Logik:** Liest über einen Mount direkt die SQLite-Datenbank des CE (Tabelle `companies`).
|
|
* **Atomic PATCH (Neu evaluiert am 08.04.2026):**
|
|
* **Vertical (UDF 83):** Wird geschrieben (`[I:xxxx]`), sofern im CRM noch leer.
|
|
* **Basisdaten (Website, Adresse):** "Mensch vor KI" - werden nur ergänzt, wenn sie in SuperOffice komplett leer sind. Kein Überschreiben bestehender Daten.
|
|
* **AI Summary (Dossier):** Da UDFs (z.B. UDF 84) in der Länge stark limitiert sind (max 254 Zeichen), wird das vollständige KI-Dossier nun als "Append" in das feld `Description` (in der UI: "InternalNotes" / "Notiz") des Accounts (ContactEntity) geschrieben. Der Patch häng das Dossier mit Zeitstempel an bestehende Notizen an, um Historie (z.B. Leadinfo-Logs) nicht zu überschreiben. Dies umgeht den 400er API Fehler beim direkten Patch auf `InternalNotes`.
|
|
* **Echtzeit-Sicherheit:** Der Connector muss sicherstellen, dass er sich selbst korrekt identifiziert, um Webhook-Echos (Endlosschleifen) beim Patchen von 17.000 Accounts zu vermeiden.
|
|
|
|
---
|
|
|
|
## 21. Meilenstein: 96.8% Enrichment & Discovery-Abschluss (08.04.2026)
|
|
|
|
Der Prozess der KI-gestützten Datenanreicherung (Enrichment) for den Bestandsabgleich von ca. 17.500 Accounts aus SuperOffice wurde nahezu abgeschlossen.
|
|
* **Discovery:** Durch Erneuerung des SerpAPI-Tokens wurden die verbleibenden Firmen gescraped.
|
|
* **Enrichment:** Die Batch-Verarbeitung (`batch_enrich.py`) lief mit ca. 11 Accounts pro Minute und hat 16.963 Firmen (96.8%) erfolgreich klassifiziert und mit einem Dossier versehen.
|
|
* **Nächster Schritt:** Ausführung des sicheren Massen-Rückspiels (`mass_sync_to_so.py`) in der nächsten Entwicklungssitzung, um die angereicherten Daten (insbesondere das Vertical und das an die `Description` angehängte Dossier) in SuperOffice sichtbar zu machen.
|
|
|
|
---
|
|
|
|
## 22. Produkt-Katalog Integration & UI Refactoring (März 2026)
|
|
|
|
**Kontext:** Ablösung der alten, rein konzeptionellen "Robotics Categories" durch einen echten, synchronisierten Produktkatalog aus Notion.
|
|
|
|
### 20.1 Datenmodell-Erweiterung
|
|
* **Tabelle `products` (NEU):** Speichert konkrete Robotik-Modelle (z.B. "HolaBot", "Phantas") inkl. Kurzbeschreibung, Leistung und einem `is_own_product`-Flag.
|
|
* **Tabelle `product_category_assoc` (NEU):** Many-to-Many Verknüpfung zwischen Produkten und den konzeptionellen Produktkategorien (`robotics_categories`).
|
|
* **Tabelle `robotics_categories` (Update):** Bereinigt um hartkodierte Legacy-Einträge. Spiegelt nun 1:1 die 7 echten "Product Categories" aus Notion wider (inkl. der Felder `Text` als Description und `Constrains` als Reasoning Guide).
|
|
|
|
### 20.2 Notion-Synchronisation
|
|
* Das neue Skript `sync_notion_products.py` löst die alte, fehlerhafte Logik in `sync_notion_to_ce_enhanced.py` ab, die echte Produkte fälschlicherweise als Kategorien importiert hatte.
|
|
* **Auswirkung auf Matrix-Generierung:** Die `MarketingMatrix` profitiert direkt davon. Wenn eine Industrie auf eine `primary_category_id` (z.B. "Service Roboter") verweist, wird nun der korrekte Notion-Text ("Serviceroboter zum Transport von Tabletts...") als kontextuelle Grounded-Truth an das Sprachmodell übergeben.
|
|
|
|
### 20.3 UI Refactoring (Settings)
|
|
* Die überladene Top-Navigation in den "Settings" (`RoboticsSettings.tsx`) wurde durch ein sauberes, breiteres **Sidebar-Layout** (`max-w-6xl`) ersetzt.
|
|
* Ein neuer Reiter **"Products"** wurde hinzugefügt, der alle synchronisierten Produkte inkl. Zuordnung und Badge ("OWN PRODUCT") anzeigt.
|
|
|
|
---
|
|
|
|
## 23. Proaktive CRM-Synchronisation & Personen-Level Automatisierung (April 2026)
|
|
|
|
Um die Latenz zwischen Lead-Eingang und CRM-Sichtbarkeit zu minimieren und die Datenqualität auf Personenebene zu erhöhen, wurde die Provisioning-Workflow erweitert.
|
|
|
|
### 23.1 Proaktiver Rückkanal zum Connector
|
|
Anstatt darauf zu warten, dass der Connector den Status einer Recherche pollt, meldet der Abschluss der Analyse nun proaktiv.
|
|
* **Mechanismus:** Sobald der Status einer firma auf `ENRICHED` springt, sendet der CE einen Ping an den neuen API-Endpunkt des Connectors (`/connector/api/sync-from-ce`).
|
|
* **Vorteil:** Die angereicherten Daten (Website, Vertical, KI-Dossier) werden ohne Verzögerung in die SuperOffice-UDFs zurückgeschrieben.
|
|
|
|
### 23.2 Personen-Anlage bei Bestandsfirmen
|
|
Der Workflow wurde so gehärtet, dass keine manuellen Eingriffe mehr nötig sind, wenn ein bekannter Account einen neuen Ansprechpartner sendet.
|
|
* **Logik:** Die Provisioning-API prüft nun gezielt, ob for einen Lead zwar eine `so_contact_id` (Firma), aber keine `so_person_id` (Person) existiert.
|
|
* **Aktion:** In diesem Fall legt das System die Person automatisch über den Connector in SuperOffice an und verknüpft sie mit der bestehenden firma.
|
|
|
|
### 23.3 Infrastruktur-Härtung (Routing & Retries)
|
|
* **Routing-Fix:** Die Kommunikation zwischen den Diensten wurde stabilisiert (Beseitigung von 405-Routingfehlern im internen Netzwerk).
|
|
* **Retry-Logic:** Jobs in der Connector-Queue, die auf den CE warten, werden nun mit einem sicheren Backoff-Verfahren (`next_try_at`) verarbeitet, ohne reguläre CRM-Webhooks zu blockieren.
|
|
|
|
## 24. Anrede-Logik & Gender-Detection (April 2026)
|
|
|
|
Um eine professionelle und personifizierte Kundenansprache ("Sehr geehrter Herr...") über alle Kanäle hinweg zu gewährleisten, wurde eine durchgängige Anrede-Logik implementiert.
|
|
|
|
### 24.1 Automatische Gender-Erkennung
|
|
Leads, die über die Lead-Engine (TradingTwins, Onlineformular) ohne explizite Anrede eingehen, werden nun automatisch klassifiziert.
|
|
* **Technologie:** Zweistufiges Verfahren in `helpers.py`.
|
|
1. **Lokal:** `gender-guesser` prüft den Vornamen gegen eine interne Datenbank.
|
|
2. **Fallback:** Bei unsicheren Ergebnissen wird die **Genderize API** (via `.env` Key) abgefragt.
|
|
* **Mapping:** "male" -> "Herr" (männlich), "female" -> "Frau" (weiblich).
|
|
|
|
### 24.2 End-to-End Datenfluss
|
|
1. **Ingestion:** `ingest.py` extrahiert die Anrede oder stößt die Erkennung an.
|
|
2. **CRM-Sync:** Der `connector-superoffice` empfängt die Anrede und schreibt sie in das SuperOffice-Feld `Mrmrs`.
|
|
3. **CE-Mapping:** Der Company Explorer empfängt die Anrede via Provisioning-API und mappt sie auf das interne feld `gender`, welches die Tonalität der KI-Textgenerierung steuert.
|
|
4. **Kommunikation:** Sowohl `manager.py` (Vorschau) als auch die `mailing-engine` nutzen die gespeicherten Metadaten (Nachname + Anrede) for eine perfekte Begrüßungszeile.
|
|
|
|
## 🤖 Status-Update (2026-03-14 14:05 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:45
|
|
|
|
Arbeitszusammenfassung:
|
|
[2ea88f42] Infrastruktur & Role-Matching stabilisiert: 1. CSV-Export for Job-Pattern implementiert. 2. Alle DBs auf Host-Bind-Mounts (./data/) migriert, um Backup-Verluste zu verhindern und Direktzugriff (SQLite) zu ermöglichen. 3. Produktion-DBs aus alten Volumes erfolgreich gerettet. 4. KI-Klassifizierung gehärtet (behebt Gemini JSON-Fehler und Escaping-Bugs) sowie Prompt mit Notion-Rollenbeschreibungen angereichert. 5. Kritische Docker-Workflows for VM docker1 in GEMINI.md dokumentiert.
|
|
```
|
|
|
|
|
|
## 21. Persistence Mastery & Data Rescue (März 2026)
|
|
|
|
Ein kritischer Meilenstein for die Betriebssicherheit wurde erreicht: Die vollständige Entkopplung der Daten vom flüchtigen Container-Speicher.
|
|
|
|
### 21.1 Die "Lead-Engine" Datenrettung
|
|
* **Problem:** In der Lead-Engine wurden Daten fälschlicherweise in `/app/lead-engine/data/` (relativ zum Code) geschrieben. Da der Bind-Mount in Docker Compose auf `/app/data` zeigte, landeten die realen Daten im flüchtigen Container-Layer und wären bei einem Update verloren gegangen.
|
|
* **Lösung:**
|
|
1. Manuelle Rettung der `leads.db` via `docker exec` und `cp`.
|
|
2. Code-Härtung in `db.py`: Umstellung auf **absolute Pfade** (`/app/data/`).
|
|
* **Erkenntnis:** Python-Code in Docker-Containern sollte Datenbankpfade niemals relativ (`__file__`) berechnen, wenn diese persistent gemountet werden sollen. Nutze immer den Pfad, der in der `docker-compose.yml` als `Destination` definiert ist.
|
|
|
|
### 21.2 Status Quo: Alle Datenbanken sicher
|
|
Alle drei Kern-Dienste sind nun verifiziert "Host-Safe":
|
|
* **Company Explorer:** `./data/company_explorer/` -> `/data/` (OK)
|
|
* **Connector:** `./data/connector_superoffice/` -> `/data/` (OK)
|
|
* **Lead-Engine:** `./data/lead_engine/` -> `/app/data/` (KORRIGIERT & SICHER)
|
|
|
|
## 22. Mensch vor KI: Diskrepanz-Erkennung & CRM-Schutz (März 2026)
|
|
|
|
Um zu verhindern, dass manuell in SuperOffice (SO) gepflegte Daten durch KI-Recherchen (CE) überschrieben werden (Endlosschleifen), wurde das "Mensch vor KI"-Prinzip tief in die Architektur integriert.
|
|
|
|
### 22.1 Das "Double Truth" Modell
|
|
Die `companies`-Tabelle speichert nun zwei Datensätze pro Unternehmen:
|
|
1. **Golden Record (KI):** `name`, `website`, `street`, `vat_id` etc. (Die von der KI erforschten Daten).
|
|
2. **CRM Snapshot (SO):** `crm_name`, `crm_website`, `crm_street`, `crm_vat` etc. (Die exakte Kopie der SuperOffice-Eingaben).
|
|
|
|
### 22.2 Die `is_discrepant` Logik (`core_utils.py`)
|
|
Eine intelligente Vergleichslogik entscheidet bei der Provisionierung, ob KI- und CRM-Daten signifikant voneinander abweichen.
|
|
* Sie ist tolerant gegenüber Schreibweisen: "Str." vs. "Straße", Umlaute (ä vs. ae) und ignoriert fehlende `https://`-Präfixe.
|
|
* Nur harte Abweichungen (z.B. "Luisenstrasse 49" vs. "Luisenring 49") triggern das Flag.
|
|
|
|
### 22.3 Der Workflow (SuperOffice UDFs)
|
|
1. Wenn der CE eine Abweichung feststellt, setzt er das `discrepancy_detected` Flag in der API-Response auf `True`.
|
|
2. Der **Connector** aktiviert daraufhin die Checkbox **"Abweichung erkannt" (`SuperOffice:90`)** in SuperOffice. Er überschreibt manuell befüllte Felder (wie die Adresse) in SuperOffice nicht mehr.
|
|
3. Der Vertriebler sieht die Warnung und kann die Daten manuell prüfen.
|
|
4. Aktiviert der Vertriebler in SO die Checkbox **"Abweichung ignorieren" (`SuperOffice:91`)**, wird die Warnung im CRM wieder gelöscht und der CE überschreibt die CRM-Daten weiterhin nicht.
|
|
5. **UI:** Im CE-Dashboard ("Inspector") werden der CRM-Snapshot und der Golden Record übersichtlich im "Side-by-Side View" dargestellt, flankiert von einem gelben Alert, falls das Flag aktiv ist.
|
|
|
|
## 23. Discovery 2.0: Multi-Source Website-Suche (März 2026)
|
|
|
|
Ein massives Upgrade der `DiscoveryService`-Klasse löste das Problem, dass Websites von lokalen Organisationen (z.B. "Bonner Werkstätten") von Google oft nicht in den Standard-Suchergebnissen geliefert wurden.
|
|
|
|
**Optimierungen:**
|
|
1. **Multi-Source Extraktion:** SerpAPI-Antworten werden nun vollumfänglich ausgewertet. Links werden nicht nur aus den `organic_results` gezogen, sondern auch aus dem **Knowledge Graph** und den lokalen Google Maps Treffern (`local_results`).
|
|
2. **Short-Name Fallback:** Wenn ein Firmenname aus mehr als 3 Wörtern besteht, wird ein zweiter Suchdurchlauf nur mit den ersten 3 Wörtern initiiert, um Social-Media-Junk bei zu spezifischen Suchanfragen zu umgehen.
|
|
3. **Blacklist-Härtung:** Recruiting-Portale (`softgarden.io`, `personio.de`) wurden der Blacklist hinzugefügt, um "False Positives" zu verhindern.
|
|
|
|
## 🤖 Status-Update (2026-03-15 08:30 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 02:30
|
|
|
|
Arbeitszusammenfassung:
|
|
[32288f42] Demo 15 Anschreiben (V5 - Expert Level):
|
|
1. Multi-Agent Pipeline implementiert (Analyst, Architekt, Psychologe, Copywriter) with integriertem CE-Sync & Polling.
|
|
2. Hochgradig personalisierte E-Mails generiert, die individuelle Dossier-Fakten nutzen.
|
|
3. Automatisches Data-Rewriting eingeführt (Ranges wie '301-1000' -> 'Bis 1.000 m2').
|
|
4. 'Influencer' Persona in Notion geschärft.
|
|
5. Kritische Datenrettung & Pfad-Korrektur for 'leads.db' zur Sicherstellung der Host-Persistenz abgeschlossen.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-03-24 15:58 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:05
|
|
|
|
Arbeitszusammenfassung:
|
|
[32d88f42] Userpflege Maria Ziegler: Associate ID 510 und Shortname 'RMZI' zur ROBOPLANET_WHITELIST in 'connector-superoffice/config.py' hinzugefügt. Dies stellt sicher, dass ihre Bearbeitungen im SuperOffice-Mandanten Cust26720 vom System als Roboplanet-Aktionen erkannt und verarbeitet werden.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-03-25 15:06 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:46
|
|
|
|
Arbeitszusammenfassung:
|
|
[2f988f42] Diskrepanz-Logik & Discovery-Upgrade:
|
|
|
|
1. Mensch vor KI: Intelligente 'is_discrepant'-Logik implementiert, die CRM-Daten schützt und Abweichungen (Umlaut-fuzzy, Str.-Normalisierung) erkennt. Flagging via 'SuperOffice:90' (Abweichung erkannt) und Respektierung von 'SuperOffice:91' (Ignorieren).
|
|
|
|
2. UI-Modernisierung: Side-by-Side View im Inspector for CRM vs. CE Daten inkl. Alert-Box bei Diskrepanzen. Spinner-Fix for Fehlerstatus.
|
|
|
|
3. Discovery 2.0: Website-Suche massiv verbessert durch Multi-Source Auswertung (Organic + Local/Maps + Knowledge Graph) sowie Kurznamen-Fallback. Löst Problem bei lokalen Organisationen (z.B. Bonner Werkstätten).
|
|
|
|
## 24. Reliability & Anti-Spam Architecture (März 26, 2026)
|
|
|
|
Ein massiver Fokus auf Systemstabilität, um "Silent Failures" und Endlosschleifen im Produktivbetrieb zu eliminieren.
|
|
|
|
### 24.1 Connector Echo-Prävention & Watchdog
|
|
* **Das Echo-Problem:** Wenn der Connector Daten in SuperOffice aktualisierte, löste dies sofort einen neuen Webhook aus, was zu einer Endlosschleife (z.B. > 55.000 Aufrufe bei Rädlog) führte.
|
|
* **Lösung:** Der Connector prüft nun bei jedem Webhook die `ChangedByAssociateId`. Stimmt diese mit der eigenen Identität des Connectors überein, wird der Webhook als Echo verworfen (`SKIPPED`).
|
|
* **Watchdog:** Ein dedizierter Hintergrund-Thread (`worker.py`) überwacht die SQLite-Queue. Bei Queue-Backups (>100), Spam-Wellen (>150 in 15 Min) oder Error-Spikes feuert er sofort einen Alarm in einen dedizierten Teams-Kanal (`TEAMS_WATCHDOG_WEBHOOK_URL`).
|
|
|
|
### 24.2 Discovery 2.1: Der "Dennerle"-Fix (Legal Forms)
|
|
* **Problem:** Die rigorose Bereinigung von Rechtsformen (z.B. "Dennerle GmbH" -> "dennerle") durch den CE führte dazu, dass SerpAPI for Firmen, deren Namen auch generische (Aquaristik-)Begriffe sind, nur YouTube-Videos oder Facebook-Seiten ausspuckte. Das führte zu `DISCOVERY_FAILED`.
|
|
* **Lösung:** Der `DiscoveryService` sucht nun zweigleisig: Er übergibt Google sowohl den bereinigten Namen als auch den **exakten, unbereinigten Namen** (inkl. "GmbH") als Fallback-Query. Dadurch werden offizielle Unternehmens-Websites wieder verlässlich auf Position 1 gefunden.
|
|
|
|
|
|
## 🤖 Status-Update (2026-03-26 13:01 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:24
|
|
|
|
Arbeitszusammenfassung:
|
|
[2f388f42] Report mistakes feature completion: UI enhancements, DB application, and AI analysis protection.
|
|
|
|
1. Frontend (Inspector): Added report mistake flag buttons directly next to data fields (Website, Industry, Address, VAT, Metric). Form now pre-fills current values and includes a 'Quote' field.
|
|
|
|
2. Backend (App): Update API now maps APPROVED mistakes (e.g. 'street' -> company.street) and automatically applies them to the company record.
|
|
|
|
3. Backend (Classification): 'classify_company_potential' now loads approved mistakes and strictly prevents overwriting human-verified data (e.g., if a user fixed the revenue, the AI won't overwrite it).
|
|
|
|
4. Frontend (Table/Inspector): Fixed a critical 'Invalid URL' crash when loading non-http URLs via a safe 'getDisplayUrl' helper.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-03-27 13:25 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:07
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ **Marketing Matrix Full Scale (v3.5) abgeschlossen:** Die Matrix wurde vollständig for alle 25 Branchen x 5 Personas befüllt (125 Einträge).
|
|
|
|
✦ **Masterclass-Integration:** Übernahme der Elite-B2B-Copywriting-Regeln aus der Lead-Engine (keine rhetorischen Fragen, Feature-to-Benefit, 'Show, don't tell').
|
|
|
|
✦ **Strategische Resilienz:** Umstellung auf implizite Adressierung der Empfänger (Verzicht auf Rollennennung wie 'Für Sie als...'), um Targeting-Reibungsverluste zu minimieren.
|
|
|
|
✦ **Notion Sync Härtung:** Fehlerbehebung beim Property-Mapping ( statt ) und der Authentifizierung in den Sync-Skripten. Alle Industries, Personas und Products sind nun fehlerfrei synchronisiert.
|
|
|
|
✦ **Strategy Switch:** Automatisierte Priorisierung von Sekundärprodukten (z.B. Transport/Service) for operative Rollen in spezifischen Branchen erfolgreich verifiziert.
|
|
```
|
|
|
|
## 25. Bestandsabgleich SuperOffice Sync (März 30, 2026)
|
|
|
|
Ein kritischer Vorbereitungsschritt vor dem Massen-Import neuer SuperOffice-Daten in den Company Explorer wurde abgeschlossen, um Datenmüll zu verhindern.
|
|
|
|
### 25.1 Identifikation & Lösung interner Duplikate
|
|
* **Ausgangslage:** In der CE-Datenbank existierten 263 Accounts, wovon ca. 63 noch nicht mit einer SuperOffice `crm_id` verknüpft waren (oft generiert durch Web-Leads).
|
|
* **Matching-Ergebnis:** Durch ein Python-Skript (`match_ce_to_so.py`) konnten 46 dieser Accounts durch exakten Namens- oder Domain-Abgleich eindeutig in SuperOffice gefunden werden.
|
|
* **Das Duplikat-Problem:** Der Versuch, diese 46 Accounts mit der `crm_id` zu aktualisieren, deckte 29 interne Duplikate im CE auf. Das Schema war immer gleich:
|
|
* *Account A:** Inbound-Lead (ohne `crm_id`), aber mit echten Kontakt-Details (E-Mail, Name) und KI-Dossier/Opener.
|
|
* *Account B:* Sync-Account aus SO (mit `crm_id` and `so_person_id`), aber oft ohne Kontakt-E-Mail ("Ghost-Contact").
|
|
* **Lösung (Merge):** Ein intelligentes Merge-Skript (`merge_ce_duplicates.py`) hat diese 29 Paare zusammengeführt. Die wertvollen Inbound-Kontakte und KI-Dossiers wurden auf die Accounts mit CRM-ID transferiert, und die verwaisten Accounts wurden gelöscht.
|
|
|
|
### 25.2 Aktueller Stand
|
|
Die CE-Datenbank ist nun dedupliziert und zu 100% konsistent.
|
|
* **235 Firmen** insgesamt.
|
|
* **216 Firmen** sicher mit SuperOffice verknüpft.
|
|
* Das Fundament for den Phase-3-Massenimport (ca. 16.000 Accounts) ist damit sauber gelegt.
|
|
|
|
---
|
|
|
|
## 26. CRM Activity Tracking & "Next Action" Logik (März 31, 2026)
|
|
|
|
Um eine hoch-effiziente Filterung for die Marketing-Automatisierung zu ermöglichen (z.B. "Schreibe niemanden an, der gestern telefoniert hat" oder "Blockiere Leads mit offener Wiedervorlage"), wurde eine bidirektionale Activity-Tracking Strategie entwickelt.
|
|
|
|
### 26.1 Strategie: "Thin CRM, Smart Engine"
|
|
Anstatt das CRM mit tausenden API-Calls nach Aktivitäten zu durchsuchen, nutzt das System **dedizierte User Defined Fields (UDFs)** in SuperOffice als Caches. Diese UDFs werden von SuperOffice CRMScripts in Echtzeit aktualisiert. Der Company Explorer (`bulk_sync_superoffice.py`) muss somit pro Datensatz nur 2-3 Felder lesen.
|
|
|
|
### 26.2 Angelegte UDFs in SuperOffice
|
|
|
|
| Entität | UDF Label | Typ | Zweck | ProgID (Beispiel) |
|
|
| :--- | :--- | :--- | :--- | :--- |
|
|
| Person | Last Contact (Email) | Date | Jüngstes Dokument mit Endung .msg/.eml oder "mail" im Betreff. | `SuperOffice:25` |
|
|
| Person | Last Contact (Phone) | Date | Jüngster Termin mit Task-ID 80, 143, 6, 24 oder "Telefon/Angebot" im Text. | `SuperOffice:26` |
|
|
| firma | Last Contact (Email) | Date | (Wird analog zur Person implementiert) | `SuperOffice:92` |
|
|
| firma | Last Contact (Phone) | Date | (Wird analog zur Person implementiert) | `SuperOffice:93` |
|
|
|
|
### 26.3 Historischer Backfill (CRMScript)
|
|
Um den Bestand (5.500+ Personen) initial mit den korrekten historischen Werten zu befüllen, wurde folgendes, robustes CRMScript in SuperOffice ausgeführt. Es nutzt eine Kombination aus Task-ID-Matching und Text-Fallback-Heuristik.
|
|
|
|
### 26.4 Offene ToDos & Nächste Schritte
|
|
|
|
* **[ERLEDIGT] "Next Planned Activity" UDFs anlegen:** In SuperOffice wurden zwei weitere UDFs pro Entität angelegt, um offene, geplante oder überfällige Aktivitäten zu speichern (z.B. `Next Contact Date` und `Next Contact Type`). Ebenso for `Last Activity Type`.
|
|
* **[ERLEDIGT] CRMScript for "Next Activity":** Bereitstellung von `next_activity_backfill.crmscript` zur Identifikation offener Aufgaben (`status IN (1, 2)`) in der Zukunft sowie Abruf des Typs der letzten historischen Aktivität (`status = 3`).
|
|
* **[ERLEDIGT] Python-Sync erweitern:** Das Skript `bulk_sync_superoffice.py` wurde erweitert, um UDFs 27, 28, 29 (Person) und 94, 95, 96 (Account) auszulesen und in die SQLite-Datenbank (via ORM UPSERT ohne Duplikate) zu übertragen.
|
|
* **[ERLEDIGT] Event-Trigger (Realtime):** Skripte `trigger_appointment_saved.crmscript` und `trigger_document_saved.crmscript` bereitgestellt. Diese können in SuperOffice in den CRMScripts unter "Event Scripts" for `Appointment - After Save` und `Document - After Save` hinterlegt werden, um die UDFs bei jeder Kalender/Aktivitäts-Änderung in Echtzeit ohne Batch-Lauf zu aktualisieren.
|
|
|
|
## 27. Sales Activity Dashboard (Phase 1) - April 2026
|
|
|
|
Um die kaufmännische Pipeline transparent zu machen und den "Blindflug" nach der Angebotserstellung zu beenden, wurde die GTM-Engine um ein echtes Sales Dashboard erweitert.
|
|
|
|
### 27.1 Architektur: Integration in den Company Explorer
|
|
Anstatt einen isolierten Microservice zu bauen, wurde die Verkaufs-Entität (`sales`) als native Tabelle in das "Gehirn" des Company Explorers (`companies_v3_fixed_2.db`) integriert.
|
|
* **Vorteil:** Dies ermöglicht in Phase 2 nahtloses Cross-Selling-Tracking (welche Branche kauft welches Produkt) und den direkten Absprung aus dem Sales Dashboard in das KI-Dossier einer firma.
|
|
* **Backend:** Ein neuer FastAPI-Router (`/ce/api/dashboard/kpis`) aggregiert Live-Daten aus die `sales` tabelle und der gemounteten `leads.db`.
|
|
|
|
### 27.2 Frontend: Das "Executive View" Dashboard
|
|
Das React-Frontend des CE wurde um einen dedizierten Reiter **"Pipeline & Sales"** erweitert.
|
|
* **Technologie:** Pures TailwindCSS for interaktive, performante Balkendiagramme (Win-Rates) ohne externe Abhängigkeiten (`npm install` Konflikte vermieden).
|
|
* **Features:**
|
|
* Globale Datums-Filter (Q1, Q2, 30 Tage, Gesamt).
|
|
* Interaktiver Drilldown: Klick auf einen Sales Manager oftnet eine detaillierte Tabelle aller gewonnenen/verlorenen Angebote inkl. exaktem Entscheidungsdatum.
|
|
|
|
### 27.3 Data Breakthrough: SKU-Level Analytics (Phase 2 Foundation)
|
|
* **Das Problem:** Das offizielle SuperOffice Quote-Modul (Angebote) antwortet in der REST/OData-API for diesen Mandanten konsistent mit 500er Fehlern (`"No registered plugin found for archive Quote"`).
|
|
* **Die Lösung (Legacy Archive API):** Durch intensive Reverse-Engineering-Tests wurde bewiesen, dass die exakten Angebotspositionen (Produkte, Implementierung, Zubehör) über den Legacy-Pfad `GET /Archive/QuoteLine` abrufbar sind.
|
|
|
|
### 27.4 Sales Dashboard (Phase 1.5) - April 20. 2026
|
|
Das Sales Dashboard wurde massiv in Richtung operativer Nutzbarkeit for die Vertriebsleitung erweitert.
|
|
|
|
* **"Mensch vor KI" in UI:** Modals wurden durch ein Side-by-Side Layout ersetzt. Ein Klick auf einen Manager oder ein Vertical oftnet die Detail-Tabelle direkt rechts daneben.
|
|
* **Interaktiver Sales Funnel:** Ein filterbares (nach Manager) Funnel-Diagramm zeigt das Volumen und die Anzahl der Deals pro Stufe.
|
|
* **Rote Liste (Overdue):** Ganz oben thront nun eine Warn-Tabelle for Deals, deren "Entscheidungsdatum" (`sale_date`) abgelaufen ist. Sie summiert das "riskierte Volumen" und drängt zum Nachfassen.
|
|
* **Time-to-Sale (API Data Mining):** Da historische CSV-Exporte kein Anlagedatum besaßen, wurde ein Hintergrund-Job (`sync_sale_dates.py`) geschrieben. Dieser zog for 2.485 Angebote das `registeredDate` aus der SuperOffice Archive API. Das Dashboard berechnet nun live die echte Time-to-Sale (Avg. Days).
|
|
* **Deep Links (CRM):** In jeder Tabelle gibt es nun einen Link-Button, der das exakte Angebot in SuperOffice (`default.aspx?sale?sale_id=XYZ`) in einem neuen Tab öffnet.
|
|
|
|
### 27.5 Sales Dashboard Echtzeit-Sync & UX Upgrade (April 27, 2026)
|
|
Die Sales-Pipeline wurde von einem Batch-getriebenen Prozess auf ein Echtzeit-System (Live via Webhook) umgestellt und die UX for Desktop-Nutzer optimiert.
|
|
|
|
* **Echtzeit Webhook (Sales):** Der bestehende SuperOffice-Webhook (ID 10) wurde um die Events `sale.created` und `sale.changed` erweitert.
|
|
* **Live-Push API:** Der Connector-Worker fängt diese Sales-Events nun ab, übersetzt den Status (z.B. "Sold" -> "Verkauft") und pusht die Daten über den neuen API-Endpunkt `/ce/api/sales/sync` in Sekundenbruchteilen direkt in die `sales` Tabelle des Company Explorers.
|
|
* **360° Pipeline ("Leads ohne Angebot"):** Ein neues Panel im Dashboard zeigt nun alle verifizierten Leads aus der Lead-Engine an, for die *noch kein* Angebot in SuperOffice existiert. Sobald ein Angebot erstellt wird, verschwindet der Lead automatisch aus der Ansicht.
|
|
* **Activity Badges & Click-to-Call:** Die Tabelle zeigt nun die letzten Kontaktpunkte (📍 Vor-Ort, 📞 Telefon, ✉️ E-Mail) als visuelle Badges an. Das Feld `last_meeting_onsite` wurde dafür als Standardfeld in der CE-Datenbank implementiert. Telefonnummern aus Inbound-Leads werden als direkte `tel:` Links angezeigt.
|
|
* **Full-Width UI & Global Filter:** Das Dashboard wurde von der 1280px-Limitierung befreit und nutzt nun bis zu 1800px (4K-Ready). Ein neuer globaler "Manager Filter" oben rechts steuert ab sofort alle Widgets (Trichter, Win-Rates, Rote Liste) dynamisch aus dem Backend heraus.
|
|
|
|
### 27.6 Sales Dashboard: Vertriebskanäle & Omnipräsente Call-Links (April 28, 2026)
|
|
Die Datenqualität und Nutzbarkeit des Dashboards wurde durch präzisere Zuordnungen und allgegenwärtige Kontaktmöglichkeiten weiter gehärtet:
|
|
|
|
* **Echte Vertriebskanäle:** Die Aggregation der Kanäle basiert nun strikt auf dem SuperOffice-Feld `lead_source` (Vertriebskanal, z.B. "Neukundenvertrieb RP"), welches automatisch von internen System-Präfixen (`GE:"..."`) bereinigt wird.
|
|
* **Omnipräsente Call-Links:** Durch einen gehärteten Cross-Reference-Join mit der `leads.db` (String-Matching) werden nun sowohl Festnetz- (`phone`) als auch Mobilnummern (`mobile`) in das Dashboard geladen. Diese erscheinen als direkte "Click-to-Call"-Icons in *allen* Detail-Tabellen des Dashboards.
|
|
* **Frontend-Caching (Deployment):** Ein systematisches Docker-Caching-Problem wurde dokumentiert. Frontend-Änderungen (React) erfordern bei Deployments auf der Produktionsmaschine nun zwingend den Build-Parameter `--no-cache`, um das Ausliefern veralteter JavaScript-Bundles zu verhindern.
|
|
|
|
## 28. Red List Burndown Tracking (April 2026)
|
|
|
|
Um den Erfolg des GTM-Tools bei der Pipeline-Reinigung messbar zu machen, wurde ein automatisches Tracking-System for die "Rote Liste" (überfällige Deals) implementiert.
|
|
|
|
### 28.1 Funktionsweise
|
|
* **Persistence:** Neue Tabelle `daily_kpi_snapshots` speichert täglich Volumen und Anzahl der überfälligen Deals.
|
|
* **Automation:** Das Skript `backend/scripts/snapshot_kpis.py` berechnet die Werte (Filter: `sale_date < TODAY`).
|
|
* **Trend-Analyse:** Das Dashboard vergleicht den aktuellen Stand mit dem Vortag und visualisiert den "Burndown" (Abbau) als farblichen Trend-Indikator.
|
|
|
|
### 28.2 Erfolgsnachweis (Start-Baseline)
|
|
* **27.04.2026:** Baseline exakt nach Screenshot gesetzt (**5.164.155 €**).
|
|
* **29.04.2026:** Aktueller Live-Stand verifiziert den massiven Rückgang auf **3.570.368 €**.
|
|
* **KPI-Erfolg:** Ein Burndown von **-1.593.787 €** in nur 48 Stunden (davon ca. 613k € durch belegbare Abschlüsse).
|
|
|
|
## 29. Controlling & Activity Analytics (Phase 1) - April 2026
|
|
|
|
Um die lücke zwischen operativen Vertriebsdaten (Pipeline) und der Steuerung durch das Controlling zu schließen, wurde das Sales Dashboard um eine umfassende Aktivitäts-Analyse ("Activity Tracking") erweitert.
|
|
|
|
### 29.1 Die Datenbank-Erweiterung (`activities`)
|
|
Das System wurde um eine dedizierte Tabelle `activities` erweitert. Diese speichert nicht nur reine Metadaten, sondern dank der `Appointment`-Entität aus SuperOffice auch die wertvollen inhaltlichen Rohdaten.
|
|
* **Inhalte:** Die felder `text_short` (Betreff), `text_agenda` und insbesondere `text_internal_notes` erfassen die vollständigen E-Mail-Bodys und Telefonnotizen.
|
|
|
|
### 29.2 Die Hybride Datenbeschaffung
|
|
* **Historischer Backfill:** Über 12.000 historische Aktivitäten wurden über einen initialen, sauberen CSV-Export aus SuperOffice in die SQLite-Datenbank gepumpt, um die API-Limits zu umgehen.
|
|
* **Echtzeit-Synchronisation (Webhook ID 11):** Der SuperOffice-Connector lauscht nun aktiv auf `appointment.created` und `document.created`. Sobald ein Vertriebler auflegt oder sendet, pusht the Worker die Daten via REST-API (`/ce/api/activities/sync`) an den Company Explorer.
|
|
|
|
### 29.3 Das "Aktivitäten & Controlling" Dashboard (v0.8.0)
|
|
Das React-Frontend wurde um eine dritte Ebene erweitert, die sich primär an Team- und Vertriebsleitung richtet:
|
|
* **Aktivitätsmix:** Prozentuale und absolute Aufschlüsselung der Tätigkeitstypen.
|
|
* **Interaktive Zeitleiste:** Ein scrollbarer, farbcodierter Verlauf der Aktivitäten über die letzten Jahre.
|
|
* **Klick-Filter (Drilldown):** Klickt man auf einen Aktivitätstyp im Kreisdiagramm, filtert sich sofort die Zeitleiste und die unterliegende "Aktivitäten-Log" Tabelle (inkl. Content-Vorschau) auf diesen Typ.
|
|
|
|
### 29.4 Executive Controlling Reports (HTML)
|
|
Für das Management wurde ein Button integriert, der auf Knopfdruck dedizierte, interaktive HTML-Reports generiert.
|
|
* **3 Zielgruppen:** Mitarbeiter, Teamleiter und Geschäftsführung.
|
|
* **Intelligenz:** Die Berechnungen umfassen abgeleitete Proxy-Metriken wie "Aktive Vertriebstage" (Tage mit mind. 1 Aktivität) zur Messung der Effizienz.
|
|
|
|
## 30. Dashboard Polish & Stability (v0.8.0+) - April 29, 2026 (Abend)
|
|
|
|
Nach der Implementierung des Activity Trackings wurde das System stabilisiert und die User Experience for den Produktivbetrieb optimiert.
|
|
|
|
### 30.1 Bugfix: Dashboard-Wiederherstellung
|
|
* **Problem:** Das Dashboard stürzte mit einem `NameError` ab, da Berechnungsvariablen for Aktivitäten in der API-Antwort fehlten.
|
|
* **Lösung:** Wiederherstellung der `activities_stats` Logik im Backend. Die API berechnet nun live den Aktivitätsmix und den Verlauf unter Berücksichtigung aller Manager- und Zeitfilter.
|
|
|
|
### 30.2 Performance & Drilldown (Limit 5000)
|
|
* **Optimierung:** Das Limit for die Aktivitäten-Liste wurde von 50 auf **5000** erhöht. Dies stellt sicher, dass beim Klick auf seltener vorkommende Tätigkeitstypen im Frontend-Drilldown alle relevanten Datensätze angezeigt werden.
|
|
|
|
### 30.3 UX: Dynamischer Toby-Ladescreen
|
|
* **Branding:** Implementierung eines interaktiven Ladebildschirms mit dem RoboPlanet Avatar **Toby**.
|
|
* **Entertainment:** Rotation von **15 verschiedenen lustigen Ladesprüchen** im 7-Sekunden-Takt.
|
|
|
|
### 30.4 Daten-Qualität: Intelligentes "Hide Zeroes"
|
|
* **Logik-Update:** Der Toggle "0-Listings ausblenden" filtert nun proaktiv Manager ohne Won-Deals und Branchen/Produkte ohne Umsatz.
|
|
|
|
## 31. Advanced Controlling & Efficiency Dashboard (v0.8.1) - April 30, 2026
|
|
|
|
**Kontext:** Bereitstellung belastbarer kaufmännischer KPIs for die Geschäftsführung und das Controlling.
|
|
|
|
### 31.1 Die "Single Source of Truth" for Aktivitäten
|
|
* **Abkehr von UDF-Caches:** Das Dashboard und die Intelligence-Engine nutzen nun ausschließlich die lokale `activities` Tabelle. Dies eliminiert Sync-Fehler und liefert 100% verlässliche Zeitstempel.
|
|
* **Healing Rollup:** Ein Massen-Update (`heal_activities_rollup_v2.py`) hat die Historie for über 4.800 Firmen lokal saniert und Lücken (z.B. Capron) geschlossen.
|
|
* **Real-Time Sync:** Backend-Logik (`app.py`) aktualisiert nun bei jedem Aktivitäts-Webhook automatisch die aggregierten Zeitstempel in der firmen- und Kontakt-Tabelle.
|
|
|
|
### 31.2 Strategische Effizienz-Metriken
|
|
* **Sales Cycle Phasen:** Getrennte Messung von Ø Dauer und Ø Touchpoints for:
|
|
1. **Phase 1:** Lead-Eingang bis Angebotserstellung.
|
|
2. **Phase 2:** Angebotserstellung bis zum Abschluss (Won).
|
|
* **Daten-Sanierung:** Automatische Exklusion von "0-Tage Retro-Deals" (Nachträge), um operative Durchlaufzeiten nicht künstlich zu schönen.
|
|
* **Field Visit Yield:** Berechnung der benötigten Vor-Ort-Termine pro Abschluss. Strikte Trennung zwischen **Pre-Sales Akquise** (Demos/Besuche) und **After-Sales** (Fulfillment/Implementierung).
|
|
|
|
### 31.3 Reiseaufwand-Kalkulator
|
|
* **Geodaten-Integration:** Kopplung mit der PLZ-Datenbank des Heatmap-Tools (Datei: `plz_geocoord.csv`).
|
|
* **Algorithmus:** Berechnung der Reisezeit pro Vor-Ort-Termin via Haversine-Distanz (Manager-Base zu Kunden-ZIP) inkl. 30% Straßennetz-Zuschlag und Ø 85 km/h.
|
|
* **Kosten-Transparenz:** Ausweisung der gesamten Reisezeit-Investition (in Stunden) pro gewonnenem Deal und pro Manager.
|
|
|
|
### 31.4 UI Upgrade & Performance
|
|
* **View Switcher:** Neuer Reiter "Controlling & Effizienz" im Sales Dashboard mit interaktivem Toggle.
|
|
* **Manager Breakdown:** Detaillierte Effizienz-Tabelle mit individuellen Werten (Touchpoints, Cycle Time, Fahrtzeit) pro Mitarbeiter.
|
|
* **Next Activity Visibility:** Neue Spalte "Nächste Aktivität" im Dashboard und im Explorer zur Visualisierung geplanter Follow-Ups (🎯).
|
|
* **Versionierung:** Dashboard auf v0.8.1 aktualisiert.
|
|
|
|
## 32. Follow-Up Engine & AI Email Generation (v0.8.2) - April 30, 2026
|
|
|
|
**Kontext:** Automatisierung und Personalisierung des Nachfass-Prozesses für offene Angebote, um die Win-Rate zu erhöhen und den Sales zu entlasten.
|
|
|
|
### 32.1 KI-gestützte Entwurfsgenerierung (Masterclass V13)
|
|
* **Grounded Truth Context:** Die KI (Gemini 2.5 Flash) generiert Follow-Up E-Mails nicht mehr generisch, sondern zieht hochspezifische Daten aus der SQLite-Datenbank:
|
|
* **Angebots-Details:** Exakte Produkte (SKUs) und Angebotsvolumen.
|
|
* **CRM-Historie:** Die letzten 5 Aktivitäten (Termine, Telefonnotizen).
|
|
* **Firmen-Dossier:** Die strategische Analyse des Company Explorers.
|
|
* **Menschliche Tonalität:** Der Prompt wurde radikal auf eine natürliche, souveräne Berater-Tonalität getrimmt. Zeitangaben werden "vermenschlicht" (z.B. "Mitte April" statt "16.04.").
|
|
* **UI-Integration:** Im Sales-Dashboard ("Rote Liste") können Entwürfe via "Zauberstab"-Icon 🪄 mit einem Klick simuliert und vor dem Versand in einem Text-Editor manuell angepasst werden.
|
|
|
|
### 32.2 Mailing Engine Integration (Execution)
|
|
* **Nahtloser Versand:** Das Dashboard ist nun direkt mit der `mailing-engine` API (`/send-manual`) verbunden.
|
|
* **Absender-Auflösung:** Die Mailing-Engine identifiziert den in der UI ausgewählten Sales-Manager, zieht dessen echtes Profil (Position, Telefon) aus ihrer lokalen Datenbank und injiziert diese in das saubere HTML-Template (`signature.html`).
|
|
* **Sicherer Test-Modus:** Um versehentliche Mails an Kunden zu verhindern, wurde für die Testphase ein harter Redirect im Backend (`person_id = 193033`) implementiert. Jede generierte Mail geht samt korrekter HTML-Signatur an die Testadresse.
|
|
* **Signatur-Update:** Das Werbe-Banner im HTML-Template wurde erfolgreich auf die neueste Version (`Signatur_Banner_Flotte_mit_Slogan_2_2.png`) aktualisiert und via internem Nginx-Proxy aus dem Connector bereitgestellt.
|
|
|
|
## 33. Proaktives Controlling & Data-Driven Sales (v0.8.4) - Mai 01, 2026
|
|
|
|
**Kontext:** Transformation des Dashboards von einem reinen Reporting-Tool zu einer proaktiven Data-Mining Engine für die Vertriebssteuerung.
|
|
|
|
### 33.1 Data Mining: "Winning Patterns" & Follow-Up Kadenz
|
|
* **Der historische Blind Spot:** Es wurde identifiziert, dass SuperOffice Termine (`Appointments`) und E-Mails/Angebote (`Documents`) strikt trennt. Ein Import von **11.600 historischen Dokumenten** aus `cg_dokumente.csv` schloss diese Lücke.
|
|
* **Die Korrektur:** Durch die lückenlose Historie sank der Median für das Erst-Follow-Up von 37 Tagen auf **10 Tage**.
|
|
* **Win-Rate Analyse:** Vor-Ort-Termine steigern die Abschlusswahrscheinlichkeit nachweislich um **159%** (23,8% vs. 9,2%).
|
|
* **Drilldown-Modal:** Implementierung eines interaktiven Drilldowns, der die exakten Accounts hinter den Metriken inkl. SO-Deep-Links visualisiert.
|
|
|
|
### 33.2 White-Space: "Untapped Potential"
|
|
* **CRM-Inventur:** Die Analyse ergab, dass **67%** der 14.850 Branchen-Accounts in SuperOffice keinerlei Aktivitätshistorie aufweisen (White Space).
|
|
* **Leuchtturm-Generator:** Das Dashboard generiert nun eine nach Vertical filterbare Liste der Top-Firmen ohne Historie, sortiert nach ihrem von der KI extrahierten **Wikipedia-Umsatz**.
|
|
|
|
### 33.3 Performance & Architektur (Turbo-Boost)
|
|
* **Index-Optimierung:** Behebung eines SQL-Index-Verlusts durch Typkonflikt (VARCHAR vs INTEGER JOIN). Ladezeit der KPI-API sank von **57 Sekunden auf 0,09 Sekunden**.
|
|
* **N+1 Query Fix:** Optimierung der "Leads ohne Angebot" Logik durch Batch-ID-Matching im RAM statt sequenzieller SQL-Abfragen.
|
|
* **Build-Automatisierung:** Vite injiziert nun bei jedem Neubau die Berliner Serverzeit (`__BUILD_TIME__`) in den Header.
|
|
* **Timeline UX:** Der Aktivitäten-Chart wurde massiv vergrößert (h-96) und horizontal scrollbar gemacht (12+ Monate).
|
|
|
|
## 34. Dashboard Ergonomie & Stagnations-Alarm (v0.8.5) - Mai 02, 2026
|
|
|
|
**Kontext:** Fokus auf UX, Platzoptimierung und die Einführung eines proaktiven Stagnations-Alarms.
|
|
|
|
### 34.1 Stagnations-Alarm
|
|
* **Logik:** Identifiziert Deals, die offen sind (`is_closed=0`), ein Umsatz-Potenzial haben (`amount>0`) und bei denen die letzte verbuchte Aktivität (egal ob CRM-Termin oder E-Mail) **älter als 14 Tage** ist.
|
|
* **Backend-Integration:** Ein neuer Endpoint `/ce/api/dashboard/stagnation` wurde implementiert. Wichtig: Um den korrekten Firmennamen zu laden, wurde ein dedizierter `LEFT JOIN companies` auf Basis der `crm_id` hinzugefügt, da die Tabelle `sales` oft nur die ID hielt.
|
|
* **Frontend-Widget:** Eine hoch-sichtbare (orange) Alert-Tabelle im Dashboard warnt die Manager und verlinkt direkt ins CRM.
|
|
|
|
### 34.2 Dashboard Ergonomie & Expert Mode
|
|
* **Kompaktheit:** Der Header wurde massiv verschlankt (reduziertes Padding, kleinere Icons), um auf Standard-Full-HD-Bildschirmen mehr Platz für die eigentlichen Analysen zu schaffen. Die KPI-Karten wurden ebenfalls neu, platzsparend angeordnet.
|
|
* **Sprungmarken (Anchor-Links):** Eine `sticky` Navigationsleiste direkt unter dem Header ermöglicht nun den direkten Absprung in jede beliebige Auswertungs-Sektion (Trend, Funnel, Branchen, Produkte, Leads, Rote Liste, Stagnation, PoCs, Kanäle, White Space).
|
|
* **Trend/Forecast Patch:** Der `Performance & Hit-Rate Trend` wurde geglättet. Wenn der aktuelle Monat bereits historische Daten (Won/Lost) aufweist, aber auch noch offenen Forecast für die Rest-Tage besitzt, werden diese beiden Quellen nun elegant als `mixed`-Typ in *einer* monatlichen Säule (Balkendiagramm) visualisiert, ohne dass der Monat doppelt auftaucht.
|
|
* **Expert Mode Gating:** Sensible Team-Vergleichsdaten (Win-Rates pro Manager, Cycle Times) sowie der Absprung in das globale Controlling-Modul sind jetzt sicher hinter dem URL-Parameter `?mode=expert` versteckt. Dies ermöglicht das problemlose Screen-Sharing des Dashboards in normalen Vertriebsmeetings.
|
|
|
|
## 35. Sales Fokus-Modus & Multi-Generierung (v0.8.6) - Mai 02, 2026
|
|
|
|
**Kontext:** Weiterentwicklung des Dashboards von einem Analyse-Werkzeug zu einem operativen Steuerungsinstrument ('Action Hub').
|
|
|
|
### 35.1 Der neue 'Mein Fokus' View
|
|
* **Manager Memory:** Das Dashboard merkt sich nun über den Local Storage, welcher Sales-Manager zuletzt ausgewählt war.
|
|
* **Wochen-Agenda:** Kompakte Übersicht aller Deals mit geplanten Aktivitäten (Termine, Follow-Ups) in den nächsten 7 Tagen.
|
|
* **Low Hanging Fruits:** Eine priorisierte Aktionsliste für Deals mit einer Gewinnwahrscheinlichkeit >= 50%, bei denen entweder keine nächste Aktivität geplant ist oder das geplante Datum in der Vergangenheit liegt.
|
|
|
|
### 35.2 Stagnations-Filter & Schieberegler
|
|
* **Flexibles Intervall:** Manager können die Schwelle für den Stagnations-Alarm nun stufenlos über einen Schieberegler (5 bis 30 Tage) einstellen.
|
|
* **Probability Filter:** Einführung von Schnellfiltern ('Alle', '>=50%', '98%'), um stagnierende Deals nach ihrer Abschlusswahrscheinlichkeit zu priorisieren.
|
|
|
|
### 35.3 Bulk Magic Wand (Multi-Generierung)
|
|
* **Batch Processing:** In den Listen 'Low Hanging Fruits' und 'Stagnations-Alarm' können nun mehrere Deals via Checkbox markiert werden.
|
|
* **Parallel Generation:** Ein Klick generiert im Hintergrund parallel hochpersonalisierte Masterclass-Anschreiben für alle ausgewählten Deals.
|
|
* **Accordion UI:** Die generierten Entwürfe werden in einem Modal übersichtlich dargestellt. Manager können sie querlesen, kurz anpassen und direkt aus dem Dashboard versenden.
|
|
|
|
### 35.4 KI-Tonalität & Kalender-Intelligenz
|
|
* **Du vs. Sie:** Der Prompt für die Follow-Up Engine extrahiert nun die echten E-Mail-Inhalte und Telefonnotizen (`text_internal_notes`) aus der CRM-Historie. Die KI analysiert diese und wählt konsequent die richtige Anrede ('Hallo Manuel' vs. 'Sehr geehrter Herr...').
|
|
* **Terminvorschlag:** Die KI fügt am Ende jedes Entwurfs nun proaktiv einen konkreten Terminvorschlag (z.B. 'Hätten Sie kommende Woche Dienstag um 11:15 Uhr Zeit...') sowie einen positiven Schlusssatz ein, um die Conversion-Rate zu maximieren.
|
|
|
|
### 35.5 UI Polish
|
|
* **Report Exklusivität:** Die Download-Buttons für die Management-Reports (Mitarbeiter, Teamleiter, GF) wurden aus dem regulären Dashboard entfernt und sind nun exklusiv im geschützten `?mode=expert` (Controlling View) sichtbar.
|
|
|
|
## 36. Controlling Dashboard: DB I, Demo-Rate & Fahrtzeiten (v0.8.7) - Mai 04, 2026
|
|
|
|
**Kontext:** Bereitstellung finaler kaufmännischer Kennzahlen und Korrektur der Fahrtzeit-Transparenz.
|
|
|
|
### 36.1 Deckungsbeitrag (DB I) & EK-Integration
|
|
* **SSoT für Preise:** Implementierung eines internen Produkt-EK Dictionaries basierend auf Controlling-Vorgaben (z.B. CC1 Pro 9.000 €, Phantas 6.500 €).
|
|
* **Keyword-Matcher:** Entwicklung einer `calculate_margin` Logik, die Verkäufe via `sale_name` (inkl. Multiplikator-Erkennung wie '2 x') den Produkten zuordnet.
|
|
* **Grounded Truth:** Ersatz der "Warten auf Navision"-Platzhalter durch Echtzeit-Berechnungen in allen Reports (MA, Team, GF) und dem Dashboard.
|
|
|
|
### 36.2 Demo-to-Win Rate (Conversion)
|
|
* **KPI-Fokus:** Einführung der "Demo Win-Rate" zur Messung der Abschlussqualität nach einer Live-Vorführung vor Ort.
|
|
* **Logik:** Korrelation von "Vorführungstermin Roboter - KPI" Aktivitäten mit dem finalen Deal-Status (Won/Lost).
|
|
* **UI-Integration:** Neue KPI-Kachel im Dashboard und zusätzliche Spalte "Demos" in der Executive Scorecard.
|
|
|
|
### 36.3 Fahrtzeit-Transparenz & Cycle-Time
|
|
* **Drilldown-Upgrade:** Um hohe Fahrtzeiten bei komplexen Deals zu rechtfertigen, wurde der Detail-View um die Spalte "Demos | Post" erweitert. Nutzer sehen nun sofort, dass z.B. 11h Fahrtzeit aus drei separaten Vor-Ort-Terminen resultieren.
|
|
* **Cycle-Time Vereinheitlichung:** Die "Cycle-Time" (Durchlaufzeit) misst nun systemweit (Pipeline, Controlling, Scorecard) nur noch **Phase 2** (Angebotserstellung bis Abschluss), um Missverständnisse durch lange Anbahnungsphasen (Phase 1) zu vermeiden. Die Phase 1 bleibt im Manager-Drilldown weiterhin als separater Wert transparent.
|
|
|
|
### 36.4 Lost-Deal Analyse
|
|
* **Neue Datenfelder:** Das Backend wurde erweitert, um `lost_reason` (Absagegrund), `internal_notes` (Manager-Freitext) und `competitor` (Wettbewerber) aus dem CRM zu speichern.
|
|
* **Automatischer Backfill:** Über 250 historische verlorene Deals aus 2026 wurden via SuperOffice API mit den echten Gründen (z.B. "Fläche zu klein", "Preis") angereichert.
|
|
* **Controlling UI:** Einführung einer neuen Sektion "Lost-Deal Analyse", die eine grafische Auswertung der Top 5 Absagegründe (inkl. Volumen) sowie ein detailliertes Audit-Log aller verlorenen Angebote mit den Original-Manager-Notizen bietet.
|
|
|
|
### 36.5 Daten-Hygiene & Rollen-Korrekturen
|
|
* **Manager-Namen:** Das harte Connector-Mapping wurde repariert ("Daniel Schlecht" ➔ "Daniel Sengstock", "Evi Ziegler" ➔ "Evelyn Zuehl"). 120 bestehende Deals und alle Aktivitäten wurden in der Datenbank per SQL korrigiert.
|
|
* **Aktive Tage:** Ein Bug in der Berechnung der "Aktiven Vertriebstage" (der durch die Uhrzeit im ISO-Zeitstempel zu Doppelzählungen führte) wurde behoben.
|
|
|
|
## 37. Controlling-Dashboard (v0.8.7) - DB I-Präzision & KPI-Erweiterung (04. Mai 2026)
|
|
|
|
**Kontext:** Finalisierung der Controller-Anforderungen und Behebung von Ungenauigkeiten in der kaufmännischen Logik.
|
|
|
|
### 37.1 Deckungsbeitrag (DB I) - Umstellung auf "Ground Truth"
|
|
* **Problem:** Es wurde eine signifikante Diskrepanz zwischen dem im Dashboard angezeigten DB I und den manuellen Berechnungen festgestellt. Die Ursachenanalyse ergab, dass die bisherige `calculate_margin`-Funktion auf dem unzuverlässigen `sale_name` (Angebotstitel) operierte.
|
|
* **Lösung (Single Source of Truth):** Die Berechnungslogik wurde fundamental umgestellt. Das Backend liest nun für jedes Angebot die exakten **`quote_lines`** (Angebotspositionen) aus der Datenbank aus.
|
|
* **Implementierung:**
|
|
1. Die zentrale KPI-Abfrage (`/ce/api/dashboard/kpis`) wurde um einen `GROUP_CONCAT` erweitert, der alle `product_model` und `quantity`-Paare pro `saleId` aggregiert.
|
|
2. Die `calculate_margin`-Funktion wurde so überarbeitet, dass sie primär diesen aggregierten String parst und den EK auf Basis der echten Angebotsdaten berechnet. Die alte `sale_name`-Analyse dient nur noch als Fallback.
|
|
* **Ergebnis:** Die DB-I-Berechnung ist nun 100% präzise und immun gegen irreführende Angebotstitel.
|
|
|
|
### 37.2 Demo-to-Win Rate
|
|
* **Neue KPI:** Eine neue Kennzahl wurde implementiert, um die Effektivität von Vor-Ort-Demos zu messen. Sie berechnet die Quote, wie viele Verkäufe aus Aktivitäten vom Typ `Vorführungstermin Roboter - KPI` resultieren.
|
|
|
|
### 37.3 Transparenz bei Fahrtzeiten
|
|
* **Kontextualisierung:** Um die teilweise hohen, geschätzten Reisezeiten pro Deal besser zu erklären, wurde die Detailansicht im Manager-Drilldown um eine Spalte ergänzt, die die **Anzahl der Pre- und Post-Sales-Termine** (`Demos | Post`) für diesen spezifischen Deal anzeigt. Dies macht sofort ersichtlich, dass hohe Zeiten oft aus mehreren Fahrten resultieren.
|
|
|
|
## 🤖 Status-Update (2026-05-07 17:48 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:46
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ Live-Schaltung des Sales Dashboards (Mailing-Engine): Entfernung der Demo-Sperre (Person-ID 193033), E-Mails werden nun an die echten CRM-Kontakte versendet.
|
|
✦ Implementierung der dynamischen Absender-Auflösung: E-Mails nutzen nun Namen und E-Mail des in SuperOffice hinterlegten Sales-Managers als Absender.
|
|
✦ BCC-Logik integriert: Jede E-Mail wird nun als Kopie an den versendenden Sales-Manager sowie als Audit an c.godelmann@robo-planet.de gesendet.
|
|
✦ 'Rückrufbitte'-Funktion (1-Klick & Bulk) im Frontend integriert: Schnelles Generieren von Call-Back Texten ohne Umweg über die KI-Analyse.
|
|
✦ Behebung des 'Bulk Magic Wand' Absturzes: UI-Refactoring und SQL-IN-Klausel-Bugfix (SQLite Parameter Limits), was den Batch-Versand stabilisiert.
|
|
✦ Härtung der Anrede-Logik ('Herr Mühle' Bugfix): Verbesserte 'getSalutation' Funktion, die nun auch Titel auswertet, Fallbacks ('Guten Tag') nutzt und fehlerhafte Gender-Daten aus SuperOffice abfängt.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-08 07:07 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:08
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ Verifizierung der Entfernung des '[DEMO-MODE]'-Präfixes: Es wurde bestätigt, dass der Prefix nicht mehr in relevanten Code-Dateien der Mailing Engine oder des Company Explorers vorhanden ist.
|
|
✦ Überprüfung der Absender-ID: Die Logik zur E-Mail-Versendung wurde erfolgreich überprüft und sendet nun mit dynamisch zugewiesenen Sales-Manager-IDs, anstatt einer hartkodierten Demo-ID.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-08 16:13 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:48
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ **Rückrufbitte-Text angepasst:** Der Text für die 'Rückrufbitte' im Sales Dashboard wurde präzisiert. Der erste Satz 'ich hatte versucht Sie telefonisch zu erreichen.' bleibt erhalten, der zweite Satz wurde zu 'Es wäre schön, wenn Sie mich bei Gelegenheit zurückrufen könnten, vielen Dank dafür!' geändert.
|
|
✦ **Betreff der Rückrufbitte erweitert:** Der Betreff der Rückrufbitte wurde um ', vielen Dank vorab' ergänzt.
|
|
✦ **'Letzte Aussendung'-Anzeige implementiert:** Die sendet nun nach erfolgreichem E-Mail-Versand die 'last outreach'-Information an den . Ein neuer Endpunkt im verarbeitet diese Information und aktualisiert den -Zeitstempel für den Kontakt und die firma in der Datenbank.
|
|
✦ **Anzeigeformat des 'Letzten Kontakts' verbessert:** Im Sales Dashboard wird das Datum des letzten E-Mail-Kontakts nun dynamisch angezeigt: für Kontakte, die weniger als 30 Tage zurückliegen, als 'vor X Tagen' und für ältere Kontakte als vollständiger Zeitstempel.
|
|
✦ **BCC-Fehler in Mailing Engine diagnostiziert:** Es wurde festgestellt, dass das kundenspezifische SuperOffice CRMScript kein dediziertes BCC-Feld im Payload verarbeitet. Ein Workaround wurde implementiert, der eine Warnung im Log ausgibt, dass BCC-Adressen ignoriert werden, da das CRMScript diese Funktion nicht unterstützt. Eine serverseitige Anpassung des CRMScripts in SuperOffice ist zur vollständigen Behebung erforderlich.
|
|
✦ **Zeitstempel-Vergleichsfehler behoben:** Ein im bei der Aktualisierung des -Zeitstempels wurde behoben, indem zeitzonenbehaftete () -Objekte vor dem Vergleich und der Speicherung in zeitzonenlose () UTC-Zeitstempel umgewandelt werden.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-09 13:47 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:19
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ Sales Dashboard Sync Verification: Successful end-to-end test of the real-time SuperOffice webhook integration.
|
|
✦ Troubleshooting & Calibration: Identified sale type '17' (Service/Accessories) as the reason for a missing deal in the Hardware Pipeline. Verified that changing the type to '14' (Roboplanet Verkauf) in CRM immediately triggers the update and reflects in the dashboard.
|
|
✦ System Reliability: Confirmed that the Connector-Worker and the Company Explorer API handle sales events reliably and within seconds, providing a solid 'Single Source of Truth' for sales controlling.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-09 14:11 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:23
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ Sales Dashboard Sync Verification: Successful end-to-end test of the real-time SuperOffice webhook integration.
|
|
✦ Troubleshooting & Calibration: Identified sale type '17' (Service/Accessories) as the reason for a missing deal. Verified that switching to '14' (Roboplanet Verkauf) in CRM immediately reflects in the dashboard.
|
|
✦ Connector Monitor Upgrade: Enhanced the 'Account Summary' view to include Sales, Appointments, and Documents. The monitor now displays the specific entity (e.g., 'Sale 343418') and the last event type, providing better visibility for all CRM interactions.
|
|
```
|
|
|
|
|
|
## 38. Reference Management & Notion Sync (v0.8.8) - 09. Mai 2026
|
|
|
|
**Kontext:** Aufbau eines dedizierten Dashboards zur Verwaltung von Referenzkunden, synchronisiert mit der Notion "References" Datenbank als Single Source of Truth.
|
|
|
|
### 38.1 Backend & Routing Fixes
|
|
* **API Konsolidierung:** Alle Endpunkte (Companies, Contacts, References) wurden erfolgreich bereinigt und konsistent unter das `/api` Präfix (via `api_router`) des Company Explorers gemountet, um mit dem Nginx-Proxy (`/ce/`) zu harmonieren.
|
|
* **Frontend-Serving:** Die gebaute React-App wird nun als Fallback (Catch-All) über `app.mount("/", StaticFiles(...))` korrekt am Ende der `app.py` ausgeliefert.
|
|
|
|
### 38.2 Referenz-Daten Initialisierung (Skripte)
|
|
* **Kandidaten-Matching (`set_reference_candidates.py`):** Ein Skript gleicht die Markdown-Dateien aus `/docs/references/` mit der lokalen SQLite-Datenbank ab und setzt das interne Flag `is_reference_candidate = 1`. Erfolgreich durchgeführt für 26 firmen.
|
|
* **Notion-Synchronisation (`sync_notion_references.py`):** Ein Skript verbindet sich mit der Notion-Datenbank "References" (ID: `32c88f42-8544-8068-a15b-f34ea972a403`). Es gleicht die firmennamen ab und importiert die Felder `Status` (Dropdown) und `Zitat` (Rich Text) in die lokalen DB-Spalten `reference_status` und `reference_comment`. Erfolgreich getestet.
|
|
|
|
### 38.3 🔴 Offener Task für die nächste Sitzung (Seamless Resume)
|
|
* **Status Quo:** Das Backend-Routing ist weitestgehend repariert (Pfade `/api/companies`, `/api/contacts/all`, `/api/references/candidates` existieren). Das System hat die Referenzkunden in der Datenbank markiert und erste Status-Werte aus Notion synchronisiert.
|
|
* **Das Problem:** Wenn man im "Reference Management" Tab auf eine firma klickt, um die Details (den Inspector) zu laden, wirft das Frontend noch einen Fehler ("Failed to load data" -> Log zeigte `404 Not Found` auf `/api/companies/{id}`). Außerdem laden die Referenzen im Table-View aktuell nicht sauber, obwohl Companies und Contacts wieder da sind.
|
|
* **To-Do 1:** Den Container zwingend einmal komplett und hart neu bauen (`docker-compose build --no-cache company-explorer && docker rm -f company-explorer && docker-compose up -d company-explorer`), da die letzten Syntax- und Routing-Korrekturen (Entfernen der doppelten `app.py` Init, Fixen des `routers_reference.py` Imports) sich offenbar im Arbeitsspeicher des Docker-Dämons "verschluckt" haben.
|
|
* **To-Do 2:** Prüfen, ob der Inspector-API-Call (`/api/companies/{id}`) nach dem sauberen Neustart funktioniert.
|
|
* **To-Do 3:** Sicherstellen, dass das Frontend-Dashboard die frisch synchronisierten Notion-Werte (Status, Kommentar) fehlerfrei anzeigt.
|
|
|
|
## 39. Reference Studio v1.0 & Readiness Intelligence (10. Mai 2026)
|
|
|
|
**Kontext:** Transformation des simplen "Reference Management" Dashboards in ein interaktives Produktionswerkzeug (Asset Studio) für das Marketing-Team, um aus Kundenreferenzen direkt verwertbare Marketingmaterialien zu generieren.
|
|
|
|
### 39.1 3-Phasen Interview-Wizard (Frontend)
|
|
Das React-Frontend (`ReferenceManager.tsx`) wurde grundlegend überarbeitet. Ein Klick auf einen Referenzkunden öffnet nun ein interaktives Accordion mit drei Phasen:
|
|
1. **Vorbereitung:** Kompakter Check der "Kunden-Gesundheit" (Laufzeit, gekaufte Hardware, offene Support-Tickets, letzte E-Mail-Historie).
|
|
2. **Interview 🎙️:** Ein dynamisch generiertes Skript (5-6 Fragen) mit Fokus-Hinweisen und separaten Textfeldern für die Echtzeit-Notizen während des Telefonats.
|
|
3. **Assets & Publikation 🪄:** One-Click-Generierung von fertigen LinkedIn-Posts, offiziellen Zitaten und Website-Stories auf Basis der in Phase 2 erfassten Notizen.
|
|
|
|
### 39.2 Readiness Intelligence & Anti-Halluzination (Backend)
|
|
Der neue API-Endpunkt `/references/{company_id}/readiness` versorgt den Wizard mit den nötigen Daten:
|
|
* **Ticket-Warning System (Fast-Lane):** Um auf Support-Probleme reagieren zu können, bevor sie eskalieren, wurde eine performante SQLite-Tabelle `tickets` angelegt. Ein neues Skript (`import_tickets.py`) importiert den statischen Export `CG_Anfragen_RP.csv` in diese Tabelle. Der Endpunkt warnt das Marketing vor Anrufen bei Kunden mit offenen Eskalationen (Red Flags).
|
|
* **Grounded Product Context (SSOT):** Um KI-Halluzinationen (z.B. Transport-Use-Cases für Reinigungsroboter) zu unterbinden, wurde der LLM-Prompt hart an die Tabelle `products` gekoppelt. Die KI erhält nun die offiziellen Produktbeschreibungen und Kategorien aus der Datenbank als unverrückbare Basis.
|
|
* **KPI-Framework Integration:** Die generierten Interview-Fragen sind keine offenen "Wie finden Sie..."-Fragen mehr, sondern **konfirmative Lenkungsfragen (Steering)**. Sie zielen strategisch darauf ab, die im `kpi_framework.json` definierten Schmerzpunkte der jeweiligen Branche zu bestätigen.
|
|
|
|
### 39.3 Daten-Persistenz
|
|
Die Tabelle `companies` wurde um die Spalten `interview_notes` (Text) und `reference_assets` (Text/JSON) erweitert, damit angefangene Interviews und fertige Marketing-Texte dauerhaft gespeichert bleiben und beim nächsten Aufruf des Dashboards sofort wieder zur Verfügung stehen.
|
|
|
|
|
|
|
|
## 40. Support Ticket Integration (v0.8.9) - 10. Mai 2026 (Abend)
|
|
|
|
**Kontext:** Vollstaendige Integration der SuperOffice Support-Tickets in den Company Explorer, um Vertrieb und Marketing eine 360-Grad-Sicht auf die Kundengesundheit ("Customer Health") zu ermoeglichen, ohne das CRM oeffnen zu muessen.
|
|
|
|
### 40.1 Datenbank-Erweiterung & Historischer Backfill
|
|
* **Modell Ticket:** Die database.py wurde um ein vollstaendiges Ticket-Modell erweitert (tickets-Tabelle), das neben den Meta-Daten (status, title, created_at) nun auch die vollstaendigen Nachrichteninhalte (message_body, html_body) und strukturierte Ticket-Metadaten als JSON speichert.
|
|
* **Backfill-Logik:** Ein dediziertes Batch-Skript (sync_ticket_contents.py) wurde entwickelt, um die Inhalte fur alle **1.440 initial importierten Support-Tickets** ueber die SuperOffice REST-API (get_ticket_messages) nachzuladen und lokal in der SQLite-Datenbank zu speichern.
|
|
|
|
### 40.2 API & Routing-Haertung (Die "Route Shadowing" Lektion)
|
|
Die Bereitstellung der Daten an das Frontend offenbarte eine kritische Architektur-Schwaeche im FastAPI-Routing:
|
|
* **Das Problem:** Der neue Endpunkt GET /api/companies/{company_id}/tickets wurde unterhalb der generischen Route GET /api/companies/{company_id} (die das komplette firmenprofil laedt) deklariert. Da FastAPI Routen sequenziell abarbeitet, fing die generische Route den Ticket-Aufruf ab, interpretierte {company_id}/tickets als ungueltige ID und warf verlaesslich einen 404 Not Found Fehler ("Company not found").
|
|
* **Die Loesung:** Die spezifischere Ticket-Route musste im Source-Code zwingend **vor** der Catch-All-Route platziert werden.
|
|
* **Mapping-Falle:** Ein weiterer Stolperstein war das Mapping der IDs. SuperOffice-Tickets sind im CRM mit der externen crm_id verknuepft, das Frontend fragt jedoch mit der internen Datenbank-ID (id) an. Die Ticket-Route muss daher die interne ID (14450) im Backend zunaechst auf die crm_id (166330) uebersetzen, bevor sie die tickets-Tabelle abfragt.
|
|
|
|
### 40.3 Echtzeit-Sync & Pydantic-Bypass
|
|
* **Echtzeit-Webhook:** Der worker.py (Connector) lauscht nun auf die SuperOffice-Events ticket.created und ticketmessage.created. Bei jedem Event laedt er den gesamten Nachrichtenverlauf ueber die REST-API und pusht ihn an den neuen Endpunkt POST /api/tickets/sync.
|
|
* **Der Pydantic-Serializer-Fehler (Hard Bypass):** Bei der Auslieferung der Ticket-Liste an das Frontend (GET /api/companies/{company_id}/tickets) stuerzte der interne FastAPI/Pydantic-Serializer beim Versuch ab, die massiven HTML-Blobs in das implizite Schema zu pressen, was stillschweigend zu einer leeren Liste [] oder einem HTTP 500 fuehrte.
|
|
* **Architektur-Entscheidung:** Um maximale Stabilitaet zu garantieren, wurde ein **Hard-Bypass** implementiert. Die Route ignoriert das SQLAlchemy-ORM fur die Rueckgabe vollstaendig und nutzt stattdessen rohes sqlite3 (row_factory = sqlite3.Row), um die Ticket-Metadaten blitzschnell und ohne Serialisierungs-Overhead als Dictionaries an das Frontend zu streamen.
|
|
|
|
### 40.4 Frontend: Der "Support Tickets" Inspector
|
|
Das React-Frontend (Inspector.tsx) wurde um einen neuen Haupt-Reiter "Support Tickets" (neben "Overview" und "Contacts") erweitert.
|
|
* **UX:** Ein Zaehler-Badge im Tab-Titel zeigt sofort an, wie viele offene/historische Tickets fur diese firma existieren.
|
|
* **Darstellung:** Die Tickets werden in einer uebersichtlichen, chronologischen Liste gerendert. Status-Badges (z.B. gruen fur "Bearbeitet", orange fur "In Arbeit") helfen bei der schnellen Orientierung.
|
|
* **Inhalte:** Die html_body-Inhalte der Tickets werden (unter Nutzung von dangerouslySetInnerHTML mit Tailwind Typography-Klassen) direkt in einer sicheren Box gerendert, sodass der Vertriebler den exakten Wortlaut der Support-Anfrage lesen kann. Ein Deep-Link ermoeglicht den direkten Absprung in das SuperOffice-Ticket.
|
|
|
|
### 40.5 Wichtige "Lessons Learned" zur Infrastruktur
|
|
Die heutige Session war stark von infrastrukturellen Fehlern gepraegt, die in Zukunft durch strengere Arbeitsablaeufe vermieden werden muessen:
|
|
1. **Host vs. Container Paths:** Die Annahme, dass das Verzeichnis /app im Host-System existiert, fuehrte zu kaskadierenden No such file or directory-Fehlern, da der Agent auf der VM lief, die Pfade aber relativ zum Mount (~/gemini-setup/) waren. Befehle wie cat > /app/... auf dem Host schlagen unweigerlich fehl.
|
|
2. **Permission Denied beim Datei-Sync:** Der Versuch, Dateien aus dem isolierten AI-Container (gemini-session) via Pipe (docker exec ... | docker exec ...) in den Produktiv-Container zu verschieben, scheitert oft an Root/User-Berechtigungskonflikten des Hosts.
|
|
3. **Leere Dateien durch Regex/Sed:** Aggressive Bash-Skripte (sed, cat << EOF) zum Umschreiben von Quellcode ohne vorheriges Backup koennen Dateien auf 0 Bytes leeren und ganze Container-Builds unbrauchbar machen (wie bei app.py passiert).
|
|
4. **Best Practice fur die Zukunft:** Bei tiefgreifenden Code-Aenderungen an Python-Backends oder React-Frontends sollten diese **niemals** ueber unleserliche CLI-Pipes modifiziert werden. Der saubere Weg:
|
|
* Den Code lokal im isolierten Volume (/app im AI-Container) testen.
|
|
* Ueber Git-Commits persistieren.
|
|
* Auf dem Host einen sauberen Git-Pull und anschliessend einen docker-compose build --no-cache ausfuehren.
|
|
|
|
|
|
### 40.6 Offene To-Dos fur morgen (WICHTIG!)
|
|
- [ ] **Frontend Build Fix:** Der aktuelle Build schlaegt fehl mit . Dies liegt an der korrupten/leeren Datei auf dem Host.
|
|
- [ ] **Action:** Die reparierte (aus dem Container) muss zwingend auf den Host synchronisiert werden ().
|
|
- [ ] **Deployment:** Anschliessend ausfuehren.
|
|
- [ ] **Verifizierung:** End-to-End Test im Browser: Erscheint der Reiter "Support Tickets" und werden die 60 Fressnapf-Tickets korrekt angezeigt?
|
|
|
|
|
|
### 40.6 Offene To-Dos fuer morgen (WICHTIG!)
|
|
- [ ] **Frontend Build Fix**: Der aktuelle Build schlaegt fehl (TS2306). Datei Inspector.tsx auf dem Host ist korrupt.
|
|
- [ ] **Action**: Reparierte Inspector.tsx vom gemini-session Container auf den Host kopieren.
|
|
- [ ] **Deployment**: docker-compose build --no-cache company-explorer ausfuehren.
|
|
- [ ] **Verifizierung**: Reiter Support Tickets und Fressnapf-Tickets im Browser pruefen.
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-10 22:34 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 03:32
|
|
|
|
Arbeitszusammenfassung:
|
|
[35c88f42] Support-Ticket Integration & Infrastructure Härtung:
|
|
|
|
1. DB-Schema um Support-Tickets (inkl. HTML-Bodys) erweitert.
|
|
|
|
2. Manueller Backfill von 1.440 Tickets erfolgreich durchgeführt.
|
|
|
|
3. FastAPI-Routing korrigiert (Shadowing behoben).
|
|
|
|
4. sqlite3-Hard-Bypass für performante Auslieferung großer Nachrichten-Blobs implementiert.
|
|
|
|
5. 'Support Tickets' Reiter im Frontend-Inspector integriert.
|
|
|
|
6. MIGRATION_PLAN.md um 'Lessons Learned' und Build-Fix To-Dos für morgen ergänzt. Status: Backend/DB bereit, Frontend-Build-Fix auf Host ausstehend.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-11 08:13 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:34
|
|
|
|
Arbeitszusammenfassung:
|
|
[35c88f42] Support Intelligence Finale:
|
|
|
|
1. Backend-SQL-Query um Nachrichten-Inhalte (HTML/Body) erweitert.
|
|
|
|
2. Interaktives Akkordeon-UI im Frontend-Inspector implementiert, um Support-Historie direkt einsehbar zu machen.
|
|
|
|
3. Container-Rebuild & Deployment auf docker1 erfolgreich durchgeführt. System ist nun vollständig live.
|
|
```
|
|
|
|
## 41. Sales Sync Resilience & API Hardening (Mai 2026)
|
|
|
|
**Kontext:** Behebung von Synchronisationslücken in der Sales-Pipeline und Härtung der SuperOffice API-Anbindung gegen Timeouts.
|
|
|
|
### 41.1 OData-Optimierung & Bugfix
|
|
* **Kritischer Bugfix:** Behebung eines Einrückungsfehlers in der `search`-Methode des `SuperOfficeClient`, der bei erfolgreichen paginierten Abfragen zu Endlosschleifen führte.
|
|
* **Timeout-Prävention:** Identifikation von API-Hängern bei komplexen `OR`-Filtern auf virtuelle Felder (`saleStatus`). Umstellung der Abfragestrategie auf hoch-indizierte Datumsfelder (`updatedDate`) mit lokalem Post-Processing in Python.
|
|
* **Case-Sensitivity:** Härtung der OData-Queries gegen Case-Sensitivity Probleme der SuperOffice API (Feldnamen wie `saleStatus`, `probPercent`).
|
|
|
|
### 41.2 Sales Audit & Recovery Tooling
|
|
* **Dauerhaftes Audit-Tool:** Implementierung von `connector-superoffice/tools/audit_sales_sync.py`. Dieses Werkzeug ermöglicht blitzschnelle Vergleiche zwischen CRM-Wirklichkeit und lokaler SQLite-Datenbank.
|
|
* **Fix-Modus:** Das Tool verfügt über einen `--fix` Parameter, um identifizierte Desyncs (z.B. verpasste Webhooks bei Deal-Abschlüssen) automatisiert zu korrigieren.
|
|
* **Recovery:** Erfolgreiche Wiederherstellung von 39 Deals (inkl. Key-Deal `343201`), die aufgrund von Webhook-Schluckauf asynchron waren.
|
|
|
|
## 🤖 Status-Update (2026-05-12 21:04 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:04
|
|
|
|
Arbeitszusammenfassung:
|
|
Sales Dashboard Desync Audit & Fix:
|
|
✦ Problem identifiziert: Komplexe OData-Filter verursachten Full-Table-Scans und stumme Timeouts der SuperOffice API.
|
|
✦ Bugfix: Kritischen Einrückungs-Fehler im 'superoffice_client.py' behoben, der Endlosschleifen bei Paginierung erzeugte.
|
|
✦ Data Recovery: Performante Datum-basierte OData-Abfrage implementiert, welche erfolgreich 39 hängengebliebene Deals (inkl. 343201) fand.
|
|
✦ DB Sanierung: Lokale SQLite DB erfolgreich für die 39 Deals auf die CRM-Wirklichkeit aktualisiert.
|
|
✦ Tooling: Neues, dauerhaftes Tool 'connector-superoffice/tools/audit_sales_sync.py' (--audit / --fix) erstellt, um dieses Problem künftig in Sekunden zu lösen.
|
|
```
|
|
|
|
## 🤖 Status-Update (2026-05-12 21:14 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:10
|
|
|
|
Arbeitszusammenfassung:
|
|
Zusätzliche Erklärung für das Fehlen von Deal 343201 im Sales Dashboard hinzugefügt: Das Dashboard filtert Verkäufe mit der Sale Type ID 17 ('RoboPlanet Servicepaket') heraus, um die Hardware-Pipeline nicht zu verfälschen. Eine manuelle Änderung auf 'Roboplanet Verkauf' in SuperOffice behebt dieses Verhalten.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-12 21:21 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:07
|
|
|
|
Arbeitszusammenfassung:
|
|
Sales Dashboard Sync Mastery & API Hardening:
|
|
✦ Bugfix: Kritischen Einrückungsfehler in 'superoffice_client.py' behoben, der Endlosschleifen bei Paginierung erzeugte.
|
|
✦ Performance: API-Timeouts durch Umstellung von komplexen OData-Filtern auf effiziente Datums-Abfragen mit lokalem Python-Parsing gelöst.
|
|
✦ Recovery: 39 asynchrone Deals (inkl. 343201) identifiziert und die lokale Datenbank auf den neuesten Stand gebracht.
|
|
✦ Tooling: Permanentes Audit-Tool 'tools/audit_sales_sync.py' (--audit / --fix) erstellt, um künftige Desyncs in Sekunden zu beheben.
|
|
✦ Analyse: Filterlogik für 'Servicepakete' (Typ 17) verifiziert und dokumentiert (Datentreue zu SO-Standardberichten).
|
|
```
|
|
|
|
## 42. Erweiterung der Roten Liste & Datenhygiene (15. Mai 2026)
|
|
|
|
**Kontext:** Die Rote Liste im Sales Dashboard wurde zu einem umfassenden "Datenhygiene & Compliance" Dashboard ausgebaut, um CRM-Fehler transparent und behebbar zu machen.
|
|
|
|
### 42.1 Neue Filter-Architektur
|
|
Die statische Rote Liste wurde durch ein interaktives Filter-System ersetzt. Folgende Problemklassen ("Issue Types") werden nun vom Backend (`/api/dashboard/kpis`) automatisch erkannt und können im UI gefiltert werden:
|
|
* **Überfälliges Entscheidungsdatum** (`overdue_date`)
|
|
* **Überfällige nächste Aktivität** (`overdue_next_activity`): Die in SuperOffice geplante Wiedervorlage liegt in der Vergangenheit.
|
|
* **Demo ohne Follow-Up** (`demo_without_followup`): Ein Vorführungstermin fand statt, wurde aber nicht abgeschlossen oder es fehlt eine Folgeaufgabe.
|
|
* **Fehlende Quelle/Kanal** (`missing_source` / `missing_channel`): Wichtige Marketing-Zuordnungen fehlen.
|
|
* **Fehlendes Startdatum** (`missing_implementation_date`): Gewonnener Deal ohne Implementierungsdatum (Neu implementiertes UDF).
|
|
* **Fehlende Vertragsart** (`missing_contract_type`): Deals >= 98% Wahrscheinlichkeit ohne Angabe zu Kauf/Miete/Leasing.
|
|
* **Won mit 0 EUR** (`zero_amount_won`): Abgeschlossene Deals ohne Umsatz.
|
|
* **Doppelte Angebote** (`duplicate_offer`): Erkennung von Multi-Deals für dieselbe Firma am selben Tag.
|
|
* **Falscher Kundenstatus** (`wrong_customer_status`): Firma ist als "Kunde" (Kategorie 3) geflaggt, hat aber keinen 'Won'-Deal in der Historie.
|
|
|
|
### 42.2 Backend & Connector Updates
|
|
* **Schema-Erweiterung:** Die `sales`-Tabelle wurde um das Feld `implementation_date` erweitert.
|
|
* **Webhook-Sync:** Der Connector (`worker.py`) liest nun gezielt das SuperOffice UDF `SuperOffice:8` als Implementierungsdatum aus und schreibt es in die SQLite-Datenbank.
|
|
* **SQL-Optimierung:** Komplexe Cross-Entity-Abfragen (Hygiene-Checks) wurden mittels `LEFT JOIN` auf die `companies`-Tabelle gehärtet, um korrekte Firmennamen für verwaiste Aktivitäten bereitzustellen.
|
|
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-15 11:51 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 03:28
|
|
|
|
Arbeitszusammenfassung:
|
|
[36188f42] Erweiterung der Roten Liste & Datenhygiene:
|
|
|
|
1. Backend: Implementierung automatischer Hygiene-Checks (Doppelte Angebote, falscher Kundenstatus, offene Vorführtermine, fehlende Startdaten/Vertragsarten).
|
|
|
|
2. Connector: Sync von 'implementation_date' aus SuperOffice (UDF 8) integriert.
|
|
|
|
3. Frontend: Interaktives Filtersystem mit Buttons und Problem-Badges im Sales Dashboard erstellt.
|
|
|
|
4. Bugfix: KeyError bei fehlenden Firmen-IDs in Hygiene-Issues behoben.
|
|
|
|
5. Dokumentation: MIGRATION_PLAN.md um Architektur der Datenhygiene erweitert.
|
|
```
|
|
|
|
## 43. Webhook Watchdog 2.0 & Desired State Enforcement (Mai 15, 2026)
|
|
|
|
**Kontext:** Behebung von unbemerkten Webhook-Ausfällen (Silent Failures) bei SuperOffice und Absicherung der Pipeline gegen fehlerhafte Webhook-Konfigurationen.
|
|
|
|
### 43.1 Das "Desired State" Prinzip
|
|
* **Problem:** Der ursprüngliche Watchdog prüfte nur, ob Webhook ID 9 "Active" war. Wenn SuperOffice diesen bei Timeouts wegen "TooManyErrors" deaktivierte (oder ID 9 zwar aktiv war, aber die Events für sale.changed fehlten), blieben Updates stecken, ohne dass ein Alarm ausgelöst wurde.
|
|
* **Lösung:** Der neue Watchdog (check_webhook_health.py) arbeitet nicht mehr starr mit IDs, sondern erzwingt einen definierten **Golden State**:
|
|
* Er listet alle Webhooks auf, die auf unsere URL (https://gtm.robo-planet.de/connector/webhook) feuern.
|
|
* Er löscht automatisch alle redundanten Duplikate (z.B. durch alte Skripte angelegte Webhooks).
|
|
* Er prüft beim verbleibenden Primär-Webhook, ob *alle* 14 zwingend erforderlichen Events (Contacts, Persons, Sales, Appointments, Documents, Tickets) abonniert sind.
|
|
* Fehlt ein Event oder ist der Webhook deaktiviert, repariert das Skript ihn sofort via API (PATCH) und sendet einen Teams-Alarm.
|
|
|
|
### 43.2 Stagnation Kill-Switch (Self-Healing Queue)
|
|
* **Problem:** API-Timeouts führten dazu, dass Jobs im Connector endlos im Status PROCESSING feststeckten und so die Abarbeitung neuer Events blockierten.
|
|
* **Lösung:** Der Hintergrund-Worker (worker.py) überwacht sich nun selbst. Steckt ein Job länger als 15 Minuten in PROCESSING fest, wird er automatisch vom Watchdog gekillt (auf FAILED gesetzt), was die Queue sofort wieder entblockiert.
|
|
|
|
### 43.3 Diff-Sync & Recovery
|
|
* Ein neues Tool (diff_sync_sales.py) wurde implementiert, um nach Systemausfällen gezielt die Änderungen der letzten 48 Stunden aus dem CRM abzurufen und als künstliche Webhook-Events in die lokale Queue einzuspeisen, um verlorene Updates nachzuziehen.
|
|
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-15 15:46 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:32
|
|
|
|
Arbeitszusammenfassung:
|
|
[36188f42] Pipeline-Transparenz & Datenhygiene finalisiert:
|
|
|
|
1. Backend: Abfrage für doppelte Angebote um Summierung und 'Bloat'-Kalkulation (Überhang) erweitert.
|
|
|
|
2. Frontend: Prominente Anzeige der Pipeline-Verfälschung (Summe aller Duplikate) in der Roten Liste implementiert.
|
|
|
|
3. Interaktive Sortierung: Alle Deal-Tabellen im Dashboard sind nun per Klick auf die Spaltenüberschrift (Firma, Volumen, Datum, Historie) sortierbar.
|
|
|
|
4. UX: Detaillierte Darstellung der Angebotsanzahl und des kumulierten Werts bei betroffenen Kunden.
|
|
|
|
5. Dokumentation: Intelligence Status in README.md aktualisiert.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-16 06:27 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:18
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ Massendaten-Korrektur (Rückrufbitte): Alle fehlerhaften Einträge (Wiedervorlage/Wiesengutschein) vom 11.05. bis 13.05. wurden bereinigt und durch korrekte 'Mailing per Email' Termine ersetzt.
|
|
✦ Daten-Wiederherstellung: Die Einträge wurden mit dem originalen Zeitstempel (13.05.2026 16:37), korrekter dynamischer Anrede (CRM-basiert) und dem richtigen Absender (Sebastian Hosbach) rekonstruiert.
|
|
✦ System-Härtung (Mapping): Der 'superoffice_client' erzwingt nun bei Task 9 ('Mailing per Email') korrekt den Appointment-Typ, um Fallbacks auf 'Wiedervorlage' zu verhindern.
|
|
✦ Zuweisungs-Logik: Die gesamte Prozesskette (Dashboard -> Mailer -> Connector) wurde um die Übergabe des Sales-Managers erweitert, sodass Aktivitäten nun immer dem echten Absender zugewiesen werden.
|
|
✦ Fehlerbehebung (Template ID): Die fehlerhafte Dokumenten-Zuweisung (ID 39) wurde durch die Rückkehr zur Appointment-Logik und die Verifizierung der korrekten Template-IDs (157 für E-Mails) gelöst.
|
|
```
|
|
|
|
|
|
|
|
## 44. Sales Targets & Forecasting Engine (Mai 2026)
|
|
|
|
**Kontext:** Aufbau eines operativen Steuerungsinstruments für die Vertriebsleitung zur Berechnung von Lead-Vorgaben und zur Bereinigung der Pipeline-Zahlen.
|
|
|
|
### 44.1 Clean Pipeline vs. Gross Pipeline
|
|
* **Problem:** Vertriebsmitarbeiter legen oft mehrere parallele Angebote (Optionen) für denselben Kunden an, was den Pipeline-Wert künstlich aufbläht.
|
|
* **Lösung:** Das System berechnet nun den **"Duplicate Bloat"**. Alle Angebote eines Kunden werden gruppiert. Die Differenz zwischen der Gesamtsumme und dem höchsten Einzelangebot wird als "Bloat" abgezogen.
|
|
* **Clean Pipeline:** Das Ergebnis (`Gross Pipeline - Bloat`) stellt den wahren, maximalen Erwartungswert dar.
|
|
* **Realistic Forecast:** Dieser Wert wird mit der historischen `Angebot ➔ Won` Conversion-Rate multipliziert, um eine realistische Umsatz-Prognose zu erhalten.
|
|
|
|
### 44.2 Account-Based Conversion Tracking
|
|
* **Problem:** Bisherige Conversion-Rates basierten auf der Anzahl der Dokumente (Angebote vs. Leads), was zu Raten > 100% führen konnte (ein Lead = 3 Angebote).
|
|
* **Lösung:** Die Conversion-Logik (`/api/dashboard/targets`) wurde auf `DISTINCT company_id` umgestellt.
|
|
* **Ergebnis:** Das System misst nun präzise, wie viel Prozent der kontaktierten *Firmen* ein Angebot erhalten und wie viele *Firmen* am Ende kaufen. Die Metrik ist unempfindlich gegenüber "Angebot-Spam".
|
|
|
|
### 44.3 Der Target Simulator ("The Machine")
|
|
* **Logik:** Eine interaktive "Reverse-Funnel" Berechnung im Frontend.
|
|
* **Funktion:** Die Vertriebsleitung gibt einen monatlichen Ziel-Umsatz ein (z.B. 300.000 €).
|
|
* **Ausgabe:** Das System berechnet live, wie viele Leads das Team pro Woche benötigt. Die Zuweisung erfolgt individuell pro Sales-Manager, basierend auf dessen spezifischer historischer Hit-Rate und der durchschnittlichen Deal-Größe.
|
|
* **Auto-Balancing:** Die prozentuale Verteilung des Ziels auf die Manager kann per Slider angepasst werden, wobei das System die Summe immer automatisch auf 100% ausbalanciert.
|
|
|
|
### 44.4 Hardware Inventory Forecast
|
|
* **Ziel:** Transparente Prognose für den Einkauf.
|
|
* **Umsetzung:** Das Backend durchsucht alle aktuell *offenen* Angebote (`is_closed = '0'`) nach Roboter-Schlüsselwörtern (`phantas`, `cc1`, etc.) und berücksichtigt dabei auch Multiplikatoren (z.B. "3 x Phantas"). Das Ergebnis ist eine exakte Liste der aktuell in Verhandlung befindlichen Hardware.
|
|
|
|
### 44.5 Customer Lifecycle Timeline (UI)
|
|
* **Visualisierung:** Ein interaktiver Zeitstrahl (Akkordeon), der beim Klick auf eine Deal-Zeile aufklappt.
|
|
* **Datenpunkte:** Der Zeitstrahl visualisiert vier Phasen: `Erster Kontakt ➔ Angebot ➔ Verkauf ➔ Implementation`. Die Startzeit wird über einen Sub-Select ermittelt, der das allererste Aktivitätsdatum (z.B. Erstkontakt-Call) aus der `activities`-Tabelle zieht.
|
|
|
|
## 🤖 Status-Update (2026-05-16 11:11 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 02:34
|
|
|
|
Arbeitszusammenfassung:
|
|
[36288f42] After Sales Dashboard (v1.1) implementiert:
|
|
|
|
1. Architektur: Neuer Microservice 'after-sales-engine' als eigenständiger Docker-Container (FastAPI + React) aufgesetzt.
|
|
|
|
2. Daten-Integration: Read-Only Zugriff auf die Company-Explorer Datenbank (Tickets & Sales) via Docker Bind-Mount realisiert.
|
|
|
|
3. Features:
|
|
- Alarm-Radar: Identifikation kritischer Accounts mit hoher Ticket-Stagnation.
|
|
- Accordion-UI: Interaktiver Deep-Dive in die Ticket-Historie und den vollständigen Nachrichtenverlauf (Messenger-Style) inkl. HTML-Support.
|
|
- Service-Economics: Automatisierte Vor-Ort-Erkennung (Heuristik) und Berechnung von Fahrtkosten/Distanzen basierend auf echten Techniker-Standorten (Kraus, Haxijaj, Schmelting).
|
|
- Sales-Linkage: Korrelation von Verkäufen mit nachfolgendem Support-Bedarf (88,2% Vor-Ort-Quote identifiziert).
|
|
|
|
4. UX: Dark-Mode Support und Datums-Filter (Gesamt / 2026) integriert.
|
|
|
|
5. Dokumentation: Umfassende README.md im Modulordner erstellt.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-19 10:59 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 03:52
|
|
|
|
Arbeitszusammenfassung:
|
|
✦ **Sales Targets & Forecasting Engine (v0.9.0) finalisiert:**
|
|
|
|
1. **Clean Pipeline & Bloat-Filter:** Implementierung einer Logik zur Erkennung und Bereinigung von 'Angebots-Bloat' (Doppel-Angebote). Der Forecast basiert nun auf der *Clean Pipeline* (Netto) x historischer Win-Rate.
|
|
|
|
2. **Account-Based Conversion:** Umstellung der Conversion-Rates auf Unique Accounts (DISTINCT company_id). Die Verzerrung durch Multi-Angebote (>100% Quote) wurde eliminiert.
|
|
|
|
3. **Target Simulator ('The Machine'):** Interaktiver Simulator im Frontend mit monatlichem Team-Umsatz-Slider. Das System berechnet live die individuell benötigten Leads pro Woche für jeden Sales-Manager.
|
|
|
|
4. **Auto-Balancing Anteile:** Implementierung einer proportionalen Verteilungs-Logik. Bei Erhöhung des Zielanteils einer Person passen sich alle anderen automatisch an, sodass die Summe immer exakt 100% ergibt.
|
|
|
|
5. **Customer Lifecycle Timeline:** Jede Deal-Zeile klappt nun als Akkordeon auf und visualisiert den Zeitstrahl: Erster Kontakt -> Angebot -> Verkauf -> Implementation 🚀 inkl. echten Daten aus der Aktivitätshistorie.
|
|
|
|
6. **Hardware Inventory Forecast:** Neue Sicht für den Einkauf, die alle aktuell *offenen* Angebote nach Roboter-Modellen scannt und den benötigten Lagerbestand (Stückzahl pro Modell) projektiert.
|
|
|
|
7. **Infrastruktur & Datenhygiene:** Migration der Vertragsarten in eigene Spalte, Whitelisting aktiver Manager und Härtung der SQLite-Stabilität (Timeout-Fixes).
|
|
|
|
8. **UX:** Dashboard ist neue Startseite, Versionen auf v0.9.0 korrigiert.
|
|
|
|
## 46. Kauf vs. Leasing Dashboard & Performance Optimization (Mai 2026)
|
|
|
|
**Kontext:** Analyse der Vertragsarten (Kauf/Leasing) im Sales Dashboard und Optimierung der Ladezeiten für große Datenmengen.
|
|
|
|
### 46.1 Kauf vs. Leasing Mix (Trend)
|
|
* **Visualisierung:** Neues gestapeltes Balkendiagramm im Sales Dashboard.
|
|
* **Logik:** Aggregation der Umsätze nach `contract_type` (Kauf, Leasing, Miete).
|
|
* **Fokus:** Um statistischen "Bloat" zu vermeiden, berücksichtigt der Graph ausschließlich gewonnene Deals (`stage = 'Verkauft'`). Offene Deals ohne festen Vertragstyp werden ignoriert.
|
|
|
|
### 46.2 Flexibler Zeit-Filter (Date-Range)
|
|
* **Feature:** Erweiterung der Filterleiste um den Modus "INDIVIDUELL".
|
|
* **UI:** Implementierung von zwei Datumsfeldern (Von/Bis) mit nativer Browser-Kalender-Unterstützung.
|
|
* **UX:** Einführung eines "Anwenden"-Buttons zur Vermeidung unnötiger API-Calls während der Datumsauswahl.
|
|
* **Feedback:** Globaler Lade-Screen mit Toby-Avatar während Datenabfragen für klare Benutzerführung.
|
|
|
|
### 46.3 Performance & Caching Strategie
|
|
* **N+1 Query Fix:** Optimierung der SKU-Performance API. Umstellung von sequenziellen Produkt-Abfragen auf ein hocheffizientes Pre-Fetching (Single-Query Mapping).
|
|
* **Caching:** Erhöhung der KPI-Cache TTL auf 10 Minuten. Integration der `winning-patterns` und `stagnation` Endpunkte in das Caching-Framework.
|
|
* **Backend:** Härtung der SQL-Abfragen für benutzerdefinierte Zeiträume.
|
|
|
|
## 47. Dashboard Konsistenz & SuperOffice Abgleich (Mai 2026)
|
|
|
|
**Kontext:** Bereinigung von Zahlen-Diskrepanzen zwischen verschiedenen Dashboard-Ansichten und Angleichung an offizielle SuperOffice-Berichte.
|
|
|
|
### 47.1 Vereinheitlichung der Filter-Logik
|
|
* **Problem:** Unterschiedliche Zeitfenster (rollierend vs. Kalenderjahr) und ungleiche Deal-Ausschlüsse führten zu widersprüchlichen Summen im Dashboard.
|
|
* **Lösung:** Implementierung einer zentralen `standard_cond` im Backend, die strikte SuperOffice-Kriterien abbildet:
|
|
1. **Hardware-Fokus:** Nur Kategorien 14 (Verkauf), 15 (Miete), 16 (Teststellung). Kategorie 17 (Service) wird separiert.
|
|
2. **Konzern-Ausschluss:** Deals von Firmen der Kategorie 22 ("Eigener Konzern") werden ignoriert.
|
|
3. **Source/Contract Veto:** Nur Deals aus dem "Neukundenvertrieb RP" ODER mit explizitem Vertragstyp "Kauf" werden in die Hardware-Pipeline aufgenommen.
|
|
* **Synchronität:** Alle Graphen (Main Trend, Funnel, Contract Mix) nutzen nun zwingend dieselbe SQL-Bedingung.
|
|
|
|
### 47.2 Transparenz für Service-Umsätze
|
|
* **Feature:** Einführung eines dedizierten "Service & Zubehör" Trends (Kategorie 17).
|
|
* **Zweck:** Verhindert die Verwässerung der Hardware-Win-Rates bei gleichzeitiger vollständiger Transparenz über alle Einnahmequellen.
|
|
|
|
### 47.3 Fehler-Resilienz & Debugging
|
|
* **Audit-Log:** Erweiterung des Dashboards um ein Audit-Log für "Unstimmige Deals", um falsch markierte Leads im Vertrieb schnell identifizieren zu können.
|
|
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-19 18:24 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 01:11
|
|
|
|
Arbeitszusammenfassung:
|
|
[36488f42] Snooze-Funktion für Dashboard-Warnungen implementiert:
|
|
|
|
1. DB-Tabelle 'snoozed_warnings' angelegt.
|
|
|
|
2. Backend-Filterung in KPI-API integriert.
|
|
|
|
3. API-Endpunkt für Snooze-Intervalle erstellt.
|
|
|
|
4. UI-Upgrade mit Snooze-Popover (1 Woche bis permanent) im Sales Dashboard.
|
|
|
|
5. Doku in MIGRATION_PLAN.md aktualisiert.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-21 08:19 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:48
|
|
|
|
Arbeitszusammenfassung:
|
|
[36588f42] Kauf vs. Leasing Dashboard & Performance Optimization:
|
|
|
|
1. Backend-Aggregation der Vertragsarten (Kauf, Leasing, Miete) für gewonnene Deals implementiert.
|
|
|
|
2. Frontend-Graph (gestapeltes Balkendiagramm) im Sales Dashboard hinzugefügt.
|
|
|
|
3. Flexibler Date-Picker (Von/Bis) mit 'Anwenden'-Button zur Vermeidung von Fehl-Ladungen integriert.
|
|
|
|
4. Globales Lade-Overlay mit Toby-Avatar für klares UX-Feedback.
|
|
|
|
5. Massive Performance-Steigerung durch Beseitigung von N+1 SQL-Queries und Erhöhung des Cache-TTL auf 10 Min.
|
|
|
|
6. Dokumentation in MIGRATION_PLAN.md aktualisiert.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-23 07:52 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:37
|
|
|
|
Arbeitszusammenfassung:
|
|
[36588f42] Dashboard Unification & Data Integrity Fixed:
|
|
|
|
1. Unified backend SQL filters across all dashboard components to ensure numerical consistency (275.536 €).
|
|
|
|
2. Implemented strict SO hardware criteria (Status: Sold, Source: Neukundenvertrieb OR Type: Kauf, Exclude Own Group).
|
|
|
|
3. Added dedicated 'Service & Zubehör' (Category 17) trend graph to separate revenue streams.
|
|
|
|
4. Removed 'date(now)' cutoff to include full month spectrum in historical views.
|
|
|
|
5. Updated frontend navigation and MIGRATION_PLAN.md.
|
|
|
|
6. Analyzed and explained SO discrepancies (TIMBRA/TCOrobotics).
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-23 08:49 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:42
|
|
|
|
Arbeitszusammenfassung:
|
|
[36988f42] Admin Activity Report & Tool-Influenced ROI implementiert:
|
|
|
|
1. Lückenlose Protokollierung von Dashboard-E-Mails als echte CRM-Aktivitäten inkl. Inhalten.
|
|
|
|
2. Präzise Absender-Zuordnung via X-User-Email Header (Auth-Service).
|
|
|
|
3. Implementierung einer ROI-Analyse-Logik für Folgereaktionen (insb. Telefonate) innerhalb von 7 Tagen.
|
|
|
|
4. Neues Dashboard-Widget 'Tool-Influenced Revenue' im Expert Mode zur Visualisierung des Tool-Beitrags zum Umsatz.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-23 09:03 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:14
|
|
|
|
Arbeitszusammenfassung:
|
|
Zusammenstellung der historischen ROI-Tabelle (Dashboard Mail -> Reaktion -> Won) für Sebastian Hosbach erstellt und in den Entwurf für den COO integriert.
|
|
```
|
|
|
|
|
|
## 🤖 Status-Update (2026-05-23 09:14 Berlin Time)
|
|
```yaml
|
|
Investierte Zeit in dieser Session: 00:10
|
|
|
|
Arbeitszusammenfassung:
|
|
[36988f42] ROI-Logik finalisiert & Dashboard korrigiert:
|
|
|
|
1. Strikte Filterung auf Dashboard-Launch (ab 01.05.2026) implementiert.
|
|
|
|
2. Fokus auf belegbare Reaktionen (Telefonate) innerhalb von 14 Tagen.
|
|
|
|
3. Sebastian's Performance (62 Mails, 6 Reaktionen) als Baseline etabliert.
|
|
|
|
4. Dokumentation in MIGRATION_PLAN.md auf den realen Stand v0.9.9 korrigiert.
|
|
```
|