Brancheneinstufung2/Notion_Dashboard.md

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

---

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.