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

## Anleitung für IT & Setup (Schritt-für-Schritt)

Ziel: Bereitstellung von zwei GCP-Projekten für die Nutzung von Vertex AI / Gemini API durch Christian (Floke).

### Schritt 1: Projekte anlegen (Durch IT Admin)
Bitte in der Google Cloud Console (`console.cloud.google.com`) zwei neue Projekte erstellen.
*   **Projekt 1 Name:** `roboplanet-ai-dev` (Sandbox/Entwicklung)
*   **Projekt 2 Name:** `roboplanet-ai-prod` (Live-System/Tools)
*   **Organisation:** `wackler-group.de` (oder entsprechende Root-Org).

### Schritt 2: Billing verknüpfen (Durch IT Admin)
Beide Projekte müssen mit dem zentralen Firmen-Rechnungskonto (Billing Account) verknüpft werden.
*   In der Projektübersicht -> "Abrechnung" -> "Abrechnung verknüpfen".
*   Dies ist zwingend erforderlich, um kostenpflichtige APIs (Vertex AI) nutzen zu können.

### Schritt 3: Berechtigungen für Christian setzen (Durch IT Admin)
Christian benötigt vollen Zugriff auf diese Projekte, um APIs zu aktivieren und Keys zu verwalten.
*   Gehe zu **IAM & Verwaltung** -> **IAM**.
*   Füge User `christian.floke@...` hinzu (bzw. deine exakte Mail).
*   **Rolle:** `Inhaber` (Owner) oder mindestens `Editor` + `Project IAM Admin` + `Service Usage Admin`.

### Schritt 4: API Aktivierung & Key-Erstellung (Durch Christian / Floke)
Sobald die Projekte da sind, führe ich folgende Schritte durch:

1.  **Login im Google AI Studio:**
    *   Gehe auf [aistudio.google.com](https://aistudio.google.com).
    *   Login mit dem Wackler-Konto.

2.  **Projekt-Verknüpfung (Der "Enterprise Switch"):**
    *   Klick auf "Settings" oder "API Key".
    *   Wähle **"Link to Google Cloud Project"**.
    *   Wähle `roboplanet-ai-dev` (oder `prod`) aus der Liste aus.
    *   *Effekt:* Ab jetzt läuft die Abrechnung über GCP (Pay-per-Use) und es gelten die Enterprise-Datenschutzbedingungen (Kein Training).

3.  **API Key erstellen:**
    *   Klick auf **"Create API Key"**.
    *   Wähle das verknüpfte GCP-Projekt.
    *   Kopiere den Key (`AIza...`) sicher weg.

4.  **Environment Variablen setzen (Lokal):**
    Damit wir Dev und Prod sauber trennen, nutzen wir standardisierte Variablennamen in `.env` Dateien:
    *   `GEMINI_API_KEY_DEV` -> Für CLI, OpenClaw, lokale Tests (Projekt: `roboplanet-ai-dev`)
    *   `GEMINI_API_KEY_PROD` -> Für Company Explorer, GTM-Engine (Projekt: `roboplanet-ai-prod`)

### Checklist für den Termin
- [ ] Projekte `roboplanet-ai-dev` und `roboplanet-ai-prod` existieren.
- [ ] Billing ist auf beiden Projekten aktiv (kein "Free Trial" Limit, sondern echtes Billing).
- [ ] Mein User hat `Owner` Rechte auf den Projekten.

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

## Datenschutz- & Lizenz-Architektur (Das Zwei-Wege-Modell)

Um maximale Sicherheit und Compliance zu gewährleisten, trennen wir technisch strikt zwischen **Automatisierung** (Massenverarbeitung) und **Assistenz** (Ad-hoc Arbeit).

```mermaid
flowchart TD
    User[User: Floke]
    
    subgraph Safe_Space_GCP ["Pfad A: Die Engine (Automation)"]
        style Safe_Space_GCP fill:#e6f4ea,stroke:#137333
        API[Python Scripts / GTM-Engine] --> Vertex[Google Vertex AI API]
        Vertex --> Processing[Data Processing in EU]
        Processing -- "No Training / Zero Retention" --> Output_API[Strukturierte Daten]
    end

    subgraph Safe_Space_Workspace ["Pfad B: Der Assistent (Custom Chat)"]
        style Safe_Space_Workspace fill:#e8f0fe,stroke:#1967d2
        Browser[Browser / Local App] --> PythonApp[Custom Python Chatbot]
        PythonApp -- "Nutzt API Key" --> Vertex
    end

    User -- "Programming / CLI" --> API
    User -- "Manual / Chat" --> Browser
```

### Pfad A: Die Engine (Google Cloud Platform / Vertex AI)
*   **Einsatzzweck:** Automatisierte Skripte, Massenanalyse (GTM-Engine), Coding.
*   **Lizenz:** Pay-per-Use (über GCP Projekt). Keine User-Lizenz erforderlich.
*   **Datenschutz:**
    *   **GCP Enterprise Terms:** Standardmäßig **kein Training** auf Kundendaten.
    *   **Region Lock:** Datenverarbeitung wird technisch auf `europe-west3` (Frankfurt) oder `europe-west4` gezwungen.
    *   **Zero Retention:** API-Calls werden nach Verarbeitung gelöscht (stateless).

### Pfad B: Der Assistent (Lokaler Chatbot)
*   **Einsatzzweck:** Ad-hoc Chat und Textarbeit.
*   **Lösung:** Da wir keine Gemini-Lizenzen für 350 User kaufen, bauen wir ein **eigenes, leichtgewichtiges Chat-Interface** (Python Streamlit).
*   **Datenschutz:** Dieses Tool greift auf **Pfad A (GCP API)** zu.
    *   Vorteil: Wir nutzen die sichere Enterprise-API, ohne Office-Lizenzen ändern zu müssen.
    *   Daten bleiben im kontrollierten GCP-Bereich.

## Strategie zur Lizenzierung & Kosten (Der "Cloud Identity Free" Ansatz)

**Ausgangslage:**
RoboPlanet nutzt aktuell den **"Cloud Identity Free"** Tarif (primär für Android-Geräte-Verwaltung). Ein Upgrade auf kostenpflichtige Workspace-Lizenzen für alle 350+ User würde immense Fixkosten verursachen.

**Lösung: Entkopplung von User-Lizenz und KI-Leistung**
Wir vermeiden ein globales Lizenz-Upgrade. Stattdessen nutzen wir die **Google Cloud Platform (GCP)**.
*   **Technik:** GCP-Projekte sind technisch vom Office-Tarif entkoppelt.
*   **Kosten:** Wir zahlen rein nutzungsbasiert (Pay-per-Use) für die API-Aufrufe.
*   **Vorteil:** Keine Änderung am bestehenden "Free Tier" Vertrag notwendig. Enterprise-Security gilt im GCP-Projekt automatisch.

## Spickzettel für den Termin (Fragen & Argumente)

### 1. Zum Lizenz-Status ("Kostenvermeidung")
**Argument:**
"Wir wollen auf keinen Fall für 350 User neue Lizenzen kaufen müssen, nur damit ich KI nutzen kann. Da wir im 'Cloud Identity Free' Tarif sind, ist der Weg über die **Google Cloud Platform (GCP)** der einzig sinnvolle. Dort zahlen wir nur, was wir verbrauchen (Pay-per-Use), ohne den Hauptvertrag anzufassen."

### 2. Zur Architektur ("Safe Space GCP")
**Argument:**
"Im GCP-Projekt gelten automatisch die B2B-Enterprise-Terms (kein Training auf Daten), egal welchen Status mein User hat. Ich werde technisch erzwingen, dass die Datenverarbeitung in **Frankfurt (europe-west3)** stattfindet."

### 3. Zur Datennutzung
**Angebot:**
"Ich richte eine strikte Trennung ein:
*   **Entwicklung (Dev):** Hier testen wir.
*   **Produktion (Prod):** Hier laufen die Tools.
Dadurch verhindern wir, dass Testdaten in produktive Systeme gelangen oder Kosten aus dem Ruder laufen."

## Vorlage: Nachricht an die IT (Teams/Mail)

Hi [Name],

ich habe mich nochmal tiefer in die Google-Lizenz-Thematik eingegraben. Da wir ja aktuell im 'Cloud Identity Free' Tarif sind (primär für die Android-Geräte), würde ein Upgrade oder Lizenz-Wechsel bei 350 Usern ja sofort massive Kosten verursachen. Das wollen wir auf keinen Fall auslösen, nur weil ich ein Tool brauche.

**Daher mein Vorschlag für den schlanken Weg:**
Wir lassen an den User-Konten/Lizenzen (Free Tier) alles exakt so, wie es ist.
Stattdessen nutzen wir für meine KI-Themen einfach die **Google Cloud Platform (GCP)**. Ich habe gesehen, dass ich darauf mit meinem User sogar schon Zugriff habe.

Das GCP-Projekt ist technisch komplett unabhängig vom Office-Tarif. Wir zahlen dort rein **Pay-per-Use** für die API-Aufrufe (oft nur Cent-Beträge im laufenden Betrieb).

**Was mir dafür noch fehlt, ist das 'Billing' (Rechnungskonto):**
Aktuell kann ich keine APIs aktivieren, weil kein Zahlungsmittel hinterlegt ist.

**Meine Bitte:**
Könntet ihr mir bitte **zwei Projekte** anlegen und mit dem zentralen Firmen-Rechnungskonto verknüpfen?

1.  `roboplanet-ai-dev` (Für Entwicklung & Tests, Sandbox)
2.  `roboplanet-ai-prod` (Für den stabilen Betrieb der Tools)

Danach könnt ihr mir einfach **Owner-Rechte** auf diese beiden Projekte geben. Den Rest (API-Aktivierung, Service Accounts, Region-Lock auf Frankfurt) richte ich dann selbst ein.

Das wäre die sauberste Lösung: Keine Fixkosten durch Lizenz-Upgrades, klare Trennung von Spielwiese und Produktion, und volle Kostentransparenz.

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