diff --git a/README.md b/README.md index 36741c3..043d8e4 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,193 @@ -# slrpg_app +# S.L.R.P.G. - Streetlifting Role Playing Game -A new Flutter project. +S.L.R.P.G. ist eine hybride Android-Anwendung, die professionelles Krafttraining (speziell Streetlifting und Powerlifting) mit Gamification-Elementen aus Rollenspielen (RPGs) verbindet. Das Ziel der Anwendung ist die Steigerung der Nutzer-Motivation durch extrinsische Anreize (Level-System, Items, Quests) bei gleichzeitiger präziser Steuerung der Trainingsbelastung durch etablierte Algorithmen. -## Getting Started +## Inhaltsverzeichnis -This project is a starting point for a Flutter application. +1. Projektübersicht +2. Technologie-Stack +3. Architektur +4. Kernfunktionen +5. Projektstruktur +6. Installation und Einrichtung +7. Entwicklung -A few resources to get you started if this is your first Flutter project: +## 1. Projektübersicht -- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) +Die App implementiert das **Wendler 5/3/1 Trainingssystem** und adaptiert es für Calisthenics- und Streetlifting-Übungen. Trainingsfortschritte ("Progressive Overload") werden direkt in Spielmechaniken übersetzt: -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +* Wiederholungen verursachen "Schaden" an Gegnern. +* Absolvierte Workouts gewähren Erfahrungspunkte (XP). +* Steigerungen der Kraftwerte (1RM) schalten neue Spielinhalte frei. + +Das System folgt einem **Offline-First** Ansatz, um die Funktionalität auch in Umgebungen ohne Internetverbindung (z. B. Fitnessstudios im Keller) vollständig zu gewährleisten. + +## 2. Technologie-Stack + +### Frontend & Mobile Framework + +* **Sprache:** Dart +* **Framework:** Flutter (Cross-Platform Development) +* **State Management:** Riverpod (mit Code Generation & Hooks) +* **Routing:** GoRouter + +### Datenhaltung & Persistenz + +* **Lokale Datenbank:** Drift (SQLite Abstraktionsschicht für Dart) +* **Backend Integration:** PocketBase (Go-basiertes Backend) +* **Synchronisierung:** Eigene Implementierung einer bidirektionalen Synchronisierung (`SyncService`) + +### Weitere Bibliotheken + +* **Freezed / JSON Serializable:** Für unveränderliche Datenmodelle und Serialisierung. +* **Flutter Localizations:** Unterstützung für Internationalisierung (i18n), aktuell DE und EN. +* **Charts:** Visualisierung von Trainingsfortschritten. + +## 3. Architektur + +Das Projekt folgt einer **Feature-First Layered Architecture** in Kombination mit **Clean Architecture** Prinzipien. + +### Schichtenmodell (Layers) + +* **Presentation Layer:** Beinhaltet Widgets, Screens und Controller (Riverpod Notifier). Dieser Layer ist rein für die Darstellung und Benutzerinteraktion zuständig. +* **Domain Layer:** Beinhaltet die Geschäftslogik (z. B. `WendlerCalculator`, `XpCalculator`), Entitäten (`Exercise`, `WorkoutSet`) und Interface-Definitionen. Dieser Layer ist unabhängig von externen Frameworks. +* **Data Layer:** Implementiert die Repositories, verwaltet die lokale Datenbank (`AppDatabase`) und die API-Kommunikation (`ApiClient`). + +### Offline-First Strategie + +Die lokale Drift-Datenbank fungiert als **Single Source of Truth** für die UI. + +1. Die App liest und schreibt primär in die lokale SQLite-Datenbank. +2. Ein Hintergrund-Service (`SyncService`) synchronisiert Änderungen asynchron mit dem PocketBase-Backend, sobald eine Netzwerkverbindung besteht. +3. Konfliktlösung und Queueing von Requests stellen die Datenkonsistenz sicher. + +## 4. Kernfunktionen + +### Trainings-Management + +* **Automatisierte Planung:** Berechnung von Trainingszyklen basierend auf dem 1RM (One Repetition Max) mittels Wendler 5/3/1 Logik. +* **Battle Mode:** Interaktive Durchführung des Workouts. Sätze werden als "Kampfrunden" dargestellt. +* **Timer-System:** Integrierte Satzpausen- und EMOM-Timer (Every Minute on the Minute). +* **Plate Calculator:** Visualisierung der benötigten Hantelscheiben für das aktuelle Gewicht. + +### Gamification (RPG-Elemente) + +* **Avatar-System:** Anpassbarer Charakter mit Ausrüstungsslots. +* **Inventar:** Verwaltung von virtuellen Gegenständen, die durch Training freigeschaltet werden. +* **Quests:** Tägliche und wöchentliche Aufgaben zur Förderung der Konsistenz. +* **Codex:** Wissensdatenbank und Sammlung freigeschalteter Erfolge. + +### Multiplayer & Social + +* **Party-System:** Bildung von Gruppen für gemeinsame "Raids" (Workouts). +* **Leaderboards:** Ranglisten basierend auf XP und Kraftwerten. +* **Lobby:** Echtzeit-Warteraum für Multiplayer-Sessions. + +### Statistik & Analyse + +* Detaillierte Historie aller absolvierten Workouts. +* Grafische Auswertung der Kraftentwicklung in den Grundübungen. + +## 5. Projektstruktur + +Der Quellcode befindet sich im Verzeichnis `lib/` und ist wie folgt gegliedert: + +```text +lib/ +├── main.dart # Einstiegspunkt der App +├── l10n/ # Lokalisierungsdateien (ARB) +└── src/ + ├── app.dart # Root-Widget und globale Konfiguration + ├── core/ # Kern-Komponenten (Routing, Theme, Konstanten, Utils) + ├── features/ # Funktionalitäten (Feature-First Struktur) + │ ├── authentication/ # Login, Register, Profil + │ ├── backup/ # Datensicherung + │ ├── dashboard/ # Hauptmenü (Hub) + │ ├── gamification/ # Quests, Avatar, Codex + │ ├── history/ # Trainingshistorie + │ ├── inventory/ # Item-Verwaltung + │ ├── multiplayer/ # Social Features + │ ├── onboarding/ # Setup-Flow für neue Nutzer + │ ├── settings/ # Einstellungen + │ ├── stats/ # Diagramme und Auswertungen + │ ├── wiki/ # Übungsanleitungen + │ └── workout_runner/ # Die eigentliche Trainings-Logik (Battle Screen) + └── shared/ # Geteilte Ressourcen + ├── data/ # Repositories, lokale DB (Drift), API-Client + ├── domain/ # Geteilte Logik (z.B. WendlerCalculator) + └── presentation/ # Wiederverwendbare Widgets + +``` + +## 6. Installation und Einrichtung + +### Voraussetzungen + +* Flutter SDK (neueste stabile Version empfohlen) +* Dart SDK +* Ein laufendes PocketBase Backend (siehe separate Backend-Dokumentation) + +### Schritte + +1. **Repository klonen:** +```bash +git clone [Repository-URL] +cd slrpg_app + +``` + + +2. **Abhängigkeiten installieren:** +```bash +flutter pub get + +``` + + +3. **Umgebungsvariablen konfigurieren:** +Erstellen Sie eine `.env` Datei im Root-Verzeichnis des Projekts und fügen Sie die notwendigen Konfigurationen hinzu (z. B. Backend-URL): +```env +API_URL=http://localhost:8090 + +``` + + +4. **Code-Generierung:** +Da das Projekt `riverpod_generator`, `drift` und `freezed` verwendet, müssen die Dateien generiert werden: +```bash +dart run build_runner build --delete-conflicting-outputs + +``` + + +5. **App starten:** +```bash +flutter run + +``` + + + +## 7. Entwicklung + +### Testing + +Das Projekt enthält Unit- und Widget-Tests (sofern implementiert). Ausführen der Tests: + +```bash +flutter test + +``` + +### Lokalisierung + +Texte werden in `lib/src/l10n/app_de.arb` und `app_en.arb` gepflegt. Nach Änderungen muss der Generator ausgeführt werden: + +```bash +flutter gen-l10n + +``` + +### Datenbank-Migrationen + +Bei Änderungen am Datenbankschema in `app_database.dart` oder `tables.dart` muss die Schema-Version erhöht und eine Migration geschrieben werden. Drift kümmert sich um die Generierung des Boilerplate-Codes.