commit 993432d47f0d677234eb35768dac8c4210cd09c6 Author: MetalCircle Codex Bot Date: Tue Sep 15 01:09:10 2026 +0200 Add MetalCircle project wiki diff --git a/Android-App.md b/Android-App.md new file mode 100644 index 0000000..fcf9470 --- /dev/null +++ b/Android-App.md @@ -0,0 +1,7 @@ +# Android App + +Die Android-App ist ein Capacitor-Wrapper der Web-App. Die Package ID bleibt dauerhaft `de.pinguholic.concerts`; der Produktname MetalCircle ändert diese ID nicht. + +Versionen im Repository: Capacitor 6.2.1, Push Notifications 6.0.5, Android Gradle Plugin 8.2.1, Gradle 8.2.1 und Firebase Messaging 23.3.1. Der übliche Ablauf ist `npm install`, `npm run sync` und `npm run build` im Verzeichnis `android`. Das Android-Projekt kann unter `android/android` in Android Studio geöffnet werden. + +Die lokale `google-services.json` ist für den Firebase-Build erforderlich, wird aber ignoriert und nie eingecheckt. FCM-Registrierung, Berechtigungsdialog, Session-Bindung und Debug-Token-Anzeige sind implementiert. Ein serverseitiger Versand von Push-Nachrichten ist noch nicht implementiert. diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 0000000..286b086 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,16 @@ +# Architecture + +```mermaid +flowchart TD + Browser[Web Browser] --> FastAPI[FastAPI / Uvicorn] + Android[Capacitor Android] --> FastAPI + FastAPI --> PostgreSQL[(PostgreSQL)] + FastAPI --> Uploads[Docker Volumes: Uploads] + FastAPI --> External[Nominatim / externe Dienste] + FastAPI --> Gitea[Gitea REST API] + Android --> FCM[Firebase Cloud Messaging] +``` + +Das Backend in `app/main.py` rendert Jinja2-Templates und liefert CSS und JavaScript aus `app/static`. Authentifizierung basiert auf serverseitigen Sessions; der Browser bzw. die Android-WebView spricht ausschließlich mit MetalCircle. PostgreSQL enthält Benutzer, Veranstaltungen, Venues, Community-Daten, Diary, Patches und Push-Geräte. + +Dateien werden in den Compose-Volumes `concert_uploads` und `private_uploads` gehalten. Die Android-App ist ein Capacitor-Wrapper derselben Webanwendung. Firebase wird derzeit für Android-FCM-Registrierung genutzt; ein serverseitiger Push-Versand ist noch nicht aktiviert. Der Bugreporter ist die einzige Backend-Komponente mit Gitea-Zugriff. diff --git a/Backup-and-Recovery.md b/Backup-and-Recovery.md new file mode 100644 index 0000000..3a9a143 --- /dev/null +++ b/Backup-and-Recovery.md @@ -0,0 +1,3 @@ +# Backup and Recovery + +Im Repository sind Datenbankschema und Migrationen versioniert; sie sind keine Datensicherung. Compose verwendet PostgreSQL- und Upload-Volumes. Eine verlässliche Backup-, Aufbewahrungs- und Restore-Strategie der laufenden Umgebungen ist in der externen Betriebsdokumentation zu pflegen. Diese Repository-Dokumentation erfindet keine produktiven Backup-Zeitpläne oder Zugangsdaten. diff --git a/Badges-and-Patches.md b/Badges-and-Patches.md new file mode 100644 index 0000000..bf52ede --- /dev/null +++ b/Badges-and-Patches.md @@ -0,0 +1,15 @@ +# Badges and Patches + +Attendance-Patches werden als Upgrade-System vergeben: + +| Schwelle | Patch | +|---:|---| +| 1 | 1 Gig | +| 10 | 10 Gigs | +| 25 | 25 Gigs | +| 50 | 50 Gigs | +| 100 | 100 Gigs | + +Im Profil wird nur der höchste erreichte Attendance-Patch sichtbar; der höhere ersetzt die niedrigeren Stufen. Weitere definierte Patches sind Gründer/Capt’n, Pit Wächter, Capt’n’s Mate, Border Breaker, Globe Banger und Alpha Tester. Zusätzlich existieren venue- und ereignisbezogene Auszeichnungen im Code. + +Die Vergabe wird aus Konzertbesuchen und den jeweiligen Triggern berechnet. Patch-Bilder können Administratoren verwalten und liegen als Uploads. Neue Vergabelogik muss zuerst in den Definitionen und Tests nachvollziehbar ergänzt werden. diff --git a/Comments-and-Community.md b/Comments-and-Community.md new file mode 100644 index 0000000..831e7d2 --- /dev/null +++ b/Comments-and-Community.md @@ -0,0 +1,5 @@ +# Comments and Community + +Kommentare gehören zu einem Konzert und werden chronologisch auf der Veranstaltungsseite angezeigt. Diese Struktur hält Gespräche beim jeweiligen Konzert; private Direktnachrichten und Freundschaften decken persönliche Kommunikation ab. + +Aktuell vorhanden sind Freundschaftsanfragen, Blockierungen, Follow-Beziehungen für Bands und Venues, Einladungen und Direktnachrichten. Erweiterungen der Community bleiben an die bestehenden Sichtbarkeits- und Blockierungsregeln gebunden. diff --git a/Concerts.md b/Concerts.md new file mode 100644 index 0000000..60a7ab9 --- /dev/null +++ b/Concerts.md @@ -0,0 +1,7 @@ +# Concerts + +Veranstaltungen können als Konzert, Festival oder sonstiges Event angelegt werden. Ein Datensatz enthält Künstlername, Beginn und optional Ende, Beschreibung, Venue, Ticket-URL, Preis, Flyer, Sichtbarkeit und optional einen Parent-Event. + +Auf der Detailseite stehen – abhängig von Anmeldung und Berechtigungen – Teilnahme-/Interesse-Status, eventbezogene Kommentare, Einladungen und Fotos zur Verfügung. Die Zeitdarstellung folgt der gewählten Sprache; Englisch verwendet das 12-Stunden-Format. + +Flyer und Tagebuchfotos sind Uploads. Persönliche oder nur für Freunde sichtbare Veranstaltungen werden serverseitig anhand der bestehenden Sichtbarkeitsregeln geschützt. Konzertalben als eigenständige Funktion sind noch nicht vollständig ausgebaut. diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..7b51f46 --- /dev/null +++ b/Configuration.md @@ -0,0 +1,17 @@ +# Configuration + +| Variable | Zweck | Status | +|---|---|---| +| `POSTGRES_DB` | Name der PostgreSQL-Datenbank | erforderlich | +| `POSTGRES_USER` | Datenbankbenutzer | erforderlich | +| `POSTGRES_PASSWORD` | Datenbankpasswort | erforderlich, geheim | +| `INITIAL_ADMIN_USERNAME` | Erstes Admin-Konto | lokal erforderlich | +| `INITIAL_ADMIN_PASSWORD` | Passwort des Erstadmins | lokal erforderlich, geheim | +| `INITIAL_ADMIN_EMAIL` | E-Mail des Erstadmins | lokal erforderlich | +| `COOKIE_SECURE` | Secure-Flag der Session-Cookies | Produktion `true` | +| `GITEA_URL` | interne Gitea-Basisadresse | für Bugreporter erforderlich | +| `GITEA_TOKEN` | Token des `metalcircle-bot` | erforderlich, geheim | +| `GITEA_OWNER` | Repository-Owner, aktuell `kai` | erforderlich | +| `GITEA_REPO` | Repository, aktuell `pingu-concerts` | erforderlich | + +`.env.example` enthält nur Platzhalter. `.env` wird nie committed. `google-services.json` liegt ausschließlich lokal im Android-App-Modul und wird durch `.gitignore` ausgeschlossen. diff --git a/Database.md b/Database.md new file mode 100644 index 0000000..7bb92ab --- /dev/null +++ b/Database.md @@ -0,0 +1,15 @@ +# Database + +MetalCircle verwendet PostgreSQL. Das Initialschema liegt in `db/init/01_initial.sql`; spätere Änderungen liegen als nummerierte SQL-Dateien in `db/migrations/`. Die Anwendung stellt beim Start zusätzlich sicher, dass die aktuellen Feature-Tabellen vorhanden sind. Jede Schemaänderung muss als reproduzierbare Migration vorliegen. + +Wichtige Beziehungen: + +- `users` ist die Identität für Sessions, Freundschaften, Nachrichten, Kommentare, Attendance, Diary, Badges und Uploads. +- `concerts` verweist optional auf `venues`, einen Parent-Event und den Ersteller. +- `concert_comments`, `concert_photos` und `concert_attendance` hängen an einem Konzert. +- `concert_diary` und `concert_diary_photos` bilden persönliche Konzertnotizen. +- `user_badges` enthält Badges und optionale auslösende Konzerte. +- `push_devices` bindet Android-FCM-Tokens an Benutzer und die aktuelle Session. +- `bug_report_submissions` enthält ausschließlich kurzlebige Status-/Nonce-Metadaten zur Duplicate-Vermeidung, keine vollständigen Issues. + +Primäre Indizes unterstützen Konzertdatum, Venue-Suche, Kommentare, Fotos, Attendance, Nachrichten und Einladungen. Backups und Wiederherstellung der PostgreSQL-Daten sind umgebungsabhängig und werden nicht durch diese Repository-Migrationen automatisiert. diff --git a/Deployment.md b/Deployment.md new file mode 100644 index 0000000..d2bdd92 --- /dev/null +++ b/Deployment.md @@ -0,0 +1,9 @@ +# Deployment + +Es gibt drei getrennte Umgebungen: + +1. Lokale Entwicklung auf PinguCore/Codex mit Docker Compose und Testdaten. +2. Cloud-Staging/Testserver für gemeinsame Integrationstests. +3. Produktion. + +Lokale Änderungen werden in Git geprüft und gepusht. Der Cloud-Testserver zieht den Stand anschließend eigenständig; Codex soll ihn nicht automatisch anmelden, verändern oder deployen. Produktion wird durch diese Dokumentation nicht verändert. Zugangsdaten und konkrete produktive Adressen gehören nicht ins Repository. diff --git a/Development-Setup.md b/Development-Setup.md new file mode 100644 index 0000000..e0f9921 --- /dev/null +++ b/Development-Setup.md @@ -0,0 +1,35 @@ +# Development Setup + +## Voraussetzungen + +Docker/Compose, Git sowie für Android Node.js/npm, JDK 17, Android SDK und ein Android-Gerät oder Emulator. Das Android-Projekt verwendet Capacitor 6.2.1, Android Gradle Plugin 8.2.1 und Gradle 8.2.1. + +## Web lokal + +```bash +cp .env.example .env +docker compose up --build +docker compose logs -f web +docker compose down +``` + +Die Web-App läuft auf Port 8080, PostgreSQL im Compose-Netzwerk. Die Datenbank wird beim ersten Start aus `db/init/01_initial.sql` initialisiert. Für Tests darf eine separate lokale Testdatenbank bzw. ein isoliertes Schema verwendet werden. + +## Tests + +```bash +docker compose run --rm --no-deps -e METALCIRCLE_TEST_DATABASE=1 \ + -v "$PWD/app:/app" -v "$PWD/db/migrations:/test-migrations:ro" \ + web python -m unittest discover -s tests -v +``` + +## Android lokal + +```bash +cd android +npm install +npm run sync +npm run build +``` + +Für lokale HTTP-Tests wird die URL ausschließlich über die dokumentierten lokalen Capacitor-Variablen gesetzt; Release-Builds benötigen HTTPS. Android Studio kann das Verzeichnis `android/android` öffnen. Die Firebase-Datei bleibt lokal und ignoriert. diff --git a/Firebase.md b/Firebase.md new file mode 100644 index 0000000..9d0a5b8 --- /dev/null +++ b/Firebase.md @@ -0,0 +1,5 @@ +# Firebase + +Das Firebase-Projekt heißt **MetalCircle**. Firebase wird aktuell für Android-Firebase Cloud Messaging verwendet: Die App fragt die Benachrichtigungsberechtigung an, erhält einen FCM-Token und registriert ihn beim MetalCircle-Backend. Das Backend speichert Geräte-/Session-Zuordnungen, versendet aber in dieser Phase keine Nachrichten. + +`android/android/app/google-services.json` ist eine lokale Konfigurationsdatei und durch `.gitignore` ausgeschlossen. Firebase-Client-Konfiguration ist kein Ersatz für Server-Secrets; Service-Accounts, Admin-Schlüssel und Tokens gehören weder ins Repository noch in Issues oder Logs. diff --git a/Gitea-Workflow.md b/Gitea-Workflow.md new file mode 100644 index 0000000..4fabe79 --- /dev/null +++ b/Gitea-Workflow.md @@ -0,0 +1,11 @@ +# Gitea Workflow + +Das aktuelle Repository heißt technisch `kai/pingu-concerts`; ein Rename ist nicht Teil dieser Dokumentation. + +| Account | Verantwortung | +|---|---| +| `kai` | persönlicher Admin-/Developer-Account | +| `codex-bot` | technischer Git-Benutzer für Codex: Fetch, Pull, Commit, Push | +| `metalcircle-bot` | ausschließlich serverseitiger Issue-Ersteller aus MetalCircle | + +Die Accounts und ihre Credentials werden strikt getrennt. `metalcircle-bot` wird nicht für normale Git-Pushes verwendet; `codex-bot` erhält keinen Issue-API-Schlüssel. Branch Protection und normale Reviews bleiben aktiv. diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..df74e7c --- /dev/null +++ b/Home.md @@ -0,0 +1,27 @@ +# MetalCircle Wiki + +MetalCircle ist eine private, invite-only Konzert-Community. Dieses Wiki ergänzt die kompakte Repository-README um technische und betriebliche Details. + +## Seiten + +- [Architecture](Architecture.md) +- [Development Setup](Development-Setup.md) +- [Configuration](Configuration.md) +- [Database](Database.md) +- [Concerts](Concerts.md) +- [Venues](Venues.md) +- [Users and Profiles](Users-and-Profiles.md) +- [Badges and Patches](Badges-and-Patches.md) +- [Comments and Community](Comments-and-Community.md) +- [Photos and Uploads](Photos-and-Uploads.md) +- [Android App](Android-App.md) +- [Firebase](Firebase.md) +- [Deployment](Deployment.md) +- [Gitea Workflow](Gitea-Workflow.md) +- [Issues and Bug Reporting](Issues-and-Bug-Reporting.md) +- [Security](Security.md) +- [Backup and Recovery](Backup-and-Recovery.md) +- [Troubleshooting](Troubleshooting.md) +- [Roadmap](Roadmap.md) + +Die Repository-Historie `pingu-concerts` bleibt bestehen; die Produktbezeichnung ist MetalCircle. diff --git a/Issues-and-Bug-Reporting.md b/Issues-and-Bug-Reporting.md new file mode 100644 index 0000000..cad342a --- /dev/null +++ b/Issues-and-Bug-Reporting.md @@ -0,0 +1,7 @@ +# Issues and Bug Reporting + +Eingeloggte Mitglieder erreichen „Bug melden“ im Benutzermenü. Das Formular sendet Titel, Beschreibung, erwartetes Verhalten, Reproduktionsschritte, Kategorie und Schweregrad an das FastAPI-Backend. Optional werden eine bereinigte Route, Plattform, App-Version und ein zusammengefasster Browsertyp beigefügt. Identität und User-ID kommen ausschließlich aus der Session. + +Das Backend ruft die Gitea REST API für `kai/pingu-concerts` auf und akzeptiert vorab nur die Identität `metalcircle-bot`. Vorhandene Labels wie `reported-from-metalcircle`, `bug`, `android`, `web`, `frontend` und `push` werden opportunistisch verwendet. Milestones werden derzeit nicht automatisch gesetzt; der bekannte Projekt-Milestone ist `MetalCircle 0.1 Beta`. + +CSRF-Schutz, Pflichtfeld-/Längenprüfung, Loginpflicht, Cooldown und kurzlebige Submission-Nonces verhindern Missbrauch und Doppelmeldungen. Gitea-Ausfälle bleiben für die restliche Anwendung folgenlos. Tokens, Cookies, Header, FCM-Daten, Passwörter und private Schlüssel gelangen nicht ins Issue. diff --git a/Photos-and-Uploads.md b/Photos-and-Uploads.md new file mode 100644 index 0000000..1087fad --- /dev/null +++ b/Photos-and-Uploads.md @@ -0,0 +1,5 @@ +# Photos and Uploads + +Unterstützt werden Veranstaltungsflyer, Profilbilder, Konzertfotos und Tagebuchfotos. Die Pfade werden in PostgreSQL gespeichert; die Dateien liegen in den Compose-Volumes unter `/app/static/uploads` bzw. im privaten Upload-Volume. Das genaue Ziel wird über `PRIVATE_UPLOAD_DIR` konfiguriert. + +`save_image` prüft Dateiendungen und verarbeitet Bilddaten mit Pillow. Upload-Routen sind login- bzw. admin-geschützt und besitzen Größen-/Mengenbegrenzungen. Lokale Uploads und Archive gehören nicht in Git. Fotoalben als ausgebautes Produktfeature sind teilweise vorhanden und werden weiterentwickelt. diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..4996d6b --- /dev/null +++ b/Roadmap.md @@ -0,0 +1,10 @@ +# Roadmap + +Die folgenden Punkte sind aus dem aktuellen Produktstand und den vorhandenen Funktionen abgeleitet: + +- Community-, Profil-, Attendance- und Interest-Funktionen weiter ausbauen +- Kommentare, Diary und Fotoalben vervollständigen +- Android-App und FCM-Benachrichtigungen weiter testen; serverseitigen Push-Versand separat planen +- weitere Patches und Gamification nach klarer Vergabelogik ergänzen + +Eintragungen hier sind Planung. Sie gelten erst als umgesetzt, wenn Code, Migrationen und Tests vorhanden sind. diff --git a/Security.md b/Security.md new file mode 100644 index 0000000..ea5f6e2 --- /dev/null +++ b/Security.md @@ -0,0 +1,10 @@ +# Security + +- Secrets bleiben in `.env` oder lokalen Secret Stores und werden nie committed oder geloggt. +- Gitea-Tokens werden ausschließlich im Backend verwendet; Bot-Identitäten und Git-Zugriff sind getrennt. +- Session-Cookies sind HttpOnly; Logout löscht Session- und Push-Gerätezuordnungen. +- Bugreport-Kontext ist eine enge Allowlist; Query-Parameter, Cookies, Authorization-Header und FCM-Tokens werden ausgeschlossen. +- Uploads werden serverseitig geprüft, verarbeitet und über Berechtigungen geschützt. +- Benutzer-, Freundes-, Blockierungs- und Sichtbarkeitsregeln gelten auch bei Konzertdaten. +- Firebase-Konfigurationsdateien, private Schlüssel, Dumps und lokale Uploads gehören nicht in Git. +- Produktionsdaten und Produktions-Secrets werden in lokaler Entwicklung nicht verwendet. diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..b063e14 --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,9 @@ +# Troubleshooting + +- **Container startet nicht:** `.env` anhand von `.env.example` prüfen, dann `docker compose logs db` und `docker compose logs web` ansehen. +- **Datenbankfehler:** Prüfen, ob PostgreSQL läuft und `POSTGRES_*` sowie `DATABASE_URL` zusammenpassen. Schemaänderungen über Migrationen einspielen. +- **Venue-Suche leer oder langsam:** Nominatim ist extern und rate-limited; manuelle Venue-Daten können verwendet werden. +- **Upload scheitert:** Dateityp, Größe, Schreibrechte und die Compose-Volumes prüfen. +- **Android-Sync schlägt fehl:** Node/npm, JDK, Android SDK und die lokale ignorierte `google-services.json` prüfen. +- **FCM fehlt:** App-Berechtigung und Firebase-Konfiguration prüfen; Push-Versand ist aktuell nicht serverseitig aktiviert. +- **Bugreport kann nicht gesendet werden:** Gitea-URL, Bot-Token und Repository-Konfiguration nur lokal prüfen; Secrets nie in Logs kopieren. diff --git a/Users-and-Profiles.md b/Users-and-Profiles.md new file mode 100644 index 0000000..2da37e9 --- /dev/null +++ b/Users-and-Profiles.md @@ -0,0 +1,7 @@ +# Users and Profiles + +MetalCircle ist invite-only. Benutzer besitzen Benutzername, E-Mail, Passwort-Hash, Anzeigename, Avatar und Sichtbarkeitseinstellung. Sessions liegen serverseitig und werden bei Logout gelöscht. + +Administratoren verwalten Einladungen, Benutzer, Venues, Patch-Bilder und Statistiken. Mitglieder können Profile ansehen, Freundschaftsanfragen senden, blockieren, Bands/Venues folgen und Nachrichten austauschen. Sichtbarkeit und Blockierungen werden bei Profilen, Attendance und Community-Daten berücksichtigt. + +Nicht jede geplante Community-Funktion ist vollständig umgesetzt; maßgeblich ist der aktuelle Code in `app/main.py`. diff --git a/Venues.md b/Venues.md new file mode 100644 index 0000000..b71e808 --- /dev/null +++ b/Venues.md @@ -0,0 +1,5 @@ +# Venues + +`venues` speichert Name, Adresse, Stadt, Land, Koordinaten, externe ID, Quelle und Verifizierungsstatus. `venue_aliases` unterstützt alternative Schreibweisen. + +Die Suche kann lokale Venues und Nominatim-Ergebnisse kombinieren. Nominatim-Datensätze werden mit Quelle und externer ID wiedererkannt. Nominatim ist ein externer Dienst mit eigenen Nutzungsbedingungen und Rate Limits; Verfügbarkeit und Antwortzeiten sind nicht garantiert. Bei Fehlern bleibt die manuelle Eingabe möglich.