Brancheneinstufung2/connector-superoffice/README.md

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:

1. Auslöser: User ändert in SuperOffice einen Kontakt (z.B. Status -> Init).
2. Transport: SuperOffice sendet ein POST Event an unseren Webhook-Endpunkt (:8003/webhook).
3. Queueing: Der Webhook Receiver validiert das Event und legt es sofort in eine lokale SQLite-Queue (connector_queue.db).
4. Verarbeitung: Ein separater Worker-Prozess holt den Job ab.
5. Provisioning: Der Worker fragt den Company Explorer (POST /api/provision/superoffice-contact): "Was soll ich mit Person ID 123 tun?".
6. 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 für Produktionsfreigabe)

Um den Connector für den stabilen Betrieb in der Produktivumgebung freizugeben, sind folgende Härtungsmaßnahmen erforderlich:

• Konfigurationshärtung (UDFs & Endpunkte):
  • Alle umgebungsspezifischen Werte (SuperOffice Base URL, Customer ID, alle UDF ProgIDs für Vertical, Subject, Intro, Social Proof, etc.) müssen aus dem Code entfernt und über Umgebungsvariablen (.env) konfigurierbar gemacht werden. Dies stellt sicher, dass derselbe Container ohne Code-Änderung in DEV und PROD läuft.
• Werkzeug zur UDF-ID-Findung:
  • Erstellung eines Python-Skripts (discover_fields.py), das die SuperOffice API abfragt und alle verfügbaren UDFs mit ihren ProgIds auflistet. Dies vereinfacht die Erstkonfiguration in neuen Umgebungen.
• Feiertags-Logik (Autarkie SuperOffice):
  • Erstellung einer dedizierten SuperOffice Y-Tabelle (y_holidays) zur Speicherung von Feiertagen.
  • Erstellung eines Python-Skripts (import_holidays_to_so.py) zur einmaligen und periodischen Befüllung dieser Tabelle.
  • Anpassung des SuperOffice CRMScripts, um diese Tabelle vor dem Versand zu prüfen.
• Webinterface (Settings -> Job Role Mapping): Erweiterung des UI zur Darstellung und Verwaltung der neuen Persona-Archetypen und ihrer Mappings. Dies beinhaltet auch eine Überarbeitung der bestehenden Job-Titel-Mappungsansicht, um die Zuordnung zu den Archetypen zu verdeutlichen und ggf. zu editieren.
• Skalierung (Optional/Zukunft):
  • Bei sehr hoher Last (>100 Events/Sekunde) sollte die interne SQLite-Queue durch eine performantere Lösung wie Redis ersetzt werden.