Dies ist der Microservice zur Anbindung von SuperOffice CRM an die GTM-Engine. Der Connector agiert als "Butler": Er bereitet im Hintergrund hyper-personalisierte Marketing-Texte vor und legt sie im CRM ab, damit der Vertrieb sie mit minimalem Aufwand versenden kann.

1. Architektur: Das "Butler-Modell"

Wir haben uns gegen eine komplexe Automatisierung innerhalb von SuperOffice (via CRMScript-Trigger) entschieden, da die DEV-Umgebung limitiert ist und die Logik extern flexibler ist.

Der Datenfluss:

Master-Daten (Notion): Pains & Gains werden pro Vertical in Notion gepflegt.
Text-Matrix (Lokal): Das Skript build_matrix.py "multipliziert" die Vertical-Daten mit den Rollen-Daten, generiert via Gemini die finalen Texte und speichert sie in einer lokalen SQLite DB (marketing_matrix.db).
Polling & Injection (Daemon): Das Skript polling_daemon_final.py läuft periodisch, prüft auf Änderungen an Kontakten in SuperOffice und "injiziert" die passenden Texte aus der lokalen Matrix-DB in die UDF-Felder.

graph TD
    subgraph "A: Strategie & Content"
        NotionDB["🏢 Notion DB<br/>(Industries & Roles)"]
    end

    subgraph "B: Lokale Engine (Python)"
        MatrixBuilder["⚙️ build_matrix.py"]
        GeminiAPI["🧠 Gemini API"]
        MatrixDB[("💾 marketing_matrix.db")]
        PollingDaemon["🤖 polling_daemon_final.py"]
    end

    subgraph "C: CRM-System"
        SuperOfficeAPI["☁️ SuperOffice API"]
        Contact["👤 Contact / Person<br/>(mit UDFs)"]
    end

    NotionDB -->|1. Liest Pains/Gains| MatrixBuilder
    MatrixBuilder -->|2. Promptet| GeminiAPI
    GeminiAPI -->|3. Generiert Texte| MatrixBuilder
    MatrixBuilder -->|4. Speichert in DB| MatrixDB
    
    PollingDaemon -->|5. Prüft Änderungen| SuperOfficeAPI
    PollingDaemon -->|6. Holt passende Texte| MatrixDB
    PollingDaemon -->|7. Schreibt in UDFs| SuperOfficeAPI
    SuperOfficeAPI -->|8. Aktualisiert| Contact

2. Kern-Komponenten (Skripte)

superoffice_client.py:
- Das Herzstück. Eine Python-Klasse, die die gesamte Kommunikation mit der SuperOffice API kapselt (Auth, GET, PUT, Search).
- Beherrscht Paginierung, um auch große Datensätze zu verarbeiten.
build_matrix.py:
- Der "Content Generator".
- Liest Pains/Gains aus Notion.
- Iteriert über definierte Verticals und Rollen.
- Nutzt Gemini, um die spezifischen Textbausteine (Subject, Intro, SocialProof) zu erstellen.
- Speichert das Ergebnis in der marketing_matrix.db.
polling_daemon_final.py:
- Der Automatisierungs-Motor.
- Läuft in einer Schleife (z.B. alle 15 Minuten) nur zu Geschäftszeiten (Mo-Fr, 7-18 Uhr).
- Fragt SuperOffice nach kürzlich geänderten Kontakten.
- Nutzt ein Hash-System, um zu prüfen, ob sich eine relevante Eigenschaft (Vertical oder Rolle) geändert hat, um unnötige API-Schreibvorgänge zu vermeiden.
- Wenn eine Änderung erkannt wird, stößt er den Update-Prozess an.
normalize_persona.py:
- Ein Hilfs-Skript (Classifier), um Jobtitel auf unsere 4 Archetypen (Operativ, Infrastruktur, Wirtschaftlich, Innovation) zu mappen.

3. Setup & Konfiguration

Installation

# In einer Python 3.11+ Umgebung:
pip install -r requirements.txt

Konfiguration (`.env`)

Der Connector benötigt eine .env Datei im Root-Verzeichnis mit folgendem Inhalt:

# Gemini API Keys (DEV für Tests, PROD für Live-Tools)
GEMINI_API_KEY_DEV="AIza..."
GEMINI_API_KEY_PROD="AIza..."
GEMINI_API_KEY=${GEMINI_API_KEY_DEV} # Setzt den Default

# Notion
NOTION_API_KEY="secret_..."

# SuperOffice Client Configuration
SO_CLIENT_ID="<Client ID / App ID>"
SO_CLIENT_SECRET="<Client Secret>"
SO_CONTEXT_IDENTIFIER="CustXXXXX"
SO_REFRESH_TOKEN="<Refresh Token>"
SO_ENVIRONMENT="sod" # oder "online" für Produktion

4. SuperOffice Konfiguration (Admin)

Folgende Benutzerdefinierte Felder (UDFs) müssen angelegt sein:

Objekt	Feldname (Label)	Typ	ProgId (Beispiel)	Zweck
Firma	Contact Vertical	Liste	`SuperOffice:5`	Speichert die Vertical ID.
Firma	AI Challenge Satz	Text	`SuperOffice:6`	Speichert den firmen-spezifischen Hook.
Person	Person Role	Liste	`SuperOffice:3`	Speichert die Rollen ID.
Person	Marketing Subject	Text	`SuperOffice:5`	Speichert den generierten Betreff.
Person	Marketing Intro	Text	`SuperOffice:6`	Speichert die generierte Einleitung.
Person	Marketing Proof	Text	`SuperOffice:7`	Speichert den generierten Social Proof.
Person	AI Copy Hash	Text	`SuperOffice:8`	Speichert den Hash zur Versionierung.

5. "Gotchas" & Lessons Learned (POC)

API-URL: Der sod Tenant Cust55774 ist nur über https://app-sod.superoffice.com erreichbar, nicht sod.superoffice.com.
Listen-IDs: Die API gibt IDs von Listenfeldern im Format [I:26] zurück. Der String muss vor der DB-Abfrage auf den Integer 26 geparst werden.
Dev-System Limits: Die Textfelder im DEV-System sind auf 40 Zeichen limitiert. Die generierten Texte müssen vor dem Senden gekürzt werden.
Y-Tabellen: Der direkte API-Zugriff auf Zusatz-Tabellen ist in diesem Mandanten blockiert (403 Forbidden). Daher der Workaround mit UDFs.
CRMScript Trigger: Die Erstellung von Triggern ist im DEV-System nicht möglich. Daher die Umstellung auf den externen Polling-Daemon.

README.md

SuperOffice Connector ("The Butler") - GTM Engine