# Checkliste: Google Cloud — PORTA (OAuth + Speech)

Operative Liste: **was im Google Cloud Projekt** (z. B. Organisation `poweron-center-ai-org`, Projekt **PowerOn Porta**) **eingerichtet** werden muss und **welche Gateway-Variablen/Code-Stellen** dazu passen.

Detaillierte OAuth-Schritte und Troubleshooting: [`google-oauth-setup.md`](google-oauth-setup.md).

---

## 1) Google Cloud Console — APIs aktivieren

Projekt auswählen → **APIs & Services** → **Library**.

| API | Wofür im Gateway |
|-----|------------------|
| **Gmail API** | Mail-Connector (readonly-Scope) |
| **Google Drive API** | Drive-Connector (readonly) |
| **Google Calendar API** | Kalender-Connector (readonly) |
| **People API** | Kontakte (readonly) |
| **Cloud Speech-to-Text API** | STT (`/voice-google/stt/*`) |
| **Cloud Text-to-Speech API** | TTS über `ConnectorGoogleSpeech` |

---

## 2) OAuth-Zustimmungsbildschirm

**APIs & Services** → **OAuth consent screen**.

- App-Name, Support-Mail, Developer Contact wie von Google gefordert.
- **Scopes** müssen zur Code-Basis passen (Single Source of Truth):

`platform-core/modules/auth/oauthProviderConfig.py` → `googleAuthScopes`, `googleDataScopes`

Kurzreferenz:

| Zweck | Scopes |
|-------|--------|
| Nur Login (**Auth-App**) | `openid`, `userinfo.email`, `userinfo.profile` |
| Datenverbindung (**Data-App**) | wie Auth **plus** `gmail.readonly`, `drive.readonly`, `calendar.readonly`, `contacts.readonly` |

Hinweis: Nach **Scope-Erweiterung** müssen Nutzer Google-Verbindungen in der UI **Reconnect** auslösen (siehe `google-oauth-setup.md`).

---

## 3) OAuth 2.0 Client(s) — „Web application“

**APIs & Services** → **Credentials** → **Create credentials** → **OAuth client ID**.

Das Gateway unterstützt **getrennte Auth- und Data-Clients** (unterschiedliche Client-IDs) oder **einen gemeinsamen Client** (in den Envs sind ID/Secret für Auth und Data oft identisch).

**Authorized redirect URIs** — pro öffentlich erreichbare Gateway-Basis-URL **zwei** Einträge (Pfad exakt, inkl. `http`/`https`):

| Pfad | Verwendung |
|------|------------|
| `{origin}/api/google/auth/login/callback` | Login-Flow (`Service_GOOGLE_AUTH_REDIRECT_URI`) |
| `{origin}/api/google/auth/connect/callback` | Connect/Reconnect (`Service_GOOGLE_DATA_REDIRECT_URI`) |

**In diesem Repo typische Origins** (jeweils beide Callbacks eintragen):

- Lokal: `http://localhost:8000`
- INT: `https://gateway-int.poweron.swiss`
- PROD: `https://gateway-prod.poweron.swiss`
- Forgejo/ALT-Prod (falls genutzt): `https://api.poweron.swiss` — in `env-gateway-prod-forgejo.env` Google `*_REDIRECT_URI` ggf. noch setzen.

Backend-Routing: `platform-core/modules/routes/routeSecurityGoogle.py`.

---

## 4) Speech / Voice (ohne User-OAuth)

**Credentials** → **API key** (empfohlen:auf Speech + TTS beschränken) **oder** Service-Account nach Vorgabe des Connector (siehe `platform-core/modules/connectors/connectorVoiceGoogle.py`: `Connector_GoogleSpeech_API_KEY_SECRET` kann API-Key oder SA-JSON sein).

Doku STT/TTS: [`b-reference/platform-core/voice-google.md`](../b-reference/platform-core/voice-google.md).

---

## 5) Gateway — Env-Dateien anpassen

Alle Werte **ohne** echte Secrets im Wiki; in den Deploy-Envs mit eurem Verschlüsselungsworkflow pflegen ([`encrypt-env-secrets.md`](encrypt-env-secrets.md)).

| Variable | Bedeutung |
|----------|-----------|
| `Service_GOOGLE_AUTH_CLIENT_ID` | OAuth Client (Login) |
| `Service_GOOGLE_AUTH_CLIENT_SECRET` | Geheimnis (verschlüsselt) |
| `Service_GOOGLE_AUTH_REDIRECT_URI` | Muss **1:1** mit Google Console Login-Callback übereinstimmen |
| `Service_GOOGLE_DATA_CLIENT_ID` | OAuth Client (Connector); darf = Auth sein |
| `Service_GOOGLE_DATA_CLIENT_SECRET` | Geheimnis (verschlüsselt) |
| `Service_GOOGLE_DATA_REDIRECT_URI` | Muss **1:1** mit Google Console Connect-Callback übereinstimmen |
| `Connector_GoogleSpeech_API_KEY_SECRET` | Speech/TTS API-Key oder SA-JSON (verschlüsselt) |

**Dateien (Stand Repo):** `platform-core/env-gateway-dev.env`, `env-gateway-int.env`, `env-gateway-prod.env`, `env-gateway-prod-forgejo.env`, ggf. `platform-core/.env`.

Zusätzlich — wenn neues **Frontend** oder neuer **API-Host**:

- `APP_API_URL` muss die Basis sein, unter der `/api/google/...` erreichbar ist (Cookie/SameSite-Kontext).
- `APP_ALLOWED_ORIGINS` — CORS für das UI, falls neue Origins dazukommen.

---

## 6) Gateway — Python (nur bei Scope-/API-Änderungen)

| Datei | Wann anfassen |
|-------|----------------|
| `platform-core/modules/auth/oauthProviderConfig.py` | Neue/entfernte Google-Scopes für Login oder Datenverbindung |
| `platform-core/modules/routes/routeSecurityGoogle.py` | Nur bei Flow-/Route-Änderungen (unüblich) |
| `platform-core/modules/auth/tokenManager.py` | Nutzt `Service_GOOGLE_DATA_*` für Refresh — keine manuelle Anpassung bei reiner Registrierung |

Token-Refresh und Microsoft/Google Data: `platform-core/modules/auth/tokenManager.py`.

---

## 7) Smoke-Tests

- [ ] Login mit Google: redirected zu Google, Rückkehr ohne `redirect_uri_mismatch`
- [ ] **Verbindungen** → Google connect/reconnect
- [ ] Drive/Mail/Kalender/Kontakte je nach Feature smoke-testen
- [ ] STT/TTS: kurzer Aufruf über Voice-Route (siehe `voice-google.md`)