refactored broad range of the application, split files, modularized calendar and file views, centralized bottom sheets and clipboard handling, and implemented unit test coverage

2026-05-08 19:05:16 +02:00
parent 3b1b0d0c19
commit c62a14645a
68 changed files with 4633 additions and 3141 deletions
@@ -0,0 +1,77 @@
+# MarianumMobile Client
+
+Flutter-App für die Schul-Community: Webuntis-Stundenplan, Nextcloud Talk + Files, Custom MHSL-Backend (Breaker, Custom Events, Push).
+
+## Stack
+
+- **Flutter** (Dart >= 3.8)
+- **State:** `flutter_bloc` + `hydrated_bloc` (persistente BLoCs pro Modul)
+- **Navigation:** `persistent_bottom_nav_bar_v2` mit zentraler `AppRoutes`-Klasse als Single Entry Point
+- **HTTP:** `dio`, lokales Caching via `localstore` (Generic `RequestCache<T>`)
+- **Calendar:** `syncfusion_flutter_calendar`
+- **Datum/Zeit:** `jiffy` – wird **nur** über die Extensions in `lib/extensions/date_time.dart` verwendet
+- **Code-Gen:** `freezed`, `json_serializable`
+
+## Ordnerstruktur
+
+```
+lib/
+├── api/                    HTTP-Layer pro Backend (mhsl/, marianumcloud/, webuntis/, holidays/)
+├── state/app/modules/      BLoC pro Feature-Modul (timetable, chat, chat_list, files, ...)
+├── state/app/infrastructure LoadableState<T>, DataLoader, geteilte BLoC-Bausteine
+├── view/                   Screens
+│   ├── login/              Login-Flow
+│   └── pages/              ein Verzeichnis pro Modul (timetable, files, talk, ...)
+├── widget/                 Geteilte UI-Komponenten (Dialoge, Buttons, Sheets)
+├── extensions/             DateTime-, Text-, TimeOfDay-Extensions
+├── routing/                AppRoutes (Single Navigation Entry)
+├── theming/                Light/Dark Theme
+├── storage/                Freezed Settings-Modelle (HydratedBloc-persistent)
+├── notification/           Firebase + flutter_local_notifications
+└── utils/                  Helper (clipboard_helper, debouncer, download_manager, ...)
+```
+
+## Konventionen
+
+**Navigation:** Ausschließlich über `AppRoutes.openX(context, ...)`. Direkte `Navigator.push(...)` für volle Pages sind nicht erlaubt – `Navigator.pop` für Sheets/Dialogs bleibt am Call-Site.
+
+**Dialoge:**
+- Info/Fehler: `InfoDialog.show(context, body, copyable: true, title: '...')` aus `lib/widget/info_dialog.dart`.
+- Bestätigung: `ConfirmDialog(...).asDialog(context)` aus `lib/widget/confirm_dialog.dart`. Async-Bestätigung nutzt `onConfirmAsync` (zeigt Spinner und Inline-Fehler über `AsyncDialogAction`).
+- **Kein** inline `AlertDialog`/`SimpleDialog` mehr.
+
+**Bottom-Sheets:** Detail-Sheets gehen über `showDetailsBottomSheet(context, header: ..., children: (ctx) => [...])` aus `lib/widget/details_bottom_sheet.dart`. Header ist optional.
+
+**Async-Actions:** Statt manuelles Spinner+Try/Catch die `AsyncActionButton`-Familie aus `lib/widget/async_action_button.dart` (`AsyncActionButton`, `AsyncTextButton`, `AsyncIconButton`, `AsyncFab`, `AsyncListTile`, `AsyncDialogAction`, `runWithErrorDialog`). Fehler-Mapping läuft über `errorBuilder` oder zentral über `errorToUserMessage` aus `lib/api/errors/error_mapper.dart`.
+
+**Clipboard:** Über `copyToClipboard(context, text)` aus `lib/utils/clipboard_helper.dart`. Zeigt automatisch SnackBar.
+
+**Datum/Zeit-Formatierung:** Über die Extensions in `lib/extensions/date_time.dart`:
+`dt.formatHm()`, `dt.formatDate()`, `dt.formatDateTime()`, `dt.formatDateShort()`, `dt.formatRelative()`, `start.timeRangeTo(end)`. **Kein** direktes `Jiffy.parseFromDateTime(...).format(pattern: '...')` im View-Code.
+
+**Settings:** Pro Feature ein Freezed-Modell unter `lib/storage/`, persistiert via HydratedBloc.
+
+## Build / Run
+
+```bash
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs   # nach Änderungen an Freezed/JSON-Modellen
+flutter run                                                  # Debug auf angeschlossenem Device
+flutter analyze                                              # statische Analyse, muss 0 Issues melden
+flutter test                                                 # Tests (siehe test/)
+```
+
+## Backend-Integrationen
+
+| Backend                   | Pfad                  | Zweck                                  |
+|---------------------------|-----------------------|----------------------------------------|
+| Webuntis                  | `lib/api/webuntis/`   | Stundenplan, Klassen, Räume, Lehrer    |
+| Nextcloud (Talk + WebDAV) | `lib/api/marianumcloud/` | Chats, Datei-Verwaltung             |
+| Custom MHSL-Server        | `lib/api/mhsl/`       | Breaker, Custom Events, Notify, Noten  |
+| Holiday-Calendar          | `lib/api/holidays/`   | Ferien                                 |
+
+`nextcloud`-Paket ist auf einen Custom-Fork gepinnt (siehe `pubspec.yaml` `dependency_overrides`).
+
+## Tests
+
+`test/` deckt aktuell nur Kern-Funktionen ab (DateTime-Extensions, AsyncActionController, LessonResolver). Beim Hinzufügen neuer pure-function-Helper bitte Test mit dazu.