pingu-concerts/docs/wiki/Firebase.md

Firebase

Das Firebase-Projekt heißt MetalCircle. Android ist dauerhaft als de.pinguholic.concerts registriert. Manuelle Testnachrichten funktionieren bereits. Automatischer Versand für Freundschaftsanfragen, Direktnachrichten und Veranstaltungseinladungen ist implementiert und benötigt einen separaten serverseitigen Zugang sowie PUSH_ENABLED=true.

Unterschiedliche Konfigurationsdateien

• android/android/app/google-services.json: lokale, Git-ignorierte Android-Client-Konfiguration. Projekt-/App-Kennungen und der Client-API-Key werden vom Build in die APK übernommen; sie sind kein Backend-Privatschlüssel.
• Service-Account-JSON: privater Schlüssel für das Backend. Niemals in Git, APK, Docker-Image, Webassets, Chat, Wiki oder Logs aufnehmen. Die Android-Datei ersetzt diesen Zugang nicht.

Lokale Entwicklungs-/Testumgebung

1. In Firebase MetalCircle auswählen und die tatsächliche Projekt-ID notieren; sie kann vom Anzeigenamen abweichen.
2. In der zugehörigen Google Cloud Console die Firebase Cloud Messaging API (HTTP v1) prüfen/aktivieren.
3. Der lokale Test verwendet den dedizierten Service Account metalcircle-push-local@metalcircle-30d9b.iam.gserviceaccount.com. Für dessen Versand ist die Projektrolle Firebase Cloud Messaging API Admin, Rollen-ID roles/firebasecloudmessaging.admin, erforderlich. Diese genaue Rolle ist diesem lokalen Test-Service-Account auf Projektebene im Projekt metalcircle-30d9b zugewiesen. Sie enthält cloudmessaging.messages.create. Nicht mit ähnlich benannten Firebase-Administrationsrollen verwechseln; OAuth-Tokenbezug allein beweist keine Versandberechtigung. Keine persönlichen oder Gitea-Zugänge verwenden. Siehe Firebase IAM und FCM-Rollen.
4. Den privaten JSON-Schlüssel geschützt außerhalb des Repositories und Docker-Buildkontexts speichern. Der Betreiber verwaltet die Datei. Firebase Admin Setup beschreibt Service-Account-Dateien.
5. Dateirechte einschränken, beispielsweise chmod 600 /absoluter/pfad/firebase-service-account.json. Keine Inhalte ausgeben.
6. In der lokalen .env die folgenden Werte selbst eintragen:

PUSH_ENABLED=true
FIREBASE_PROJECT_ID=<tatsaechliche-test-projekt-id>
FIREBASE_SERVICE_ACCOUNT_FILE=/absoluter/pfad/firebase-service-account.json

7. In der eigenen lokalen HTTP-Testumgebung starten:

COOKIE_SECURE=false docker compose -f compose.yml -f compose.push.yml up -d --build web

compose.push.yml liest FIREBASE_SERVICE_ACCOUNT_FILE als absoluten Host-Pfad, bindet diese Datei read-only unter /run/secrets/firebase-service-account.json in den web-Container ein und setzt GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/firebase-service-account.json. Die Quelldatei muss existieren. Der Sender prüft, dass FIREBASE_PROJECT_ID zur Projekt-ID des Credentials passt. Die Android-App muss dasselbe Firebase-Projekt verwenden. Schlüsseldatei, .env und Token gehören weder ins Repository noch in ein Image.

Cloud-Staging richtet der Betreiber separat ein; dort hinter HTTPS COOKIE_SECURE=true lassen. Codex auf PinguCore greift nicht automatisch darauf zu. Produktion bekommt später eigene Credentials, keine kopierten Testschlüssel.

Verifizierter lokaler E2E-Stand

Am 15.09.2026 wurde der vollständige lokale Weg mit dem Android-Testgerät und dem lokalen Backend erfolgreich geprüft. Nach Zuweisung von roles/firebasecloudmessaging.admin verschwand der vorherige HTTP-403-Fehler PERMISSION_DENIED. Das Service-Account-Credential stimmte mit FIREBASE_PROJECT_ID=metalcircle-30d9b überein; der Firebase Admin SDK Versand wurde vom FCM HTTP-v1-Endpunkt angenommen.

Freundschaftsanfrage und Veranstaltungseinladung wurden im Android Notification Manager nachgewiesen. Die Direktnachrichten-Benachrichtigung wurde auf dem Gerät gesehen; Antippen öffnete den zugehörigen Chat. Alle drei Benachrichtigungen verwenden generische Vorschautexte ohne Nachrichtentext oder private Veranstaltungsdetails. Die installierte Test-App war 1.1.0-debug, Package ID de.pinguholic.concerts.

Für eine Wiederholung lokale App und Backend verwenden; mit adb reverse tcp:8080 tcp:8080 wird der Android-Testbuild an den lokalen Port 8080 weitergeleitet. Keine Cloud-Staging- oder Produktionsumgebung verwenden. In der Datenbank bedeutet push_notifications.state='sent', dass der Firebase-Sendeaufruf angenommen wurde; für einen vollständigen E2E-PASS zusätzlich den tatsächlichen Android-Empfang über Notification Manager oder gleichwertige Gerätebeobachtung prüfen.

Automatisierte Backend-Tests simulieren Firebase und belegen nicht die Cloud-IAM-Berechtigung. Die lokale Suite mit 53 Tests und der Android-Debug-Build waren erfolgreich; der oben beschriebene Gerätetest hat zusätzlich den echten FCM-Versand und Empfang bestätigt. Bei erneutem configuration-/403-Fehler Projekt-ID, aktiven Service Account, dessen roles/firebasecloudmessaging.admin-Zuweisung im richtigen Firebase-Projekt, API-Aktivierung und Secret-Mount prüfen. Logs enthalten absichtlich keine vollständigen Firebase-Fehlerantworten oder Secrets. Keine Legacy-Server-Keys einsetzen.