# 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: Der "SuperOffice Connector"

Wir implementieren einen dedizierten Microservice (`connector-superoffice`), der als Brücke fungiert.

```mermaid
graph LR
    subgraph CRM ["SuperOffice CRM (Cloud/On-Prem)"]
        SO_DB[("Stammdaten<br/>(Contact)")]
        SO_UDF[("KI-Felder<br/>(UDFs)")]
    end

    subgraph Middleware ["Integration Layer (Docker)"]
        Connector["🔄 SuperOffice Connector<br/>(Python Service)"]
    end

    subgraph Intelligence ["GTM Engine"]
        CE_API["⚡ Company Explorer API"]
        CE_DB[("Enrichment DB")]
    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
```

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

### 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.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 (Polling)
*Ziel: Neue Firmen automatisch verarbeiten.*

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

---

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