App-Doku erstellt, doku aufgeräumt

doc/docs/concepts/mobile_app.md

@@ -0,0 +1,107 @@
+# Mobile App
+
+Um das Spiel zu steuern, wird eine mobile App entwickelt. Sie soll anfangs für Android verfügbar sein. Wenn die Hürden nicht zu groß sind, wird auch eine iOS-Version in Betracht gezogen. Dazu wird die Entwicklung in Flutter stattfinden.
+
+## Übersicht
+
+Der grundsätzliche Ablauf sieht so aus:
+
+```mermaid
+flowchart TD
+    start([App-Start])
+    choose_leader[1. Leader bestimmen]
+    check_state{Leader-Status?}
+
+    lobby[2a. Lobby-Phase]
+    game[2b. Spiel-Phase]
+    evaluation[2c. Auswertungs-Phase]
+    
+    start-->choose_leader
+    choose_leader-->check_state
+    check_state-->|Kein Spiel läuft|lobby
+    check_state-->|Spiel läuft|game
+    check_state-->|Spiel abgeschlossen|evaluation
+    
+    lobby-->|Spiel starten|game
+    game-->|Spiel abbrechen|lobby
+    game-->|Spielende|evaluation
+    evaluation-->|Neues Spiel|lobby
+
+    classDef phase fill:#eef4ff,stroke:#6c8be0,stroke-width:1px,color:#0d1b2a
+    class lobby,game,evaluation phase
+```
+
+### 1. Leader bestimmen
+- Beim Start der App wird geschaut, ob der zuletzt gewählte Game-Leader über BLE erreichbar ist.
+- Ist der nicht erreichbar, wird nach allen verfügbaren Leader-Knoten gescannt und zur Auswahl angeboten.
+
+### 2a. Lobby-Phase
+
+In der Lobby-Phase wird das Spiel vorbereitet: Spielmodus wählen, Teams/Spieler zuordnen und Parameter konfigurieren.
+
+#### Thread-Netzwerk & Provisionierung
+- Thread-Parameter werden am Leader konfiguriert und über das Thread-Netzwerk an alle verbundenen Geräte verteilt
+- Im Hintergrund läuft permanent ein BLE-Scan nach neuen Geräten
+- Neu gefundene Geräte werden automatisch mit den Thread-Parametern provisioniert und dem Netzwerk hinzugefügt
+
+#### Geräte-Discovery & Monitoring
+- Die App triggert den Leader in regelmäßigen Abständen, eine "Who is there"-Multicast-Abfrage im Thread-Netzwerk auszuführen
+- Zurückgemeldete Geräte werden in einer Liste erfasst
+- Beim ersten Erscheinen eines Geräts werden dessen Parameter abgerufen: Name, Typ, spezifische Eigenschaften
+- Geräte, die sich über einen bestimmten Zeitraum nicht mehr melden, werden ausgegraut
+- **Auto-Synchronisation:** Meldet ein Gerät Spieler- oder Team-Zuordnungen (z.B. "Spieler 3, Team 2"), die in der App noch nicht existieren, werden diese automatisch angelegt (z.B. "Spieler 3" und "Team 2"), um Konfigurationskonflikte zu vermeiden
+
+#### Benutzeroberfläche
+
+**Geräteliste:**
+
+- Zeigt alle verfügbaren Geräte an
+- Antippen eines Geräts blendet zusätzliche Icons ein:
+  - **Verbindungsstatus:** Zeigt an, ob das Gerät kürzlich gesehen wurde
+  - **Zuordnungsstatus:** Ob das Gerät einem Spieler/Team zugeordnet ist
+  - **Identifikation:** Lässt das Gerät blinken (3x) oder LED atmen zur physischen Identifikation
+  - **Entfernen:** Nur aktiv bei ausgegrauten Geräten
+  - **Einstellungen:** Geräteeinstellungen bearbeiten
+
+**Teamliste:**
+
+- Zeigt alle Teams an
+- Antippen erweitert die Ansicht mit den zugewiesenen Spielern
+
+**Spielerliste:**
+
+- Zeigt alle Spieler mit Teamzuordnungsstatus an
+- Spieler können angelegt, gelöscht und umbenannt werden
+
+#### Spielkonfiguration
+- Spielkonfigurationen können gespeichert und später neu geladen werden
+- Alle Spielparameter (Dauer, Respawns, etc.) sind hier einstellbar
+
+#### Spielstart-Bedingungen
+Das Spiel kann nur gestartet werden, wenn folgende Bedingungen erfüllt sind:
+
+- Alle Westen und Waffen sind zugeordnet
+- Jede Weste ist genau einem Spieler zugeordnet (und umgekehrt)
+- Der Spielmodus ist gesetzt und konfiguriert
+- Alle Basen, Power-Ups etc. sind konfiguriert
+- Kein ausgegrautes Gerät ist vorhanden
+- Je nach Spielmodus: Alle Spieler sind einem Team zugeordnet
+
+Sind nicht alle Bedingungen erfüllt, werden die Gründe angezeigt.
+
+#### Übergang zur Spiel-Phase
+- Beim "Spiel starten" wird eine zufällige Spiel-ID generiert und an den Leader übermittelt
+- Die aktuelle Spielkonfiguration wird gespeichert
+- Dadurch kann das Spiel auch nach App-Neustart ausgewertet werden
+
+### 2b. Spiel-Phase
+- Laufendes Spiel: Status/Timer anzeigen, optional Live-Events (Treffer, Bases) und Admin-Aktionen wie "Spiel abbrechen".
+- Spielende erfolgt je nach Modus (Timer, Score, Objective) und wechselt in die Auswertungs-Phase.
+- Sollte die App während der Spielphase gestartet werden, wird geprüft, ob die Spiel-ID auf dem gewählten Leader-Knoten mit der gespeicherten ID zusammenpasst. Wenn ja, schaltet sich die App auf das Spiel auf. Wenn nein, meldet die App einen Fehler, dass eine Verbindung aufgrund eines laufenden Spieles nicht möglich ist.
+Je nach Spielmodus ist es der App möglich, in das Spielgeschehen einzugreifen (zum Beispiel Power-Ups senden etc.).
+### 2c. Auswertungs-Phase
+- Geräte auslesen, Scores sammeln, Rangliste erzeugen und anzeigen.
+- Optionen: "Neues Spiel" führt zurück in die Lobby; Export/Share der Ergebnisse möglich.
+- Sollte die App während der Auswertungsphase gestartet werden, wird geprüft, ob die Spiel-ID auf dem gewählten Leader-Knoten mit der gespeicherten ID zusammenpasst. Wenn ja, schaltet sich die App auf das Spiel auf. Wenn nein, meldet die App einen Fehler, dass die Spiel-ID unbekannt ist und somit eine Auswertung nicht möglich ist.
+
+Eine Auswertung erfolgt erst, wenn alle Geräte, die zur Auswertung erforderlich sind, abgerufen werden konnten. Ist das innerhalb einer bestimmten Zeit nicht möglich, wird dem Benutzer angezeigt, welche fehlen. Er kann dann dafür sorgen, dass diese in Reichweite kommen und die Auswertung abschliessen.

doc/docs/index.md

@@ -12,7 +12,7 @@ Kurzer Überblick über das DIY-Lasertag-System auf Basis von nRF52840, Thread u
 
 - Konzept Software: Rolle Leader/Weste/Waffe, Game Loop, CoAP-API.
 - Konzept Hardware: Aufbau der Einheiten, LED-Treiber, Akku-Setup.
-- Gameplay & Modi: [konzept/gameplay.md](konzept/gameplay.md) – Kurz erklärt, Rollen, Power-Ups und Spielmodi.
+- Gameplay & Modi: [concepts/gameplay.md](concepts/gameplay.md) – Kurz erklärt, Rollen, Power-Ups und Spielmodi.
 - Planung: Zephyr-Workspace-Struktur und Roadmap.
 
 **Lizenz**