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

*   [ ] **UDF-Mapping:** Aktuell sind die `ProgId`s (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.