From d28a8a2eee37d44073d176d327870269ad2e86a9 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 9 Feb 2026 07:51:07 +0000 Subject: [PATCH] docs: Add step-by-step IT setup guide for GCP Dev/Prod projects --- ARCHITEKTUR_GCP_SETUP.md | 112 +++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 62 deletions(-) diff --git a/ARCHITEKTUR_GCP_SETUP.md b/ARCHITEKTUR_GCP_SETUP.md index 04333e9f..9e8dd2a3 100644 --- a/ARCHITEKTUR_GCP_SETUP.md +++ b/ARCHITEKTUR_GCP_SETUP.md @@ -18,6 +18,56 @@ Anstatt dass ein Mitarbeiter manuell 20 Minuten lang Webseiten liest, um herausz 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. Diesen nutze ich in meinen lokalen Skripten. + +4. **Vertex AI API aktivieren (Optional/Advanced):** + * Falls ich Service Accounts (JSON-Dateien) statt API-Keys nutzen will (für Server-zu-Server): + * Gehe in die GCP Console -> "APIs & Dienste" -> "Bibliothek". + * Suche nach "Vertex AI API". + * Klick auf "Aktivieren". + +### 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 @@ -134,27 +184,6 @@ flowchart TD * Vorteil: Wir nutzen die sichere Enterprise-API, ohne Office-Lizenzen ändern zu müssen. * Daten bleiben im kontrollierten GCP-Bereich. -## Datenschutz & Compliance Strategie - -### Grundsatz: "Safe Space" & Transparenz -Wir verfolgen einen zweistufigen Ansatz ("Salami-Taktik"), um Datenschutzrisiken zu minimieren und Vertrauen aufzubauen. - -**Phase 1: Der "Safe Space" (Aktueller Status)** -* **Datenbasis:** Ausschließlich öffentlich zugängliche B2B-Firmendaten (Handelsregister, Webseiten). -* **Personenbezug:** Keiner (oder nur reine B2B-Kontaktdaten gem. DSGVO Erwägungsgrund 47 / berechtigtes Interesse). -* **Infrastruktur:** Nutzung der bestehenden Google Workspace Enterprise Umgebung ("Walled Garden"). -* **Training:** Expliziter Ausschluss der Datennutzung zu Trainingszwecken in der Google Admin Konsole (Enterprise Data Protection). - -**Phase 2: Erweiterte Szenarien (Zukunft / Genehmigungspflichtig)** -* **Szenario:** Nutzung interner Daten (z.B. Support-Tickets) zur Mustererkennung. -* **Voraussetzung:** Vorherige Abstimmung eines separaten Datenschutzkonzeptes (z.B. PII-Redaction/Schwärzung vor API-Transfer, Nutzung lokaler LLMs). -* **Commitment:** Keine Verarbeitung kritischer Daten ohne explizites "Go" durch den Datenschutzbeauftragten. - -### Technische Maßnahmen -1. **Vertrag:** Nutzung von Vertex AI im Rahmen des bestehenden Google Workspace Enterprise-Vertrags (DPA). -2. **Zero Retention:** Nutzung der API im Modus ohne Datenspeicherung seitens Google. -3. **Data Residency:** Konfiguration der Datenverarbeitung in EU-Rechenzentren (Frankfurt/Belgien) wo möglich. - ## Strategie zur Lizenzierung & Kosten (Der "Cloud Identity Free" Ansatz) **Ausgangslage:** @@ -207,44 +236,3 @@ Könntet ihr mir bitte **zwei Projekte** anlegen und mit dem zentralen Firmen-Re 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 |