Merge branch 'main' of https://floke-gitea.duckdns.org/Floke/Brancheneinstufung2
This commit is contained in:
135
ARCHITEKTUR_GCP_SETUP.md
Normal file
135
ARCHITEKTUR_GCP_SETUP.md
Normal file
@@ -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<br/>(@roboplanet.de / @wackler-group.de)"]
|
||||
User --> CorpID
|
||||
end
|
||||
|
||||
subgraph Local_Execution ["⚙️ Execution Layer (Local/Server)"]
|
||||
Docker["🐳 Docker Container<br/>(GTM-Engine / Python)"]
|
||||
|
||||
subgraph Data_Handling ["🛡️ Daten-Verarbeitung"]
|
||||
RawData[("Rohdaten<br/>(Websites, Listen)")]
|
||||
Anonymizer["⚙️ Pre-Processing<br/>(Filterung PII / Personendaten)"]
|
||||
end
|
||||
|
||||
ResultStorage[("Ergebnisse<br/>(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<br/>(z.B. 'gtm-engine-prod')"]
|
||||
ServiceAccount["🤖 Service Account<br/>(Technischer User für API)"]
|
||||
Billing["💳 Corporate Billing<br/>(Zentrale Abrechnung)"]
|
||||
end
|
||||
|
||||
subgraph AI_Services ["🧠 AI Services (Vertex AI / Gemini)"]
|
||||
GeminiAPI["⚡ Gemini API<br/>(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<br/>(Nur Firmendaten)"| Docker
|
||||
Docker -->|"2. API Request (HTTPS/TLS)"| GeminiAPI
|
||||
GeminiAPI -->|"3. JSON Response<br/>(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 |
|
||||
102
SUPEROFFICE_INTEGRATION_PLAN.md
Normal file
102
SUPEROFFICE_INTEGRATION_PLAN.md
Normal file
@@ -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`).
|
||||
10
connector-superoffice/Dockerfile
Normal file
10
connector-superoffice/Dockerfile
Normal file
@@ -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"]
|
||||
21
connector-superoffice/main.py
Normal file
21
connector-superoffice/main.py
Normal file
@@ -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()
|
||||
4
connector-superoffice/requirements.txt
Normal file
4
connector-superoffice/requirements.txt
Normal file
@@ -0,0 +1,4 @@
|
||||
requests
|
||||
pydantic
|
||||
python-dotenv
|
||||
tenacity
|
||||
@@ -191,7 +191,7 @@
|
||||
<p>
|
||||
Zugriff auf die lokale Lead Engine.
|
||||
</p>
|
||||
<a href="http://192.168.178.6:8501/" class="btn" target="_blank">Starten →</a>
|
||||
<a href="/lead/" class="btn" target="_blank">Starten →</a>
|
||||
</div>
|
||||
|
||||
<!-- Meeting Assistant (Transcription) -->
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user