# Dokumentation: RoboPlanet Strategic Marketing OS (v1.0)

## 1. Vision & Primärauftrag
Das **RoboPlanet Strategic Marketing OS** ist kein reines Content-Tool, sondern das digitale Zentralnervensystem für das Growth-Marketing der RoboPlanet GmbH (Wackler Group). Es transformiert unstrukturierte Herstellerdaten und Marktschmerz-Analysen in eine skalierbare, hochgradig personalisierte Go-to-Market-Maschine.

**Kern-Mission:** 
*   **Whale Hunting:** Identifikation und Durchdringung von Großkunden (Logistik >10k m², Chemieparks, Malls).
*   **Wackler-Symbiose:** Integration des menschlichen Service-Layers (NSL, Reinigung, Security) in das Robotik-Versprechen.
*   **Hyper-Skalierung:** Reduktion des Aufwands pro Kampagne bei gleichzeitiger Steigerung der Relevanz (Precision Targeting).

---

## 2. System-Architektur (The Big Picture)

Das System basiert auf einer **Decoupled Architecture**:

1.  **The Intelligence Factory (Backend):** Python-Services (Docker, SQLite) für Scraping, Data Mining, Normalisierung und KI-Generierung.
2.  **The Strategic Hub (Frontend/Control):** Notion als Single Source of Truth (SSoT) für Strategie, Portfolio-Management und Reporting.
3.  **The Execution Channels (Outbound):** SuperOffice API (CRM/Mails), WordPress API (Public Web), Messaging Matrix (Automation).

---

## 3. Funktionsmodule (Detaillierte Beschreibung)

### 3.1 Product Master (Hardware Truth)
Zentrale Instanz für alle technischen Spezifikationen.
*   **Funktion:** Automatisierte Extraktion von harten Fakten aus Hersteller-Quelltexten.
*   **Normalisierung:** Umwandlung heterogener Daten (z.B. "1:30h" -> 90 Min, "3000 sqm/h" -> 3000) zur direkten Vergleichbarkeit.
*   **Zukunftsfähigkeit:** Modularer Aufbau durch "Layer-Logik" (Cleaning-Layer, Service-Layer, Security-Layer).

### 3.2 Sector & Persona Master (Psychology Layer)
Das "Gehirn", das früher in YAML-Dateien gefangen war.
*   **Sektoren:** Definition der Zielbranchen (Hotellerie, Chemie, etc.) inklusive der "RoboPlanet-Definition" (Was bedeutet diese Branche für uns?).
*   **Personas:** Psychologische Profile (Housekeeping, Werkschutz, CEO) mit spezifischen Pains (Mirror) und Gains (Value).
*   **Probing Questions:** Branchenspezifische Fragen, die das Scraping-Tool leiten (z.B. "Hat das Hotel einen Spa?").

### 3.3 Messaging Matrix (The Secret Sauce)
Die Schaltstelle für die hyper-personalisierte Ansprache.
*   **Logik:** Trennung in **Satz 1** (Individueller Hook basierend auf der aktuellen Website-Analyse des Zielkunden) und **Satz 2** (Relationaler Lösungsbaustein basierend auf Branche + Produkt).
*   **Voice-Ready:** Vorbereitung von Skripten für den zukünftigen Voice-KI-Einsatz im Vertrieb und Support.

### 3.4 Competitive Radar & GTM Engine (Market Intelligence v3.0)
Automatisierte Überwachung der Marktbegleiter *und* zentrale Steuerung der eigenen Go-to-Market-Strategien.
*   **Architektur-Upgrade (Jan 2026):** Das System wurde auf eine 3-Tier-Architektur umgestellt, um zwischen dem **kanonischen Produkt** (was es ist) und dem **Portfolio-Eintrag** (wer es zu welchen Konditionen/mit welcher Strategie verkauft) zu unterscheiden.
*   **Funktion (Market Intelligence):** Kontinuierliches Scraping von Wettbewerber-Webseiten zur Identifikation ihres Produkt-Portfolios, ihrer Referenzkunden und zur Erstellung von "Landmines" (Angriffsfragen).
*   **Funktion (GTM Engine):** Für RoboPlanet-eigene Produkte dient das System als "Single Source of Truth". Es erfasst die komplette GTM-Strategie – von der technischen Analyse über die Definition der Zielbranchen (ICPs) und Schmerzpunkte bis hin zur Erstellung von Sales-Battlecards und ROI-Rechnern.
*   **Relationaler Kern:** Das System besteht nun aus einem Netz von Datenbanken, dessen Herzstück die Triade `Canonical Products` ↔️ `Portfolio` ↔️ `Companies` ist. Dies ermöglicht es, ein Produkt (z.B. "Puma M20") einmal zentral zu definieren und dann spezifische Marketing- und Vertriebsstrategien für den Verkauf durch RoboPlanet anzuhängen, während gleichzeitig erfasst wird, welche Wettbewerber dasselbe Produkt führen.

### 3.5 Enrichment Factory & RevOps
Datenanreicherung der CRM-Accounts.
*   **Mining:** Suche nach Umsatz, MA-Zahlen und fehlenden Ansprechpartnern via LinkedIn/SerpAPI.
*   **Klassifizierung:** Automatisches Mapping von Jobtiteln zu definierten Rollen im Strategic OS.
*   **Reporting:** Aggregation von Outbound-Metriken (Mails sent, Response Rate) zurück nach Notion für das C-Level.

---

## 4. Workflows & Datenflüsse

### A. Der GTM-Prozess (Produkt-Launch)
1.  **Ingest:** Hersteller-URL wird in die GTM-Engine eingespeist.
2.  **Extraction:** Technische Specs werden normalisiert und in den Notion **Product Master** geschrieben.
3.  **Positioning:** KI matcht Specs gegen die **Market Psychology DB** in Notion.
4.  **Generation:** Erstellung von Website-Inhalten (WordPress API) und Sales-Battlecards.

### C. Der Market-Intelligence-Prozess (Inkrementeller Import)
Nach der Umstrukturierung der Datenbanken wurde der Importprozess von einem reinen "Einmal-Import" zu einem intelligenten, zustandsbewussten Synchronisierungs-Workflow weiterentwickelt. Dies ist der Schlüssel, um das System als lebendes "Market Radar"-Tool zu nutzen.

1.  **Trigger:** Manueller Start des `import_competitive_radar.py` Skripts mit einer neuen Analyse-JSON-Datei als Input.
2.  **Phase 1: State Awareness (IST-Zustand lesen):**
    *   Bevor das Skript die neue Datei liest, fragt es den aktuellen Stand in Notion ab.
    *   Es erstellt drei "Caches" im Arbeitsspeicher: eine Liste aller existierenden Firmen, eine Liste aller `Canonical Products` und eine Liste aller `Portfolio`-Verknüpfungen (welche Firma verkauft welches Produkt).
3.  **Phase 2: Abgleich & "Upsert" (SOLL-Zustand verarbeiten):**
    *   Das Skript liest die neue JSON-Datei Wettbewerber für Wettbewerber.
    *   **"Upsert" Logik:** Für jeden Eintrag (Firma, Produkt, Portfolio-Verknüpfung) prüft es gegen seine Caches, ob dieser bereits in Notion existiert.
        *   **Fall A (Existiert bereits):** Der Eintrag wird übersprungen. Es werden keine Änderungen vorgenommen.
        *   **Fall B (Existiert noch nicht):** Nur der fehlende Eintrag wird erstellt. Wenn z.B. das Produkt "BellaBot" schon existiert, aber die Firma "Robo-Heroes" neu ist, wird nur die neue Firma und die neue Portfolio-Verknüpfung ("Robo-Heroes verkauft BellaBot") angelegt.
4.  **Ergebnis (Idempotenter Import):**
    *   **Keine Duplikate:** Firmen und kanonische Produkte werden niemals doppelt erstellt.
    *   **Inkrementelle Updates:** Nur neue Informationen werden hinzugefügt. Das System wächst mit jeder Analyse, anstatt überschrieben zu werden.
    *   **Sicherheit:** Das Skript kann beliebig oft mit derselben Datei ausgeführt werden. Nach dem ersten Lauf wird es keine Änderungen mehr vornehmen, da es erkennt, dass alle Daten bereits synchronisiert sind.

---

## 5. Outside-the-Box Hebel (Ausblick 6-12 Monate)

### 5.1 The Brain (Knowledge Ingestor)
Befreiung von implizitem Wissen aus WhatsApp/E-Mail-Silos. Ein Postfach-Scraper extrahiert Lösungsfragmente der Techniker und führt sie in Notion als strukturierte Wissensbasis für Support und RAG-Systeme zusammen.

### 5.2 Voice-Bot Integration
Nutzung der `Voice Script` Felder in der Messaging Matrix zur Speisung von AI-Voice-Agenten für Erstqualifizierung und Terminvereinbarung.

### 5.3 Combat View (Mobile Enablement)
Reduzierte Notion-Ansicht für Vertriebler vor Ort, die basierend auf dem Standort/Kunden-Sektor sofort die 3 schlagkräftigsten Verkaufsargumente liefert.

---

## 6. Notion Datenbank-Relationen (Technisches Mapping - Architektur v3.0)

Um die relationale Integrität zu wahren, sind folgende Datenbanken in Notion zwingend zu verknüpfen. Das Modell trennt zwischen anbieterneutralen Stammdaten (`Canonical Products`) und der anbieterspezifischen Vertriebssicht (`Portfolio`).

*   **Kern-Relationen (Produkt & Markt):**
    *   **Canonical Products** ↔️ **Portfolio** (Ein kanonisches Produkt kann in mehreren Portfolios sein)
    *   **Companies** ↔️ **Portfolio** (Ein Unternehmen hat mehrere Produkte im Portfolio)
    *   **Canonical Products** ↔️ **Product Categories** (Jedes Produkt gehört zu einer Kategorie)

*   **GTM & Marketing-Relationen:**
    *   **Canonical Products** ↔️ **Sector & Persona Master** (Welcher Roboter passt in welchen Markt?)
    *   **Messaging Matrix** ↔️ **Canonical Products** (Welche Lösung gehört zum Text?)
    *   **Messaging Matrix** ↔️ **Sector & Persona Master** (Welcher Schmerz gehört zu welcher Branche?)
    *   **GTM Workspace** ↔️ **Canonical Products** (Welche Kampagne bewirbt welches Gerät?)
    *   **Feature-to-Value Translator** ↔️ **Canonical Products** (Welcher Nutzen gehört zu welchem Feature?)

*   **Competitive Intelligence-Relationen:**
    *   **Companies** ↔️ **Competitive Radar (Landmines)** (Welche Angriffsfragen gehören zu welchem Wettbewerber?)
    *   **Companies** ↔️ **Competitive Radar (References)** (Welche Kundenprojekte hat der Wettbewerber realisiert?)

*   **Wissensmanagement-Relationen:**
    *   **The Brain** ↔️ **Canonical Products** (Welches Support-Wissen gehört zu welcher Hardware?)

---

## 7. Zusammenfassung der technischen Hebel
1.  **Python API Gateway:** Einziger Kommunikationspunkt für alle KI-Anfragen und CRM/WP-Transaktionen.
2.  **SQLite Persistence:** Lokales Zwischenlagern von Scrape-Ergebnissen zur Vermeidung redundanter API-Kosten.
3.  **Human-in-the-loop:** Notion dient als "Freigabe-Layer" – erst nach manuellem Review in Notion triggert Python den CRM-Push oder den Website-Publish.

---

## 8. Lessons Learned & Technische Constraints (Stand Jan. 2026)

Während der initialen Prototyping-Phase wurden kritische technische Hürden identifiziert, die bei der finalen Implementierung (insb. via Gemini CLI) proaktiv adressiert werden müssen.

### 8.1 API-Latenz & „Eventual Consistency“
*   **Problem:** Wenn eine Datenbank via API erstellt wird, meldet Notion sofort den Erfolg (`200 OK`). Die internen Indizes der Spalten (Properties) sind jedoch oft erst 15–30 Sekunden später für Schreibzugriffe (`pages.create`) bereit.
*   **Lösung:** Nach DDL-Operationen (Erstellen/Ändern von Datenbank-Strukturen) muss zwingend ein **Wait-Timer (min. 15s)** eingebaut werden, bevor Daten in diese Struktur injiziert werden.

### 8.2 SDK vs. Native REST
*   **Erkenntnis:** Das offizielle Python-SDK (`notion-client`) verhielt sich auf der Server-Umgebung (Diskstation/Python 3.8) instabil und meldete fehlende Methoden (z.B. `.query`), die laut Dokumentation vorhanden sein sollten.
*   **Lösung:** Für geschäftskritische Prozesse und Massen-Injektionen ist der **direkte Weg über die REST-API** (Python `requests` Bibliothek) vorzuziehen. Dies eliminiert Abhängigkeiten und bietet volle Transparenz über die Fehlermeldungen von Notion.

### 8.3 Suchindex-Verzögerung
*   **Problem:** Neu erstellte Datenbanken tauchen erst mit erheblicher Verzögerung im `notion.search`-Index auf. Skripte, die Datenbanken „dynamisch suchen“, schlagen in der Deployment-Phase daher oft fehl.
*   **Lösung:** Während des Setups müssen die von der API zurückgegebenen **UUIDs (IDs)** direkt im Speicher gehalten und an nachfolgende Funktionen übergeben werden, anstatt sich auf Suchbegriffe zu verlassen.

### 8.4 Property-Namenskonventionen
*   **Problem:** Sonderzeichen (z.B. `/` in `Branche/Persona`) oder führende/nachfolgende Leerzeichen in Spaltentiteln führen zu `400 Bad Request` Fehlern, da die API extrem sensitiv auf exakte String-Matches reagiert.
*   **Lösung:** Nutzung von **einfachen, alphanumerischen Bezeichnern** (z.B. `Art`, `Beschreibung`, `Status`). Die kosmetische Aufbereitung (Icons, längere Namen) sollte erst *nach* dem erfolgreichen API-Mapping manuell oder über ein explizites Update-Skript erfolgen.

### 8.5 Relation-Wiring (Das Henne-Ei-Problem)
*   **Problem:** Eine Datenbank kann keine Relation zu einer anderen Datenbank aufbauen, wenn diese noch nicht existiert.
*   **Lösung:** Zweistufiger Deployment-Prozess:
    1.  **Phase A:** Erstellen aller 7 Datenbank-Hüllen mit Basis-Properties.
    2.  **Phase B:** Nachträgliches „Verdrahten“ der Relationen via `databases.update` unter Verwendung der in Phase A generierten IDs.

### 8.6 Authentifizierung & Scoping
*   **Erkenntnis:** Notion-Integrationen benötigen explizite Freigaben pro Seite. Wenn eine Datenbank gelöscht und neu erstellt wird, muss die Verbindung in der Notion-UI oft **manuell neu autorisiert** werden, auch wenn die übergeordnete Seite bereits freigegeben war.
*   **Lösung:** Bei jedem neuen Deployment-Lauf in der Notion-UI prüfen, ob die „RoboPlanet GTM Engine“ unter den `Connections` der Zielseite gelistet ist.

### 8.7 Initial Database IDs (Stand 08. Jan. 2026)
Die folgenden IDs wurden bei der initialen Erstellung der Datenbanken generiert und sollten für die weitere Entwicklung verwendet werden, um Suchindex-Verzögerungen zu vermeiden:
*   **Product Master:** `2e288f42-8544-81d8-96f5-c231f84f719a`
*   **Sector & Persona Master:** `2e288f42-8544-8113-b878-ec99c8a02a6b`
*   **Messaging Matrix:** `2e288f42-8544-81b0-83d4-c16623cc32d1`
*   **Competitive Radar:** `2e288f42-8544-814a-a2ad-eee8a181a3cc`
*   **Enrichment Factory & RevOps:** `2e288f42-8544-8172-a3a7-f5101b6ac0f0`
*   **The Brain:** `2e288f42-8544-810f-8e7d-e9a2a3100779`
*   **GTM Workspace:** `2e288f42-8544-81cc-b167-f9dffe9c7bde`
*   **Feature-to-Value Translator:** `2e288f42-8544-8184-ba08-d6d736879f19`
*   **Projects [UT]:** `2e288f42-8544-8179-9eaa-f2bc594eece3` (Identifiziert am 25. Jan. 2026)
*   **All Tasks:** `2e888f42-8544-815c-be46-c36bbb1b7e2b` (Identifiziert am 25. Jan. 2026)

---

### Checkliste für den Neustart mit Gemini CLI:
1. [ ] **Requests statt SDK:** Nutze die native HTTP-Library für alle Notion-Calls.
2. [ ] **ID-Persistence:** Speichere IDs in einer lokalen JSON-Variable während des Laufs. (Nun fest in Doku hinterlegt)
3. [ ] **Schema-Validation:** Nutze einen `database.retrieve` Call vor dem ersten Daten-Push, um die Existenz der Spaltennamen zu verifizieren.
4. [ ] **Error-Logging:** Implementiere detailliertes Logging der API-Response-Bodys, da Notion dort sehr präzise Hinweise gibt (z.B. `property_not_found`).

---
**Status:** Blueprint Finalisiert.
**Nächster Schritt:** Umsetzung der Datenbank-Properties und API-Endpunkte gemäß diesem Dokument.

### 8.8 Erfolgreicher Datenimport & -verteilung (08. Jan. 2026)
Der Produkt-Datensatz "Puma M20" wurde erfolgreich importiert. Die strategischen Daten (Zielgruppen, Pain Points, Messaging) wurden anschließend aus dem Produkteintrag extrahiert und in die relational verknüpften Datenbanken "Sector & Persona Master" und "Messaging Matrix" verteilt. Dies schafft eine "Single Source of Truth" und legt die Grundlage für automatisierte Marketing-Workflows.

### 8.9 Neu gelernte Lektionen (Post-MVP)

6.  **Notion API - Schema First:**
    *   **Problem:** Skripte schlugen fehl beim Versuch, Daten in eine nicht existierende Datenbankeigenschaft (Spalte) zu schreiben.
    *   **Lösung:** IMMER sicherstellen, dass das Datenbankschema korrekt ist, *bevor* Daten importiert oder aktualisiert werden. Den `databases.update`-Endpunkt verwenden, um die erforderlichen Eigenschaften (z.B. "Key Features", "Constraints") programmatisch als vorbereitenden Schritt hinzuzufügen. Die API erstellt diese nicht spontan.

7.  **Notion API - Zeichenbeschränkungen:**
    *   **Problem:** API-Aufrufe schlugen mit einem `400 Bad Request`-Fehler fehl, wenn ein Rich-Text-Feld die maximale Länge überschritt.
    *   **Lösung:** Das **2000-Zeichen-Limit** für Rich-Text-Eigenschaften beachten. Eine Logik implementieren, um den Textinhalt vor dem Senden des Payloads an die Notion-API zu kürzen, um Validierungsfehler zu vermeiden.

8.  **Notion API - Antwortstrukturen:**
    *   **Problem:** Parsing-Funktionen schlugen mit `TypeError` oder `AttributeError` fehl, da die JSON-Struktur für eine Eigenschaft unterschiedlich war, je nachdem, wie sie angefordert wurde.
    *   **Lösung:** Robuste Hilfsfunktionen schreiben, die mehrere mögliche JSON-Strukturen verarbeiten können. Ein Eigenschaftsobjekt, das über einen direkten Eigenschafts-Endpunkt (`/pages/{id}/properties/{prop_id}`) abgerufen wird, ist anders strukturiert als dieselbe Eigenschaft, wenn sie Teil eines vollständigen Seitenobjekts (`/pages/{id}`) ist. Die Parsing-Logik muss diese Variationen berücksichtigen.