# Flutter Desktop-App – Umsetzungsplan

## Ziel und Leitentscheidung

Eine eigenständige, plattformübergreifende **Flutter-/Dart-Desktop-App** für Windows, macOS und Linux. Sie rendert ihre Oberflächen selbst mit Flutter – **keine WebView und keine eingebettete Vue-Webseite**.

Die bestehende Express-/MySQL-Anwendung bleibt die gemeinsame Server- und API-Plattform. Web- und Desktop-App arbeiten deshalb mit denselben Vereinsdaten, Benutzern und Berechtigungen.

**Abgrenzung:** Das Vue-Frontend wird nicht portiert oder eingebettet. Es dient nur als fachliche Referenz für Abläufe und API-Nutzung.

## Zielarchitektur

```text
Flutter Desktop-App (Dart)
  ├── eigene native Flutter-Oberfläche
  ├── REST-Client → https://tt-tagebuch.de/api
  ├── sicherer Token-Speicher des Betriebssystems
  └── später: Socket.IO, Benachrichtigungen, Datei-/Druckfunktionen

Bestehendes Node/Express-Backend
  ├── JWT-Authentifizierung und Berechtigungsprüfung
  ├── MySQL-Datenbank
  └── bestehende REST- und Socket.IO-Schnittstellen
```

### Technische Festlegungen

- Neues Projekt im Repository: `backend/desktop-app/`.
- Flutter stable und Dart; Windows, macOS und Linux von Beginn an als Build-Ziele aktivieren.
- `go_router` für Navigation, `flutter_riverpod` für App-Zustand und `Dio` für HTTP.
- Datenmodelle, Repositorys und API-Client von Widgets trennen; DTOs nicht direkt in der UI verwenden.
- API-URL ausschließlich per `--dart-define` bzw. Build-Konfiguration setzen, nie fest in Quellcode oder Installer einbauen.
- JWT in `flutter_secure_storage` ablegen. Bei `401` Token entfernen und zur Anmeldung wechseln; Netzwerkfehler führen nicht zum Logout.
- Requests senden den vom Backend unterstützten Header `Authorization: Bearer <token>`; kompatibel bleibt auch der Web-Header `authcode`.
- Berechtigungen immer vom Backend erzwingen lassen. Die Flutter-Navigation blendet fehlende Rechte nur für eine bessere Bedienung aus.
- Deutsch als erste Sprache; Übersetzungen von Beginn an über Flutter-Lokalisierung strukturieren.

## Phasen und To-dos

### Phase 0 – API und Produktumfang festziehen

- [x] Desktop-MVP verbindlich auf **Login, Vereinskontext, Kalender, Spielplan, Mitglieder und Trainingsübersicht** begrenzen.
- [x] Rollen für das MVP festlegen: einfaches Mitglied, Trainer und Vereinsverwaltung; pro Rolle die sichtbaren Bereiche definieren.
- [x] Die verwendeten Endpunkte und Payloads gegen `docs/api_contract.md` und die echten Routen prüfen.
- [x] Fehlende oder uneinheitliche API-Antworten als eigene Backend-Tickets erfassen, statt sie in der App zu umgehen.
- [x] Gemeinsame Fehlercodes und Lade-/Leerezustände für die App festlegen.
- [x] Datenschutz- und Offline-Anforderungen entscheiden: zunächst online-first, lokale Daten nur als Cache.

### Phase 1 – Projektfundament

- [x] Flutter-Projekt in `backend/desktop-app/` erzeugen und eine nachvollziehbare README mit Voraussetzungen erstellen.
- [x] Paketstruktur anlegen: `core/`, `features/`, `data/`, `domain/`, `presentation/`.
- [x] Build-Konfigurationen `development`, `staging` und `production` mit `API_BASE_URL` per Dart-Define einrichten.
- [x] App-Theme, Typografie, responsive Desktop-Layout und zentrale Design-Tokens anlegen.
- [x] Navigation mit öffentlichem Bereich und geschütztem App-Bereich aufsetzen.
- [x] Fehlerbehandlung, Logging ohne personenbezogene Daten und zentrale Ladeindikatoren implementieren.
- [x] CI-Grundgerüst für Formatierung, Analyse und Tests anlegen.

### Phase 2 – Anmeldung, Sitzung und Vereinskontext

- [ ] Login gegen `POST /api/auth/login` implementieren, inklusive „angemeldet bleiben“.
- [ ] Token sicher speichern, beim Start wiederherstellen und Sitzung mit `GET /api/session/status` prüfen.
- [ ] Logout über `POST /api/auth/logout` implementieren und lokale Zugangsdaten zuverlässig löschen.
- [ ] Passwort-vergessen- und Passwort-zurücksetzen-Flows als native Formulare ergänzen.
- [ ] Vereinsliste über `GET /api/clubs` laden und aktiven Verein persistent auswählen.
- [ ] Berechtigungen über `GET /api/permissions/:clubId` laden und die Navigation rollenabhängig aufbauen.
- [ ] Unit- und Integrationstests für Login, Tokenablauf, 401 und Vereinswechsel schreiben.

### Phase 3 – Desktop-MVP: persönliche Organisation

- [ ] Startseite mit nächstem Training, nächstem Spiel, offenen Hinweisen und Schnellzugriffen erstellen.
- [ ] Kalenderansicht für Trainings-, Vereins- und Spieltermine umsetzen.
- [ ] Spielplan mit Saison- und Mannschaftsauswahl sowie korrekter Berliner Zeitzonenanzeige umsetzen.
- [ ] Mitgliederliste mit Suche und einer datensparsamen Detailansicht implementieren.
- [ ] Trainingsübersicht mit Gruppen, Zeiten und Trainingsstatistik für berechtigte Rollen implementieren.
- [ ] Für einfaches Mitglied den Bereich „Mein Verein“ mit persönlichen Terminen und Informationen priorisieren.
- [ ] Leere Zustände, fehlende Berechtigungen, langsame Verbindung und Serverfehler in allen MVP-Ansichten testen.

### Phase 4 – Vereins- und Trainerfunktionen

- [ ] Trainingstagebuch inklusive Anwesenheit, Aktivitäten und Gruppen als native Arbeitsansicht umsetzen.
- [ ] Mitgliederverwaltung mit Bearbeiten, Bild-/Datei-Upload und Rechteprüfung erweitern.
- [ ] Sammlungsbestellungen als gemeinsames Modul einplanen und implementieren: Wünsche, Artikelstatus, Rückfragen, Preise, Bestätigung und Zahlungsstatus.
- [ ] Mannschaften, Spielberichte/Ergebnisse und Turniere in fachlich getrennten Features ergänzen.
- [ ] Rechnungen, Kommunikation, Aufgaben und Archiv erst nach einem eigenen UX-Entwurf als weitere Feature-Wellen ergänzen.
- [ ] Socket.IO für die Bereiche aktivieren, in denen aktuelle Daten tatsächlich einen Mehrwert bringen; REST bleibt die verlässliche Basis.

### Phase 5 – echte Desktop-Mehrwerte

- [ ] Systembenachrichtigungen für Terminänderungen, Rückfragen und neue Vereinsnachrichten einführen.
- [ ] Tray-Icon mit „Heute“, Synchronisationsstatus und Schnellaktionen ergänzen.
- [ ] Native Datei-Auswahl, Downloads, PDF-Export und Druckabläufe implementieren.
- [ ] Fensterzustand, zuletzt gewählter Verein und bevorzugte Ansicht lokal speichern.
- [ ] Offline-Cache für lesende Kernansichten konzipieren; Konfliktregeln vor schreibender Offline-Unterstützung festlegen.
- [ ] Signierte Installer für Windows, macOS und Linux sowie eine sichere Update-Strategie vorbereiten.

### Phase 6 – Qualität, Release und Betrieb

- [ ] Widget-Tests für jede neue Ansicht und Repository-/API-Tests für kritische Datenflüsse ergänzen.
- [ ] Integrationstests für Anmeldung, Vereinswechsel, Kalender und Spielplan aufsetzen.
- [ ] Smoke-Tests auf Windows, macOS und Linux durchführen; dabei Skalierung, Tastaturnavigation und Zeitzonen prüfen.
- [ ] Accessibility prüfen: Fokusführung, Kontraste, Screenreader-Beschriftungen und vollständig bedienbare Tastaturwege.
- [ ] Release-Kanäle (intern/stabil), Versionsnummern, Fehlerberichte und Datenschutztexte definieren.
- [ ] Pilot mit einem Verein durchführen und erst danach die nächste Paritätswelle freigeben.

## Reihenfolge nach dem MVP

1. Persönliche Funktionen: Mein Verein, Kalender, Spielplan und Benachrichtigungen.
2. Trainer-Arbeitsabläufe: Trainingstagebuch, Anwesenheit, Gruppen und Trainingselemente.
3. Vereinsverwaltung: Mitglieder, Kommunikation, Sammlungsbestellungen, Aufgaben und Dokumente.
4. Komplexe Spezialfunktionen: Turniere, Rechnungen, Importe, externe myTischtennis-/click-TT-Abläufe und Offline-Schreiben.

## Kritische vorhandene Referenzen

- `backend/server.js` – zentrale API-Routen.
- `backend/middleware/authMiddleware.js` und `backend/services/authService.js` – JWT- und Sitzungsverhalten.
- `docs/api_contract.md` – aktueller API-Katalog.
- `docs/socket_contract.md` – spätere Live-Updates.
- `frontend/src/router.js` – fachliche Web-Bereiche und Berechtigungen als Referenz, nicht als UI-Vorlage.
- `docs/simple-user-plan.md` und `docs/collective-orders-plan.md` – bereits geplante Nutzer- und Bestellabläufe.

## Abnahmekriterien für Release 1

- Die App ist eine eigenständige Flutter-Anwendung ohne WebView.
- Login, sicherer Sitzungsspeicher und Logout funktionieren gegen die Produktions-API.
- Ein Nutzer sieht ausschließlich die für seine Vereinsrolle erlaubten Bereiche.
- Kalender, Spielplan, Mitglieder und Trainingsübersicht funktionieren auf allen drei Desktop-Plattformen.
- `flutter analyze` und `flutter test` laufen fehlerfrei; je Plattform gibt es mindestens einen erfolgreichen manuellen Smoke-Test.
