# SuperOffice Connector ("The Muscle") - GTM Engine v2.0

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:**
1.  **Auslöser:** Ein User ändert Stammdaten in SuperOffice.
2.  **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.*
3.  **Queueing:** Valide Events landen in der lokalen `SQLite`-Queue (`connector_queue.db`).
4.  **Provisioning:** Der Worker fragt den **Company Explorer** (:8000): "Was ist die KI-Wahrheit für diesen Kontakt?".
5.  **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.
1.  Loggen Sie sich ins [SuperOffice Developer Portal](https://dev.superoffice.com/) ein.
2.  Registrieren Sie eine neue App ("Custom Application").
    *   **Redirect URI:** `http://localhost`
    *   **Scopes:** `Contact:Read/Write`, `Person:Read/Write`, `List:Read`, `Appointment:Write`.
3.  Notieren Sie sich **Client ID**, **Client Secret** und den **Token** (falls System User genutzt wird).

### Schritt B: Konfiguration & Mapping
1.  **Credentials:** Tragen Sie die Daten aus Schritt A in die `.env` Datei auf dem Server ein (`SO_CLIENT_ID`, etc.).
2.  **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:
    ```bash
    python3 connector-superoffice/discover_fields.py
    ```
3.  **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:
1.  Kopieren Sie den Inhalt von `connector-superoffice/import_holidays_CRMSCRIPT.txt`.
2.  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.

```bash
# 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".