docs: update README

2026-02-14 18:05:27 +01:00 · 2026-02-14 18:05:27 +01:00 · 6092692c54
commit 6092692c54
parent fdc258af28
1 changed files with 187 additions and 10 deletions
--- 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.