[2ff88f42] Finalize SuperOffice Integration: Enhanced Persona model with Influencer role, switched Matrix Generator to Gemini, implemented Noise Reduction for Webhooks, and added E2E test scenarios.
This commit is contained in:
@@ -1,100 +1,75 @@
|
||||
# SuperOffice Connector ("The Muscle") - GTM Engine
|
||||
# SuperOffice Connector ("The Muscle") - GTM Engine v2.0
|
||||
|
||||
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.
|
||||
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: "The Intelligent Hub & The Loyal Messenger"
|
||||
## 1. Architektur: "Noise-Reduced Event Pipeline"
|
||||
|
||||
Wir haben uns für eine **Event-gesteuerte Architektur** entschieden, um Skalierbarkeit und Echtzeit-Verarbeitung zu gewährleisten.
|
||||
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:** 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.
|
||||
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. Kern-Komponenten
|
||||
## 2. 🚀 Go-Live Checkliste (User Tasks)
|
||||
|
||||
* **`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`.
|
||||
Um das System auf der Produktivumgebung ("Live") in Betrieb zu nehmen, müssen folgende Schritte durchgeführt werden:
|
||||
|
||||
* **`queue_manager.py` (SQLite):**
|
||||
* Verwaltet die lokale Job-Queue.
|
||||
* Status: `PENDING` -> `PROCESSING` -> `COMPLETED` / `FAILED`.
|
||||
* Persistiert Jobs auch bei Container-Neustart.
|
||||
### 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).
|
||||
|
||||
* **`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.
|
||||
### 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.
|
||||
|
||||
* **`superoffice_client.py`:**
|
||||
* Kapselt die SuperOffice REST API (Auth, GET, PUT).
|
||||
* Verwaltet Refresh Tokens.
|
||||
### 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`.
|
||||
|
||||
## 3. Setup & Konfiguration
|
||||
### 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.
|
||||
|
||||
### Docker Service
|
||||
Der Service läuft im Container `connector-superoffice`.
|
||||
Startet via `start.sh` sowohl den Webserver als auch den Worker.
|
||||
## 3. Business Logik & Features
|
||||
|
||||
### Konfiguration (`.env`)
|
||||
Der Connector benötigt folgende Variablen (in `docker-compose.yml` gesetzt):
|
||||
### 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).
|
||||
|
||||
```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.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
|
||||
```
|
||||
|
||||
## 4. API-Schnittstelle (Intern)
|
||||
## 5. Roadmap (v2.1)
|
||||
|
||||
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.
|
||||
* [ ] **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".
|
||||
Reference in New Issue
Block a user