Dies ist der Microservice zur bidirektionalen Anbindung von SuperOffice CRM an die Company Explorer Intelligence. Der Connector agiert als intelligenter Bote ("Muscle"): Er nimmt Webhook-Events entgegen, filtert Rauschen heraus, fragt das "Gehirn" (Company Explorer) nach Instruktionen und schreibt Ergebnisse (Marketing-Texte, Branchen-Verticals, Rollen) ins CRM zurück.

1. Architektur: "Noise-Reduced Event Pipeline"

Wir nutzen eine Event-gesteuerte Architektur mit integrierter Rauschunterdrückung, um die CRM-Last zu minimieren und Endlosschleifen zu verhindern.

Der Datenfluss:

Auslöser: Ein User ändert Stammdaten in SuperOffice.
Filterung (Noise Reduction): Der Webhook-Receiver ignoriert sofort:
- Irrelevante Entitäten (Sales, Projects, Appointments, Documents).
- Irrelevante Felder (Telefon, E-Mail, Fax, interne Systemfelder).
- Nur strategische Änderungen (Name, Website, Job-Titel, Position) triggern die Pipeline.
Queueing: Valide Events landen in der lokalen SQLite-Queue (connector_queue.db).
Provisioning: Der Worker fragt den Company Explorer (:8000): "Was ist die KI-Wahrheit für diesen Kontakt?".
Write-Back: Der Connector schreibt die Ergebnisse (Vertical-ID, Persona-ID, E-Mail-Snippets) via REST API zurück in die SuperOffice UDF-Felder.

2. 🚀 Go-Live Checkliste (User Tasks)

Um das System auf der Produktivumgebung ("Live") in Betrieb zu nehmen, müssen folgende Schritte durchgeführt werden:

Schritt A: SuperOffice Registrierung (IT / Admin)

Da wir eine Private App nutzen, ist keine Zertifizierung nötig.

Loggen Sie sich ins SuperOffice Developer Portal ein.
Registrieren Sie eine neue App ("Custom Application").
- Redirect URI: http://localhost
- Scopes: Contact:Read/Write, Person:Read/Write, List:Read, Appointment:Write.
Notieren Sie sich Client ID, Client Secret und den Token (falls System User genutzt wird).

Schritt B: Konfiguration & Mapping

Credentials: Tragen Sie die Daten aus Schritt A in die .env Datei auf dem Server ein (SO_CLIENT_ID, etc.).
Discovery: Starten Sie den Container und führen Sie einmalig das Discovery-Tool aus, um die IDs der Felder in der Live-Umgebung zu finden:
```
python3 connector-superoffice/discover_fields.py
```
Mapping Update: Tragen Sie die ermittelten IDs in die .env ein:
- VERTICAL_MAP_JSON: Mappen Sie die CE-Branchen auf die SuperOffice "Business"-IDs.
- PERSONA_MAP_JSON: Mappen Sie die Rollen (z.B. "Influencer", "Wirtschaftlicher Entscheider") auf die SuperOffice "Position"-IDs.

Schritt C: Webhook Einrichtung (SuperOffice Admin)

Gehen Sie in SuperOffice zu Einstellungen & Verwaltung -> Webhooks und legen Sie einen neuen Hook an:

Target URL: http://<IHRE-SERVER-IP>:8003/webhook?token=<SECRET_AUS_ENV>
Events: contact.created, contact.changed, person.created, person.changed.

Schritt D: Feiertags-Import

Damit der Versand an Feiertagen pausiert:

Kopieren Sie den Inhalt von connector-superoffice/import_holidays_CRMSCRIPT.txt.
Führen Sie ihn in SuperOffice unter CRMScript -> Execute aus.

3. Business Logik & Features

4.1. Persona Mapping ("Golden Record")

Das Feld Position (Rolle) in SuperOffice wird als Ziel-Feld für die CE-Archetypen genutzt.

Logik: Der CE analysiert den Jobtitel (z.B. "Einkaufsleiter") -> Mappt auf "Influencer".
Sync: Der Connector setzt das Feld Position in SuperOffice auf den entsprechenden Wert (sofern in der Config gemappt).

4.2. Vertical Mapping

KI-Verticals (z.B. "Healthcare - Hospital") werden auf die SuperOffice-Branchenliste gemappt. Manuelle Änderungen durch User im CRM werden aktuell beim nächsten Update überschrieben (Master: CE).

4. Testing & Simulation

Verwenden Sie test_full_roundtrip.py, um die Kette zu testen, ohne E-Mails zu versenden. Das Skript erstellt stattdessen Termine in SuperOffice als Beweis.

# Startet Simulation für Person ID 2
python3 connector-superoffice/tests/test_full_roundtrip.py

5. Roadmap (v2.1)

Manual Override Protection: Schutz manueller Änderungen (Vertical/Rolle) durch den User vor Überschreiben durch die KI.
Notion Dashboard: KPI-Reporting.
Lead-Attribution: Automatisches Setzen der Sale.Source auf "Marketing Automation".