[2ff88f42] Full End-to-End integration: Webhooks, Auto-Enrichment, Notion-Sync, UI updates and new Connector Architecture
This commit is contained in:
@@ -7,40 +7,48 @@ Automatisierte Anreicherung von B2B-Firmendaten im CRM mit KI-generierten Insigh
|
||||
|
||||
---
|
||||
|
||||
## 1. Architektur: Der "SuperOffice Connector"
|
||||
## 1. Architektur: "Event-Driven Messaging" (v2.0)
|
||||
|
||||
Wir implementieren einen dedizierten Microservice (`connector-superoffice`), der als Brücke fungiert.
|
||||
Wir haben die Architektur von einem Polling-Modell auf ein **Event-gesteuertes Webhook-Modell** umgestellt. Dies entspricht modernen Best Practices und ist Voraussetzung für eine Skalierung auf 16.000+ Firmen.
|
||||
|
||||
### Das Prinzip: "Gehirn & Muskel"
|
||||
|
||||
* **Das Gehirn (Company Explorer):** Hier liegt die gesamte Intelligenz. Die Datenbank speichert die Firmendaten, die Signale und die **Marketing-Matrix** (Textbausteine). Er entscheidet, *welcher* Text für *welchen* Kontakt generiert wird.
|
||||
* **Der Muskel (Connector):** Er ist ein "dummer" Bote. Er nimmt Events entgegen, fragt das Gehirn nach Anweisungen und führt diese in SuperOffice aus.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph CRM ["SuperOffice CRM (Cloud/On-Prem)"]
|
||||
SO_DB[("Stammdaten<br/>(Contact)")]
|
||||
SO_UDF[("KI-Felder<br/>(UDFs)")]
|
||||
graph TD
|
||||
subgraph "SuperOffice CRM"
|
||||
SO_Contact["👤 Contact / Person"]
|
||||
SO_Webhook["🚀 Webhook<br/>(contact.changed)"]
|
||||
end
|
||||
|
||||
subgraph Middleware ["Integration Layer (Docker)"]
|
||||
Connector["🔄 SuperOffice Connector<br/>(Python Service)"]
|
||||
subgraph "Connector (Docker)"
|
||||
WebhookApp["📥 Webhook Receiver<br/>(FastAPI :8002)"]
|
||||
Queue[("📦 Job Queue<br/>(SQLite/Redis)")]
|
||||
Worker["👷♂️ Worker Process"]
|
||||
end
|
||||
|
||||
subgraph Intelligence ["GTM Engine"]
|
||||
CE_API["⚡ Company Explorer API"]
|
||||
CE_DB[("Enrichment DB")]
|
||||
subgraph "Company Explorer (Docker)"
|
||||
CE_API["🧠 Provisioning API<br/>(:8000)"]
|
||||
MatrixDB[("📚 Marketing Matrix<br/>(SQLite)")]
|
||||
end
|
||||
|
||||
%% Data Flow
|
||||
SO_DB -->|"1. Pull (Delta/Initial)"| Connector
|
||||
Connector -->|"2. Push (Import)"| CE_API
|
||||
CE_API -.->|"3. Enrichment Process"| CE_DB
|
||||
CE_DB -->|"4. Result"| CE_API
|
||||
Connector -->|"5. Poll Results"| CE_API
|
||||
Connector -->|"6. Write-Back (Update UDFs)"| SO_UDF
|
||||
|
||||
%% Styling
|
||||
style CRM fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
|
||||
style Middleware fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
|
||||
style Intelligence fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
|
||||
SO_Contact -->|1. Änderung| SO_Webhook
|
||||
SO_Webhook -->|2. POST Event| WebhookApp
|
||||
WebhookApp -->|3. Enqueue Job| Queue
|
||||
Worker -->|4. Fetch Job| Queue
|
||||
Worker -->|5. Request: 'Provision Me'| CE_API
|
||||
CE_API -->|6. Lookup Logic| MatrixDB
|
||||
CE_API -->|7. Return: Final Texts| Worker
|
||||
Worker -->|8. Write-Back UDFs| SO_Contact
|
||||
```
|
||||
|
||||
**Technische Kommunikation:**
|
||||
Da beide Services (`connector-superoffice` und `company-explorer`) im selben Docker-Netzwerk laufen, erfolgt die Kommunikation direkt und latenzfrei über den internen Docker-DNS (`http://company-explorer:8000`). Es gibt keinen Umweg über das öffentliche Internet.
|
||||
|
||||
## 2. Datenmodell & Erweiterung
|
||||
|
||||
## 2. Datenmodell & Erweiterung
|
||||
|
||||
Um die CRM-Daten sauber zu halten, schreiben wir **niemals** in Standardfelder (wie `Name`, `Department`), sondern ausschließlich in dedizierte, benutzerdefinierte Felder (**User Defined Fields - UDFs**).
|
||||
@@ -61,6 +69,17 @@ Folgende Felder sollten am Objekt `Company` (bzw. `Contact` in SuperOffice-Termi
|
||||
| :--- | :--- | :--- |
|
||||
| `external_crm_id` | String/Int | Speichert die `ContactId` aus SuperOffice zur eindeutigen Zuordnung (Primary Key Mapping). |
|
||||
|
||||
### 2.2. Data Integrity: "The Double Truth"
|
||||
|
||||
Um die Datenqualität zu sichern, pflegen wir für Stammdaten (Name, Website) zwei Wahrheiten:
|
||||
1. **CRM Truth:** Was aktuell in SuperOffice steht (oft manuell gepflegt, potenziell veraltet).
|
||||
2. **Explorer Truth:** Was der Company Explorer im Web gefunden hat.
|
||||
|
||||
**Synchronisation:**
|
||||
* Bei jedem Webhook-Event sendet der Connector die aktuellen CRM-Werte (`crm_name`, `crm_website`) an den Company Explorer.
|
||||
* Der Company Explorer speichert diese und berechnet einen **`data_mismatch_score`** (0.0 = Match, 1.0 = Mismatch).
|
||||
* **UI:** Im Frontend wird dieser Score visualisiert, sodass Abweichungen sofort erkennbar sind.
|
||||
|
||||
## 2.1. Mapping of CRM Concepts (SuperOffice vs. D365)
|
||||
|
||||
Um die Integration effizient zu gestalten, wurde eine strategische Entscheidung bezüglich der Abbildung von Kern-CRM-Konzepten getroffen:
|
||||
@@ -88,15 +107,16 @@ Um die Integration effizient zu gestalten, wurde eine strategische Entscheidung
|
||||
2. Für jeden Treffer sendet er ein Update an die SuperOffice API (`PUT /Contact/{id}`).
|
||||
3. Es werden nur die oben definierten UDFs aktualisiert.
|
||||
|
||||
### Phase 3: Continuous Sync (Polling)
|
||||
*Ziel: Neue Firmen automatisch verarbeiten.*
|
||||
### Phase 3: Continuous Sync (Event-Driven)
|
||||
*Ziel: Skalierbare, echtzeitnahe Verarbeitung.*
|
||||
|
||||
1. **Zyklus:** Alle 60 Minuten.
|
||||
2. **Logik:** "Gib mir alle Firmen, die seit `LAST_RUN` erstellt oder geändert wurden."
|
||||
3. **Aktion:** Neue Firmen werden automatisch zur Analyse geschickt.
|
||||
4. **Vorteil:** Keine komplexe Firewall-Konfiguration für eingehende Webhooks nötig (Outbound-Only Traffic).
|
||||
|
||||
---
|
||||
1. **Auslöser:** Ein `contact.changed` oder `person.changed` Event in SuperOffice (z.B. User setzt Status auf `Init`).
|
||||
2. **Transport:** SuperOffice Webhook -> Connector `POST /webhook` -> Queue.
|
||||
3. **Verarbeitung:** Der `Worker` holt den Job, ruft die **Provisioning API** des Company Explorer auf.
|
||||
4. **Vorteil:**
|
||||
* **Kein unnötiger Traffic:** Wir verarbeiten nur Kontakte, bei denen wirklich etwas passiert.
|
||||
* **Echtzeit:** Änderungen sind sofort wirksam.
|
||||
* **SO-Konformität:** Wir nutzen den offiziellen, effizienten Weg für Integrationen.
|
||||
|
||||
## 4. Sicherheit & Authentifizierung
|
||||
|
||||
|
||||
Reference in New Issue
Block a user