# Technisches Konzept: SuperOffice CRM Integration

Dieses Dokument beschreibt die Integrationsstrategie zwischen **SuperOffice CRM** (führendes System für Stammdaten) und dem **Company Explorer** (KI-gestützte Anreicherungs-Engine).

## Zielsetzung
Automatisierte Anreicherung von B2B-Firmendaten im CRM mit KI-generierten Insights (z.B. Robotik-Affinität, Branchen-Einstufung), ohne die Hoheit über die Stammdaten zu gefährden.

---

## 1. Architektur: "Event-Driven Messaging" (v2.0)

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 TD
    subgraph "SuperOffice CRM"
        SO_Contact["👤 Contact / Person"]
        SO_Webhook["🚀 Webhook<br/>(contact.changed)"]
    end

    subgraph "Connector (Docker)"
        WebhookApp["📥 Webhook Receiver<br/>(FastAPI :8002)"]
        Queue[("📦 Job Queue<br/>(SQLite/Redis)")]
        Worker["👷‍♂️ Worker Process"]
    end

    subgraph "Company Explorer (Docker)"
        CE_API["🧠 Provisioning API<br/>(:8000)"]
        MatrixDB[("📚 Marketing Matrix<br/>(SQLite)")]
    end

    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**).

### Benötigte Felder in SuperOffice (Anforderung an IT/Admin)
Folgende Felder sollten am Objekt `Company` (bzw. `Contact` in SuperOffice-Terminologie) angelegt werden:

| Feldname (Label) | Typ | Zweck |
| :--- | :--- | :--- |
| `AI Robotics Potential` | List/Select | High / Medium / Low / None |
| `AI Industry` | Text (Short) | KI-ermittelte Branche (z.B. "Logistik - Intralogistik") |
| `AI Summary` | Text (Long/Memo) | Kurze Zusammenfassung der Analyse |
| `AI Last Update` | Date | Zeitstempel der letzten Anreicherung |
| `AI Status` | List/Select | Pending / Enriched / Error |
| `Unsubscribe-Link` | Text/Link | **NEU:** Speichert den personalisierten Link zur Abmeldung von der Marketing-Automation. (ProgID: SuperOffice:9) |

### Benötigtes Feld im Company Explorer
| Feldname | Typ | Zweck |
| :--- | :--- | :--- |
| `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:

| D365 Konzept | SuperOffice Entität | Zweck & Begründung |
| :--- | :--- | :--- |
| **Opportunity** | `Sale` | Die `Sale`-Entität in SuperOffice ist das direkte Äquivalent zu einer Opportunity. Hier werden potenzielle Umsätze, Vertriebsphasen und Wahrscheinlichkeiten erfasst. Dies ist das primäre Zielobjekt, sobald eine konkrete Verkaufschance durch den Company Explorer identifiziert wird. |
| **Campaign** | `Project` | Für Marketing-Automatisierung und die Bündelung von Kontakten für Kampagnen dient die `Project`-Entität als idealer Container. Sie ermöglicht es, Kampagnen-Teilnehmer zu gruppieren, Aktivitäten zuzuordnen und den ROI durch Verknüpfung mit `Sale`-Objekten zu messen. |

---

## 3. Phasenplan

### Phase 1: Initial Load (Snapshot)
*Ziel: Bestandskunden und aktive Leads einmalig bewerten.*

1.  **Filter:** Der Connector lädt alle Firmen mit Status "Kunde" oder "Prospect".
2.  **Import:** Daten werden via `POST /api/companies/bulk` an den Explorer gesendet. Die `ContactId` wird mitgegeben.
3.  **Verarbeitung:** Der Explorer arbeitet die Queue ab (Web-Scraping -> Klassifizierung).

### Phase 2: Write-Back (Ergebnisse speichern)
*Ziel: Ergebnisse im CRM sichtbar machen.*

1.  Der Connector prüft regelmäßig (`GET /api/companies?status=ENRICHED`) auf fertige Analysen.
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 (Event-Driven)
*Ziel: Skalierbare, echtzeitnahe Verarbeitung.*

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

*   **Authentifizierung:** Nutzung eines **System User Tokens** (Machine-to-Machine). Dies verhindert, dass Passwörter von persönlichen Accounts im Code hinterlegt werden müssen.
*   **Scope:** Der API-User benötigt Lesezugriff auf `Contact` und Schreibzugriff auf die `UDFs`.
*   **Datenschutz:** Es werden nur Firmendaten (Name, Webseite, Stadt) übertragen. Personenbezogene Ansprechpartner bleiben im CRM und werden nicht an die KI gesendet.

### 4.1. POC Ergebnisse & Finale Authentifizierungs-Strategie (Feb 2026)

Der Proof of Concept (POC) wurde erfolgreich abgeschlossen. Dabei wurde die Authentifizierungs-Strategie für maximale Stabilität und Einfachheit angepasst.

**Ergebnis:**
*   **Erfolg:** Die Verbindung zum SOD-Tenant (`Cust55774`) steht. Der Connector kann Daten lesen und ist bereit zum Schreiben.
*   **Strategiewechsel:** Statt des komplexen RSA-S2S-Flows wird der **OAuth 2.0 Refresh Token Flow** genutzt. Dies umgeht Lizenz- und UI-Einschränkungen in der SOD-Umgebung und bietet dieselbe Automatisierungsqualität für den Docker-Service.
*   **Subdomain-Handling:** Es wurde festgestellt, dass SuperOffice Online (SOD) mandantenabhängige Subdomains nutzt. Für den Test-Tenant wurde **`https://app-sod.superoffice.com`** als valide API-Basis identifiziert.

**Technische Umsetzung:**
1.  **Einmalige Autorisierung:** Ein langlebiger `refresh_token` wurde über einen manuellen Consent-Step generiert.
2.  **Automatisierung:** Der `AuthHandler` tauscht diesen Token vollautomatisch gegen kurzlebige `access_tokens` (Bearer) aus.
3.  **Caching:** Tokens werden lokal in `token_cache.json` gespeichert, um API-Limits zu schonen.

**Aktueller Status & Nächste Schritte:**
*   **Blocker gelöst:** Die Authentifizierung und das URL-Routing sind stabil.
*   **Nächster Schritt:** Manuelle Anlage der UDF-Felder (siehe Abschnitt 2) in der SuperOffice Administration durch den Admin. Erst danach kann der "Write-Back" (Phase 2) im Code final gemappt werden.

## 5. Vorbereitung für die IT

Um den Connector in Betrieb zu nehmen, benötigen wir:
1.  **API Zugangsdaten:** `Client ID`, `Client Secret`, `Customer ID` (Tenant) und einen `System User Token`.
2.  **UDF Definitionen:** Die `ProgId` (technischen Namen) der neu angelegten Felder (z.B. `userdef_id_123`).

## 6. Fragen an Manuel

1. Die "Lizenz-Gretchenfrage" (Development Tools)
Frage: "Manuel, du sagtest, bei Wackler sind die 'Development Tools' aktiv. Weißt du, ob das eine globale Konzern-Lizenz ist oder ob wir für den RoboPlanet-Mandanten eine eigene Subskription brauchen? Mein Dev-Portal blockiert S2S aktuell mit dem Hinweis auf fehlende Lizenzen in Production."
Ziel: Klären, ob es nur ein "Klick" im Admin-Panel ist oder ob Webkom (oder ein anderer Partner) eine neue Rechnung schreiben muss.

2. Der App-Registrierungs-Pfad
Frage: "Hast du eure App als 'Custom Application' (privat für Wackler) oder als 'Standard Application' (über einen Partner-Account) registriert? Falls ihr einen Partner-Account nutzt: Könnten wir unsere GTM-Engine darüber mitlaufen lassen, um die Lizenz-Hürde zu umgehen?"
Ziel: Prüfen, ob Manuel über ein Partner-Portal arbeitet. Partner-Apps brauchen manchmal keine Dev-Tools beim Kunden, weil der Partner die Validierung übernimmt.

3. Identifikation des "Gatekeepers"
Frage: "Wer hat bei euch den Tenant technisch aufgesetzt? War das die Webkom? Ich muss herausfinden, wer die administrative Hoheit hat, um den 'System User' für S2S freizuschalten."
Ziel: Den Namen des Ansprechpartners bei der Webkom oder intern bei Wackler-IT herausfinden.

4. Authentifizierungs-Deep-Dive (RSA vs. Token)
Frage: "Nutzt ihr für eure S2S-App den RSA-Key-Flow (JWT) oder arbeitet ihr mit einem statischen System-User-Token? Ich bereite gerade den RSA-Handshake vor und wollte wissen, was in der SuperOffice Cloud stabiler läuft."
Ziel: Fachsimpelei, um Manuel zu zeigen, dass du auf seinem Level spielst. Das öffnet Türen für Code-Sharing oder Tipps.

5. Das "Y-Tabellen" Problem
Frage: "Nutzt ihr für eure Verkaufs-App auch Zusatztabellen (Y-Tabellen) oder schreibt ihr nur in Standardfelder? Ich plane eine Tabelle für dynamische Marketing-Texte (Rolle x Branche) – gab es bei euch Probleme mit dem Cache nach Strukturänderungen?"
Ziel: Bestätigung einholen, dass Y-Tabellen mit ihrer Lizenz funktionieren. Das ist dein Beweis, dass du die Dev-Tools zwingend brauchst.

6. Authentifizierung beim S2S Call
Wie authentifiziert ihr euch beim S2S-Call? Nutzt ihr den RSA-Flow mit Zertifikaten oder habt ihr einen Partner-Proxy dazwischen?" (Wenn er "Partner-Proxy" sagt, arbeitet er über Webkom-Infrastruktur).

7. Nutzung System User
Wo habt ihr den 'System User' im CRM autorisiert?" (Er soll dir den Pfad in Einstellungen & Verwaltung zeigen).

8. Header API-Call
Könntest du mir den Header eines eurer API-Calls zeigen (natürlich ohne den echten Token)?" (Daran sehen wir sofort, ob sie die v1 REST API oder die alte SOAP-Schnittstelle nutzen).