Add MetalCircle project wiki
@@ -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.
|
||||
+16
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+7
@@ -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.
|
||||
+17
@@ -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.
|
||||
+15
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+5
@@ -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.
|
||||
@@ -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.
|
||||
+27
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+10
@@ -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.
|
||||
+10
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
+5
@@ -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.
|
||||
Reference in New Issue
Block a user