# 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):

```yaml
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`
```json
{
  "so_contact_id": 12345,
  "so_person_id": 67890,
  "crm_name": "RoboPlanet GmbH",
  "crm_website": "www.roboplanet.de",
  "job_title": "Geschäftsführer"
}
```

**Response:**
```json
{
  "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 `ProgId`s 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.