90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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. |