diff --git a/ARCHITEKTUR_GCP_SETUP.md b/ARCHITEKTUR_GCP_SETUP.md new file mode 100644 index 00000000..fa5b7d6b --- /dev/null +++ b/ARCHITEKTUR_GCP_SETUP.md @@ -0,0 +1,135 @@ +# Technisches Zielbild: GTM-Engine & Google Cloud Integration + +Dieses Dokument beschreibt die Architektur und den Datenfluss der **GTM-Engine (Go-to-Market Engine)**. + +## Executive Summary: Was wir tun +Wir automatisieren die **Qualifizierung von B2B-Accounts** (Firmen), um den Vertrieb gezielter und effizienter zu steuern ("Whale Hunting"). + +Anstatt dass ein Mitarbeiter manuell 20 Minuten lang Webseiten liest, um herauszufinden, ob eine Firma relevant ist, übernimmt dies das System automatisiert: +1. **Input:** Firmenname & Webseite (aus CRM oder Lead-Liste). +2. **Analyse:** Wir aggregieren öffentlich verfügbare Daten (Website-Text, Impressum, Wikipedia). +3. **KI-Verarbeitung:** Ein Sprachmodell (Gemini) agiert als "Lese-Assistent". Wir stellen ihm gezielte Fragen an den Kontext (z.B. *"Hat diese Firma mehr als 500 Mitarbeiter?", "Nutzen sie Roboter?", "Sind sie im Bereich Logistik tätig?"*). +4. **Output:** Strukturierte Daten (Branche, Potential-Score, Summary) fließen zurück ins CRM zur Vertriebssteuerung. + +**Wichtig:** Es findet **keine** automatisierte Entscheidung über natürliche Personen statt. Wir bewerten Firmen-Potentiale. + +## Kern-Prinzipien +1. **Trennung von Identität & Daten:** Nutzung von Unternehmens-Identitäten (Managed Google ID) statt privater Konten. +2. **Datensparsamkeit:** KI-Verarbeitung erfolgt primär auf anonymen Firmendaten (B2B), nicht auf Personendaten. +3. **Lokale Hoheit:** Die Business-Logik (Python/Docker) läuft kontrolliert lokal oder im Intranet, nicht "in der Cloud". + +## Architektur-Übersicht + +```mermaid +graph TD + %% Subgraph: Corporate Environment (Wackler/RoboPlanet) + subgraph Corporate_IT ["🏢 Wackler / RoboPlanet Umgebung"] + + subgraph User_Layer ["🧑‍💻 User & Identity"] + User[("Christian (User)")] + CorpID["Corporate Google ID
(@roboplanet.de / @wackler-group.de)"] + User --> CorpID + end + + subgraph Local_Execution ["⚙️ Execution Layer (Local/Server)"] + Docker["🐳 Docker Container
(GTM-Engine / Python)"] + + subgraph Data_Handling ["🛡️ Daten-Verarbeitung"] + RawData[("Rohdaten
(Websites, Listen)")] + Anonymizer["⚙️ Pre-Processing
(Filterung PII / Personendaten)"] + end + + ResultStorage[("Ergebnisse
(Notion / CRM / Excel)")] + end + end + + %% Subgraph: Google Cloud Platform (Managed) + subgraph Google_Cloud ["☁️ Google Cloud Platform (Enterprise Tenant)"] + + subgraph IAM_Security ["🔐 Security & Billing"] + GCP_Project["GCP Projekt
(z.B. 'gtm-engine-prod')"] + ServiceAccount["🤖 Service Account
(Technischer User für API)"] + Billing["💳 Corporate Billing
(Zentrale Abrechnung)"] + end + + subgraph AI_Services ["🧠 AI Services (Vertex AI / Gemini)"] + GeminiAPI["⚡ Gemini API
(Enterprise Mode: Zero Logging)"] + end + end + + %% Data Flow Connections + CorpID -.->|"Verwaltet"| GCP_Project + Docker -->|"Nutzt API Key"| ServiceAccount + ServiceAccount -->|"Authentifiziert"| GeminiAPI + + RawData --> Anonymizer + Anonymizer -->|"1. Anonymisierter Prompt
(Nur Firmendaten)"| Docker + Docker -->|"2. API Request (HTTPS/TLS)"| GeminiAPI + GeminiAPI -->|"3. JSON Response
(Strukturierte Daten)"| Docker + Docker -->|"4. Speicherung"| ResultStorage + + %% Styling + style Corporate_IT fill:#f9f9f9,stroke:#333,stroke-width:2px + style Google_Cloud fill:#e8f0fe,stroke:#4285f4,stroke-width:2px + style Anonymizer fill:#fff3e0,stroke:#f57c00,stroke-dasharray: 5 5 + style GeminiAPI fill:#e8f0fe,stroke:#4285f4,stroke-width:4px +``` + +## Erläuterung für die IT + +1. **Identity (IAM):** + * Es wird kein "Schatten-Account" genutzt. Christian authentifiziert sich mit seiner bestehenden Corporate Identity (`@roboplanet`). + * Für die automatisierte Ausführung (Skripte) wird später ein **Service Account** beantragt, dessen Schlüssel (JSON Key) sicher im lokalen Container verwaltet wird (Secrets Management). + +2. **Google Cloud Projekt:** + * Wir benötigen ein dediziertes GCP-Projekt (z.B. `rp-marketing-intel`), das im Rechnungskreis der Firma hängt. + * Vorteil: Volle Transparenz über Kosten und Nutzung im Admin-Dashboard der IT. + +3. **Environment Strategie (Dev/Prod Trennung):** + * Um Entwicklungskosten von Betriebskosten sauber zu trennen und die Stabilität zu gewährleisten, werden **zwei separate GCP-Projekte** empfohlen: + * **`rp-marketing-intel-dev`**: Sandbox für Entwicklung (Gemini CLI, Tests). Hier können Budgets gedeckelt und Quotas flexibel genutzt werden, ohne den Betrieb zu gefährden ("Blast Radius" Minimierung). + * **`rp-marketing-intel-prod`**: Stabile Umgebung für den Company Explorer. Exklusive Quotas und striktes Monitoring für den operativen Betrieb. + +4. **Datenschutz (DSGVO):** + * **Input:** Wir senden Webseiten-Texte und Firmennamen an die API. Wir senden *keine* Mitarbeiterlisten oder Kunden-Adressdaten zur Analyse. + * **Enterprise-Garantie:** Durch Nutzung der Enterprise-Verträge (via GCP) ist vertraglich geregelt, dass Google die Daten **nicht** zum Training eigener Modelle verwendet (anders als bei der kostenlosen ChatGPT/Gemini-Consumer-Version). + +## Backend API (Company Explorer) + +Das System verfügt bereits über eine standardisierte, dokumentierte API (FastAPI) zur Datenverarbeitung. Dies ermöglicht eine saubere Trennung von Frontend und Backend sowie eine granulare Zugriffskontrolle. + +**Core Endpoints:** + +| Methode | Pfad | Beschreibung | +| :--- | :--- | :--- | +| `GET` | `/api/health` | System Status Check | +| `GET` | `/api/companies` | Liste von Unternehmen (Filterbar, Sortierbar) | +| `GET` | `/api/companies/{id}` | Detailansicht eines Unternehmens | +| `POST` | `/api/companies` | Manuelle Anlage eines Unternehmens | +| `POST` | `/api/companies/bulk` | Massenimport (Batch-Processing) | +| `GET` | `/api/companies/export` | CSV Export der angereicherten Daten | + +**Enrichment & KI-Analyse:** + +| Methode | Pfad | Beschreibung | +| :--- | :--- | :--- | +| `POST` | `/api/enrich/discover` | Startet Discovery-Prozess (Website-Suche) | +| `POST` | `/api/enrich/analyze` | Startet KI-Analyse (Scraping + Klassifizierung) | +| `PUT` | `/api/companies/{id}/industry` | Manuelle Korrektur der KI-Branchenzuordnung | +| `POST` | `/api/companies/{id}/override/*` | Manuelle Overrides für kritische Datenquellen (Website, Wikipedia, Impressum) | + +**Quality Assurance:** + +| Methode | Pfad | Beschreibung | +| :--- | :--- | :--- | +| `POST` | `/api/companies/{id}/report-mistake` | Melden von Datenfehlern ("Human in the Loop") | +| `GET` | `/api/mistakes` | Übersicht gemeldeter Fehler zur Überprüfung | +| `PUT` | `/api/mistakes/{id}` | Status-Update für Fehlermeldungen (Approved/Rejected) | + +**Stammdaten & Kataloge:** + +| Methode | Pfad | Beschreibung | +| :--- | :--- | :--- | +| `GET` | `/api/robotics/categories` | Katalog der Robotik-Kategorien | +| `GET` | `/api/industries` | Katalog der Branchen | +| `GET` | `/api/job_roles` | Katalog der Job-Rollen | diff --git a/SUPEROFFICE_INTEGRATION_PLAN.md b/SUPEROFFICE_INTEGRATION_PLAN.md new file mode 100644 index 00000000..47265810 --- /dev/null +++ b/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
(Contact)")] + SO_UDF[("KI-Felder
(UDFs)")] + end + + subgraph Middleware ["Integration Layer (Docker)"] + Connector["🔄 SuperOffice Connector
(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`). diff --git a/connector-superoffice/Dockerfile b/connector-superoffice/Dockerfile new file mode 100644 index 00000000..7cd99fe7 --- /dev/null +++ b/connector-superoffice/Dockerfile @@ -0,0 +1,10 @@ +FROM python:3.9-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY . . + +CMD ["python", "main.py"] diff --git a/connector-superoffice/main.py b/connector-superoffice/main.py new file mode 100644 index 00000000..acea9a6c --- /dev/null +++ b/connector-superoffice/main.py @@ -0,0 +1,21 @@ +import os +import logging +from dotenv import load_dotenv + +# Setup basic logging +logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s') +logger = logging.getLogger(__name__) + +# Load environment variables +load_dotenv() + +def main(): + logger.info("Starting SuperOffice Connector...") + + # TODO: Implement authentication logic here using Gemini CLI + # TODO: Implement Polling / Sync logic here + + logger.info("Connector stopped.") + +if __name__ == "__main__": + main() diff --git a/connector-superoffice/requirements.txt b/connector-superoffice/requirements.txt new file mode 100644 index 00000000..6e9be739 --- /dev/null +++ b/connector-superoffice/requirements.txt @@ -0,0 +1,4 @@ +requests +pydantic +python-dotenv +tenacity diff --git a/dashboard/index.html b/dashboard/index.html index 8a581be6..f8be8b15 100644 --- a/dashboard/index.html +++ b/dashboard/index.html @@ -191,7 +191,7 @@

Zugriff auf die lokale Lead Engine.

- Starten → + Starten → diff --git a/nginx-proxy.conf b/nginx-proxy.conf index 792dddf5..572f4726 100644 --- a/nginx-proxy.conf +++ b/nginx-proxy.conf @@ -133,5 +133,21 @@ http { proxy_connect_timeout 1800s; proxy_send_timeout 1800s; } + + location /lead/ { + # Lead Engine (TradingTwins) + # Proxying external service on host + proxy_pass http://192.168.178.6:8501/; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Websocket support for Streamlit + proxy_http_version 1.1; + + # Explicit timeouts + proxy_read_timeout 86400; # Long timeout for stream + } } }