Brancheneinstufung2/SUPEROFFICE_INTEGRATION_PLAN.md

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.

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

---

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.

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