Implement Google OAuth linking functionality. Update backend to handle linking existing accounts with Google, including state token management. Enhance frontend to support linking process, including new UI components for user input and feedback. Update mobile app to handle OAuth callbacks and integrate linking features. Refactor related services and controllers for improved error handling and user experience.

GOOGLE_OAUTH_MANUAL_STEPS.md

@@ -0,0 +1,83 @@
+# Google OAuth: manuelle Restarbeiten
+
+Stand: 2026-05-15
+
+## 1. Google Cloud Console vorbereiten
+
+1. In der Google Cloud Console das passende Projekt öffnen oder ein neues Projekt anlegen.
+2. Unter `APIs & Services > OAuth consent screen` den Consent Screen konfigurieren.
+3. App-Name, Support-E-Mail und Entwicklerkontakt eintragen.
+4. Scopes reichen für diese App:
+   - `profile`
+   - `email`
+5. Unter `APIs & Services > Credentials` einen OAuth-Client vom Typ `Web application` anlegen.
+6. Als Authorized redirect URI eintragen:
+   - Produktion: `https://stechuhr3.tsschulz.de/api/auth/google/callback`
+   - Lokal, falls benötigt: `http://localhost:3010/api/auth/google/callback`
+7. `Client ID` und `Client Secret` notieren.
+
+## 2. Server-Environment setzen
+
+Auf dem Server in der produktiven Environment-Datei folgende Werte setzen:
+
+```env
+GOOGLE_CLIENT_ID=<client-id-aus-google-console>
+GOOGLE_CLIENT_SECRET=<client-secret-aus-google-console>
+GOOGLE_CALLBACK_URL=https://stechuhr3.tsschulz.de/api/auth/google/callback
+API_PUBLIC_URL=https://stechuhr3.tsschulz.de/api
+FRONTEND_URL=https://stechuhr3.tsschulz.de
+SESSION_SECRET=<langer-zufallswert>
+JWT_SECRET=<bestehender-oder-langer-zufallswert>
+```
+
+Wichtig: `GOOGLE_CALLBACK_URL` muss exakt mit der Redirect URI in der Google Console übereinstimmen.
+
+## 3. Backend deployen und neu starten
+
+1. Code auf den Server bringen.
+2. Backend neu starten, z. B. über das vorhandene Deploy-Skript oder PM2.
+3. Log prüfen. Erwartet:
+
+```text
+✅ Google OAuth konfiguriert
+```
+
+Wenn stattdessen `Google OAuth nicht konfiguriert` erscheint, fehlen `GOOGLE_CLIENT_ID` oder `GOOGLE_CLIENT_SECRET` im laufenden Prozess.
+
+## 4. Web-Frontend deployen
+
+1. Frontend neu bauen.
+2. Neue `dist`-Dateien deployen.
+3. Browser-Cache bei Bedarf leeren.
+
+## 5. Android-App neu bauen/installieren
+
+1. Debug/APK oder Release/AAB neu bauen.
+2. App neu installieren.
+3. Prüfen, dass Android den Deep Link `timeclock://oauth-callback` öffnet.
+
+## 6. Testfälle
+
+1. Google-Account ohne vorhandene TimeClock-E-Mail:
+   - `Mit Google anmelden`
+   - Erwartung: neuer Account wird erstellt und eingeloggt.
+2. Google-Account bereits verknüpft:
+   - `Mit Google anmelden`
+   - Erwartung: direkter Login.
+3. Google-Account mit E-Mail eines bestehenden Passwort-Accounts:
+   - `Mit Google anmelden`
+   - Erwartung: Verknüpfungsabfrage.
+   - Bestehende E-Mail + Passwort eingeben.
+   - Erwartung: Account wird verknüpft und eingeloggt.
+4. Eingeloggt unter `Persönliche Daten`:
+   - `Mit Google-Konto verknüpfen`
+   - Erwartung: Google Flow startet, danach Rückkehr und Verknüpfung.
+5. Danach ausloggen und erneut `Mit Google anmelden`.
+   - Erwartung: direkter Login in denselben bestehenden Account.
+
+## 7. Falls etwas fehlschlägt
+
+- Google meldet `redirect_uri_mismatch`: Redirect URI in Google Console und `GOOGLE_CALLBACK_URL` vergleichen.
+- Backend zeigt OAuth nicht konfiguriert: PM2/Deploy lädt die neuen Env-Werte nicht. Prozess mit aktualisierter Environment neu starten.
+- Android kehrt nicht in die App zurück: prüfen, ob der Browser auf `timeclock://oauth-callback?...` weiterleitet und die neu gebaute App installiert ist.
+- Verknüpfung schlägt fehl: prüfen, ob der alte Account wirklich ein Passwort hat. OAuth-only Accounts können sich nicht per Passwort bestätigen.