SuperOffice Connector ("The Muscle") - GTM Engine

Dies ist der "dumme" Microservice zur Anbindung von SuperOffice CRM an die Company Explorer Intelligence. Der Connector agiert als reiner Bote ("Muscle"): Er nimmt Webhook-Events entgegen, fragt das "Gehirn" (Company Explorer) nach Instruktionen und führt diese im CRM aus.

1. Architektur: "The Intelligent Hub & The Loyal Messenger"

Wir haben uns für eine Event-gesteuerte Architektur entschieden, um Skalierbarkeit und Echtzeit-Verarbeitung zu gewährleisten.

Der Datenfluss:

Auslöser: User ändert in SuperOffice einen Kontakt (z.B. Status -> Init).
Transport: SuperOffice sendet ein POST Event an unseren Webhook-Endpunkt (:8003/webhook).
Queueing: Der Webhook Receiver validiert das Event und legt es sofort in eine lokale SQLite-Queue (connector_queue.db).
Verarbeitung: Ein separater Worker-Prozess holt den Job ab.
Provisioning: Der Worker fragt den Company Explorer (POST /api/provision/superoffice-contact): "Was soll ich mit Person ID 123 tun?".
Write-Back: Der Company Explorer liefert das fertige Text-Paket (Subject, Intro, Proof) zurück. Der Worker schreibt dies via REST API in die UDF-Felder von SuperOffice.

2. Kern-Komponenten

webhook_app.py (FastAPI):
- Lauscht auf Port 8000 (Extern: 8003).
- Nimmt Events entgegen, prüft Token (WEBHOOK_SECRET).
- Schreibt Jobs in die Queue.
- Endpunkt: POST /webhook.
queue_manager.py (SQLite):
- Verwaltet die lokale Job-Queue.
- Status: PENDING -> PROCESSING -> COMPLETED / FAILED.
- Persistiert Jobs auch bei Container-Neustart.
worker.py:
- Läuft als Hintergrundprozess.
- Pollt die Queue alle 5 Sekunden.
- Kommuniziert mit Company Explorer (Intern: http://company-explorer:8000) und SuperOffice API.
- Behandelt Fehler und Retries.
superoffice_client.py:
- Kapselt die SuperOffice REST API (Auth, GET, PUT).
- Verwaltet Refresh Tokens.

3. Setup & Konfiguration

Docker Service

Der Service läuft im Container connector-superoffice. Startet via start.sh sowohl den Webserver als auch den Worker.

Konfiguration (`.env`)

Der Connector benötigt folgende Variablen (in docker-compose.yml gesetzt):

environment:
  API_USER: "admin"
  API_PASSWORD: "..."
  COMPANY_EXPLORER_URL: "http://company-explorer:8000" # Interne Docker-Adresse
  WEBHOOK_SECRET: "changeme" # Muss mit SO-Webhook Config übereinstimmen
  # Plus die SuperOffice Credentials (Client ID, Secret, Refresh Token)

4. API-Schnittstelle (Intern)

Der Connector ruft den Company Explorer auf und liefert dabei Live-Daten aus dem CRM für den "Double Truth" Abgleich:

Request: POST /api/provision/superoffice-contact

{
  "so_contact_id": 12345,
  "so_person_id": 67890,
  "crm_name": "RoboPlanet GmbH",
  "crm_website": "www.roboplanet.de",
  "job_title": "Geschäftsführer"
}

Response:

{
  "status": "success",
  "texts": {
    "subject": "Optimierung Ihrer Logistik...",
    "intro": "Als Logistikleiter kennen Sie...",
    "social_proof": "Wir helfen bereits Firma X..."
  }
}

5. Offene To-Dos (Roadmap)

UDF-Mapping: Aktuell sind die ProgIds (z.B. SuperOffice:5) im Code (worker.py) hartkodiert. Dies muss in eine Config ausgelagert werden.
Fehlerbehandlung: Was passiert, wenn der Company Explorer "404 Not Found" meldet? (Aktuell: Log Warning & Skip).
Redis: Bei sehr hoher Last (>100 Events/Sekunde) sollte die SQLite-Queue durch Redis ersetzt werden.

3.6 KiB Raw Blame History