Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
50141069e6372e74474b6bf0046f91c6706dbf86
Brancheneinstufung2/Notion_Dashboard.md
Floke d6a1449031 feat(notion): Finalize Competitive Radar v3.0 (Level 3 Relational Model) 
- Extended import_relational_radar.py to include a 'Products' database.
- Implemented full dual-way relations for Companies <-> Landmines, References, Products.
- Updated documentation to reflect the 4-database architecture.
2026-01-11 12:14:45 +00:00

13 KiB
Raw Blame History

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 (Market Intelligence v2.0)

Automatisierte Überwachung der Marktbegleiter mit Fokus auf "Grounded Truth".

  • Funktion: Kontinuierliches Scraping von Wettbewerber-Webseiten, gezielte Suche nach Referenzkunden und Case Studies.
  • Kill-Argumente & Landmines: Erstellung von strukturierten Battlecards und spezifischen "Landmine Questions" für den Sales-Außendienst.
  • Relationaler Ansatz: Trennung in vier verknüpfte Datenbanken (Firmen, Landmines, Referenzen, Produkte) für maximale Filterbarkeit und Übersicht.

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.

B. Der Outbound-Prozess (Whale Hunting)

  1. Scanning: Enrichment-Tool liest Ziel-Accounts aus SuperOffice.
  2. Hyper-Personalization:
    • KI analysiert Kunden-Website -> Generiert Satz 1 (Operative Herausforderung).
    • System zieht Satz 2 aus der Messaging Matrix in Notion.
  3. CRM-Injection: Der finale Text wird via API in SuperOffice injiziert.
  4. Execution: Vertrieb sendet hochgradig relevante Mails direkt aus dem gewohnten CRM.

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)

Um die relationale Integrität zu wahren, sind folgende Datenbanken in Notion zwingend zu verknüpfen:

  • Product Master \leftrightarrow Sector Master (Welcher Roboter passt in welchen Markt?)
  • Messaging Matrix \leftrightarrow Product Master (Welche Lösung gehört zum Text?)
  • Messaging Matrix \leftrightarrow Sector Master (Welcher Schmerz gehört zu welcher Branche?)
  • Competitive Radar (Companies) \leftrightarrow Competitive Radar (Landmines) (Welche Angriffsfragen gehören zu welchem Wettbewerber?)
  • Competitive Radar (Companies) \leftrightarrow Competitive Radar (References) (Welche Kundenprojekte hat der Wettbewerber realisiert?)
  • Competitive Radar (Companies) \leftrightarrow Competitive Radar (Products) (Welche Produkte hat der Wettbewerber im Portfolio?)
  • The Brain \leftrightarrow Product Master (Welches Support-Wissen gehört zu welcher Hardware?)
  • GTM Workspace \leftrightarrow Product Master (Welche Kampagne bewirbt welches Gerät?)
  • Feature-to-Value Translator \leftrightarrow Product Master (Welcher Nutzen gehört zu welchem Feature?)

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)

  1. 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.

  2. 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.

  3. 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.
Reference in New Issue View Git Blame Copy Permalink