docs: add strategic integration plan for SuperOffice CRM

SUPEROFFICE_INTEGRATION_PLAN.md

@@ -0,0 +1,102 @@
+# 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). |
+
+---
+
+## 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`).