193 lines
7.1 KiB
Markdown
193 lines
7.1 KiB
Markdown
# S.L.R.P.G. - Streetlifting Role Playing Game
|
|
|
|
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.
|
|
|
|
## Inhaltsverzeichnis
|
|
|
|
1. Projektübersicht
|
|
2. Technologie-Stack
|
|
3. Architektur
|
|
4. Kernfunktionen
|
|
5. Projektstruktur
|
|
6. Installation und Einrichtung
|
|
7. Entwicklung
|
|
|
|
## 1. Projektübersicht
|
|
|
|
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:
|
|
|
|
* 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.
|