Update .gitignore to exclude Android/Gradle files and enhance TimeEntryController and TimefixService for better error handling and performance. Refactor frontend components to use AppBrand for consistent branding across views.

ANDROID_FRONTEND_PLAN.md

@@ -0,0 +1,427 @@
+# Android-Frontend Plan
+
+Ziel: Ein funktional und visuell identisches Android-Frontend fuer TimeClock v3, das dieselbe Backend-API nutzt wie das bestehende Vue-Frontend und sich auf Smartphone und Tablet unterschiedlich bedienen laesst.
+
+## Ausgangslage
+
+- Bestehendes Web-Frontend: `frontend` mit Vue, Vite, Pinia und Vue Router.
+- Backend: `backend` mit REST-API unter `/api`.
+- Authentifizierung: JWT per `Authorization: Bearer <token>`.
+- Rollen: normaler Benutzer und Admin, sichtbar in der Navigation.
+- Design: helle, sachliche Web-Oberflaeche mit fester Titel-/Navigationsleiste, Statusbereich, dezenten Karten, kompakten Formularen und Bootstrap-aehnlichen Button-Zustaenden.
+- Aktuelle Hauptnavigation:
+  - Buchungen: Wochenuebersicht, Zeitkorrekturen, Urlaub, Krankheit, Arbeitstage, Kalender.
+  - Export.
+  - Einstellungen: Persoenliches, Passwort aendern, Zeitwuensche, Zugriffe verwalten, Einladen.
+  - Verwaltung fuer Admins: Feiertage, Rechte.
+  - Weitere vorhandene Routen: Eintraege, Statistiken.
+
+## Empfohlene technische Basis
+
+Neue App als eigenes Modul neben Web-Frontend und Backend:
+
+```text
+mobile-app/
+```
+
+Empfehlung: Kotlin Multiplatform mit Compose Multiplatform fuer Android.
+
+Gruende:
+
+- Native Android-Bedienung und gute Tablet-Unterstuetzung.
+- Gemeinsame UI-Patterns fuer Smartphone und Tablet per adaptivem Layout.
+- Klare Trennung vom bestehenden Vue-Web-Frontend.
+- Gute Erweiterbarkeit, falls spaeter Desktop oder weitere Plattformen relevant werden.
+
+Alternative: React Native oder Expo. Das waere schneller, wenn JavaScript/TypeScript wichtiger ist als native Android-Integration. Fuer diese Codebasis ist die native Kotlin/Compose-Variante langfristig sauberer, weil das Android-Frontend eigenstaendig und nicht als WebView-Klon entstehen soll.
+
+## Nicht-Ziele
+
+- Kein WebView, das nur das bestehende Frontend einbettet.
+- Keine Backend-Neuentwicklung.
+- Keine Veraenderung der fachlichen Regeln ohne separaten Auftrag.
+- Keine Vermischung von Android-Code im bestehenden `frontend`-Verzeichnis.
+- Keine freie Neugestaltung der App. Das Android-Design soll die Webversion wiedererkennbar und konsistent nachbilden.
+
+## Design-Paritaet zur Webversion
+
+Das Android-Frontend soll von Anfang an mit einem eigenen Compose-Designsystem aufgebaut werden, das die bestehende Webversion uebersetzt statt neu zu interpretieren.
+
+### Web-Design als Quelle
+
+Primaere Quellen:
+
+- `frontend/src/assets/main.css`
+- `frontend/src/App.vue`
+- `frontend/src/components/SideMenu.vue`
+- `frontend/src/components/StatusBox.vue`
+- Styles in den einzelnen Views, soweit sie fuer konkrete Screens relevant sind.
+
+Zu uebernehmende Merkmale:
+
+- Heller Hintergrund: weiss als App-Hintergrund.
+- Textfarbe: schwarz/dunkelgrau.
+- Schrift: System-Schrift analog Web (`-apple-system`, `Segoe UI`, Roboto, Arial). Android nutzt entsprechend Roboto/System Default.
+- Navbar: feste, helle gruenliche Leiste mit `#f0ffec`, dezenter Border `#e0ffe0` und leichtem Schatten.
+- Seitentitel: kompakte Box mit hellem Hintergrund, grauem Rand und 3 px Radius.
+- Karten: `#fafafa`, Rand `#e0e0e0`, Radius 6 px, dezenter Schatten.
+- Buttons:
+  - Standard: `#f5f5f5`, Rand `#ccc`, Text `#333`.
+  - Primary: `#5bc0de`, Rand `#46b8da`, Text weiss.
+  - Success: `#5cb85c`, Rand `#4cae4c`, Text weiss.
+  - Danger: `#d9534f`, Rand `#d43f3a`, Text weiss.
+  - Secondary: `#6c757d`, Text weiss.
+- Inputs: 1 px Rand `#ddd`, 4 px Radius, 8/12 px Innenabstand, Fokusfarbe `#5bc0de`.
+- Layout: grosszuegiger horizontaler Rand auf Tablet, kompakter auf Smartphone.
+- StatusBox: eigene wiederverwendbare Komponente mit Aktionsbuttons und Statuszeilen.
+
+### Android-Designsystem
+
+In der Grundapp sollen diese Bausteine zuerst entstehen:
+
+- `TimeClockTheme`
+  - Farben aus der Webversion.
+  - Typografie auf Basis der Android-Systemschrift.
+  - Standard-Abstaende und Radien.
+- `TcScaffold`
+  - Gemeinsame App-Shell fuer angemeldete Screens.
+  - Navbar/Header, Seitentitel, Statusbereich, Content und optional Footer-Ersatz.
+- `TcTopBar`
+  - Brand `Stechuhr`, aktueller Seitentitel, Benutzerbereich, Logout.
+- `TcStatusBox`
+  - Visuell und funktional an `StatusBox.vue` angelehnt.
+  - Zuerst mit Mock-/Preview-Daten, spaeter mit API-Daten.
+- `TcButton`
+  - Varianten: default, primary, success, danger, secondary.
+  - Gleiche Farb- und Randlogik wie Web.
+- `TcCard`
+  - Kartencontainer mit Web-Radius, Rand, Hintergrund und Schatten.
+- `TcTextField`
+  - Formularfelder mit Web-Input-Stil.
+- `TcSectionMenu`
+  - Mobile und Tablet-Varianten der Web-Navigation.
+- `TcLoading`, `TcError`, `TcEmptyState`
+  - Einheitliche Zustandsanzeigen im Web-Stil.
+
+### Design-Validierung
+
+Jede neue Android-Screen-Implementierung soll gegen die Webversion geprueft werden:
+
+- Farben stimmen mit den Web-CSS-Werten ueberein.
+- Abstaende und Dichte wirken wie die Webversion, nicht wie ein neues Material-Design.
+- Buttons, Karten, Inputs und Tabellen verwenden die gemeinsamen `Tc*`-Widgets.
+- Smartphone und Tablet duerfen unterschiedlich bedient werden, muessen aber klar dieselbe TimeClock-Oberflaeche bleiben.
+- Screens werden nicht direkt mit Compose-Material-Defaults gebaut, wenn dadurch das Web-Design verloren geht.
+
+## Funktionsumfang Paritaet
+
+### Authentifizierung
+
+- Login.
+- Registrierung, falls weiterhin mobil erlaubt.
+- Passwort vergessen.
+- Passwort zuruecksetzen.
+- Passwort aendern.
+- Session-Wiederherstellung beim App-Start.
+- Logout.
+- Token sicher speichern, nicht in Klartext-Preferences.
+- OAuth/Google pruefen: Fuer Android braucht der bestehende Web-OAuth-Flow wahrscheinlich eine eigene Deep-Link- oder App-Link-Strategie.
+
+### Zeiterfassung und Buchungen
+
+- Aktueller Status aus `/time-entries/current-state`.
+- Stempeln ueber `/time-entries/clock`.
+- Laufenden Eintrag anzeigen.
+- Wochenuebersicht.
+- Zeitkorrekturen.
+- Urlaub.
+- Krankheit.
+- Arbeitstage.
+- Kalender.
+- Eintraege anzeigen, bearbeiten und loeschen, soweit im Web-Frontend vorhanden.
+- Statistiken.
+
+### Einstellungen
+
+- Persoenliches Profil.
+- Passwort aendern.
+- Zeitwuensche.
+- Zugriffe verwalten.
+- Einladen.
+
+### Export
+
+- Exportfunktion analog Web.
+- Auf Android muss geklaert werden, ob Dateien direkt heruntergeladen, geteilt oder im System-Dateidialog gespeichert werden sollen.
+
+### Admin
+
+- Feiertage.
+- Rechte/Rollen.
+- Nur sichtbar und erreichbar fuer Admin-Benutzer.
+
+## API-Schicht
+
+Die Android-App bekommt eine eigene API-Schicht, die die bestehenden Endpunkte typisiert kapselt.
+
+Vorgeschlagene Struktur:
+
+```text
+mobile-app/
+  composeApp/
+    src/
+      commonMain/
+        kotlin/
+          api/
+          auth/
+          model/
+          repository/
+          ui/
+          util/
+      androidMain/
+        kotlin/
+```
+
+API-Aufgaben:
+
+- Basis-URL konfigurierbar machen.
+- JSON-Serialisierung zentral definieren.
+- Auth-Header automatisch setzen.
+- 401 zentral behandeln und Session beenden.
+- Fehlertexte aus Backend-Antworten normalisieren.
+- Datums- und Zeitzonenlogik konsistent zur Web-App halten.
+
+## Navigation
+
+### Smartphone
+
+Smartphone-Layout priorisiert schnelle Bedienung mit einer Hand, bleibt aber visuell an der Web-Navigation orientiert.
+
+- Bottom Navigation fuer die wichtigsten Bereiche:
+  - Buchungen.
+  - Kalender.
+  - Export oder Statistik, je nach tatsaechlicher Nutzung.
+  - Einstellungen.
+- Buchungen erhalten eine eigene Unterseite mit Liste oder Tabs:
+  - Wochenuebersicht.
+  - Zeitkorrekturen.
+  - Urlaub.
+  - Krankheit.
+  - Arbeitstage.
+- Der aktuelle Stempelstatus bleibt prominent oben sichtbar.
+- Primaere Aktion `Kommen/Gehen/Pause` als klarer Hauptbutton.
+- Admin-Funktionen nicht in der Bottom Navigation, sondern unter einem Verwaltungsbereich in Einstellungen oder einem Overflow-Menue.
+
+### Tablet
+
+Tablet-Layout nutzt die Breite fuer parallele Navigation und Inhalt und kommt der Webversion am naechsten.
+
+- Permanente Navigation links als Navigation Rail oder Side Drawer.
+- Statusbereich dauerhaft im oberen Inhaltskopf.
+- Master-Detail-Ansichten, wo sinnvoll:
+  - Kalender links, Tagesdetails rechts.
+  - Wochenuebersicht links, Eintragsdetails/Bearbeitung rechts.
+  - Rollen/Feiertage mit Liste und Detailpanel.
+- Keine reine Smartphone-Skalierung auf grosse Breite.
+- Dialoge auf Tablet als zentrierte Panels oder seitliche Detailbereiche, nicht als vollflaechige Seiten, sofern der Workflow dadurch klarer bleibt.
+
+### Breakpoints
+
+Vorschlag:
+
+- Compact: Smartphone-Portrait und kleine Breiten.
+- Medium: grosse Smartphones, Foldables, kleine Tablets.
+- Expanded: Tablets im Landscape-Modus.
+
+Die konkrete Entscheidung sollte nicht nur an Pixeln haengen, sondern an Android Window Size Classes.
+
+## Screen-Liste
+
+| Web-Route | Android-Screen | Smartphone | Tablet |
+| --- | --- | --- | --- |
+| `/login` | LoginScreen | Vollbildformular | schmales Formular in ruhigem Layout |
+| `/register` | RegisterScreen | Vollbildformular | Formularpanel |
+| `/password-forgot` | PasswordForgotScreen | Vollbildformular | Formularpanel |
+| `/password-reset` | PasswordResetScreen | Deep-Link-faehig | Deep-Link-faehig |
+| `/bookings/week` | WeekOverviewScreen | Liste/Tagesgruppen | Wochenraster plus Detailbereich |
+| `/bookings/timefix` | TimefixScreen | Formular/Liste getrennt | Liste plus Bearbeitung |
+| `/bookings/vacation` | VacationScreen | Antrag und Verlauf | Kalender/Liste plus Details |
+| `/bookings/sick` | SickScreen | Antrag und Verlauf | Liste plus Details |
+| `/bookings/workdays` | WorkdaysScreen | kompakte Wochenliste | tabellarische Monats-/Wochenansicht |
+| `/calendar` | CalendarScreen | Monatsansicht mit Tagesdetails | Kalender plus Seitenpanel |
+| `/export` | ExportScreen | Filter plus Aktion | Filter links, Ergebnis/Aktion rechts |
+| `/settings/profile` | ProfileScreen | Formular | Formularpanel |
+| `/settings/password` | PasswordChangeScreen | Formular | Formularpanel |
+| `/settings/timewish` | TimewishScreen | Liste/Formular | Liste plus Detail |
+| `/settings/invite` | InviteScreen | Formular/Liste | Verwaltungspanel |
+| `/settings/permissions` | PermissionsScreen | Liste | Liste plus Detail |
+| `/admin/holidays` | HolidaysAdminScreen | Admin-Liste | Tabelle plus Detail |
+| `/admin/roles` | RolesAdminScreen | Admin-Liste | Tabelle plus Detail |
+| `/entries` | EntriesScreen | Liste mit Filtern | Tabelle plus Detail |
+| `/stats` | StatsScreen | Karten/Diagramme untereinander | Dashboard-Raster |
+
+## Datenhaltung und Offline-Verhalten
+
+Die erste fachlich nutzbare Android-Version sollte online-first bleiben:
+
+- Kein vollstaendiger Offline-Modus.
+- Token und Benutzerprofil lokal speichern.
+- Letzten bekannten aktuellen Status optional cachen.
+- Bei fehlender Verbindung klare Fehlermeldung und keine riskanten lokalen Buchungen.
+
+Optional spaeter:
+
+- Offline-Warteschlange fuer Stempelaktionen.
+- Konfliktbehandlung bei Zeitkorrekturen.
+- Lokaler Read-Cache fuer Kalender und Wochenuebersicht.
+
+## Sicherheit
+
+- Token im Android Keystore oder ueber eine sichere Storage-Abstraktion speichern.
+- Screens mit sensiblen Daten optional gegen Screenshots schuetzen, falls gewuenscht.
+- Logout loescht lokale Session vollstaendig.
+- API-Basis-URL nicht hart im Code fuer alle Umgebungen fest verdrahten.
+- OAuth-Redirects nur ueber erlaubte App-/Deep-Link-Hosts.
+
+## Projektphasen
+
+### Phase 1: Grundapp und Designsystem
+
+- `mobile-app` anlegen.
+- Android-Build lauffaehig machen.
+- `TimeClockTheme` mit Farben, Typografie, Abstaenden, Radien und Schatten aus der Webversion.
+- Grundlegende `Tc*`-Widgets: Scaffold, TopBar, StatusBox, Button, Card, TextField, SectionMenu, Loading/Error.
+- Preview-/Demo-Screens fuer Smartphone und Tablet mit Mock-Daten.
+- Adaptive Grundnavigation, aber noch ohne vollstaendige fachliche Implementierung.
+- Designabgleich mit Web-Frontend anhand der bestehenden CSS-/Vue-Komponenten.
+
+Akzeptanz:
+
+- App startet auf Emulator/Device.
+- Grundshell sieht wie die Webversion aus.
+- Smartphone und Tablet haben unterschiedliche Layouts, aber identische visuelle Sprache.
+- Neue Screens koennen auf Basis der gemeinsamen Widgets gebaut werden.
+
+### Phase 2: API- und Auth-Fundament
+
+- App-Konfiguration fuer API-Basis-URL.
+- HTTP-Client, JSON, Fehlerbehandlung.
+- Secure Token Storage.
+- Auth-Flow: Login, Logout, Session-Wiederherstellung, `/auth/me`.
+
+Akzeptanz:
+
+- Login gegen bestehendes Backend funktioniert.
+- Geschuetzter Bereich wird nach App-Neustart wiederhergestellt.
+- Auth-Screens verwenden bereits die gemeinsamen Design-Widgets.
+
+### Phase 3: Shell und adaptive Navigation
+
+- Gemeinsames App-Layout.
+- Smartphone: Bottom Navigation plus Unterbereiche.
+- Tablet: permanente Navigation plus Inhaltsbereich.
+- Rollenbasierte Sichtbarkeit.
+- Statusleiste/Statusbereich analog Web-App.
+
+Akzeptanz:
+
+- Smartphone und Tablet zeigen bewusst unterschiedliche Navigation.
+- Admin-Menues erscheinen nur fuer Admins.
+- Session-Ablauf fuehrt sauber zurueck zum Login.
+
+### Phase 4: Kern-Zeiterfassung
+
+- Aktueller Status.
+- Kommen/Gehen/Pause ueber `/time-entries/clock`.
+- Laufender Eintrag.
+- Wochenuebersicht.
+- Eintraege anzeigen.
+
+Akzeptanz:
+
+- Kernworkflow kann mobil vollstaendig genutzt werden.
+- Web und Android zeigen danach konsistente Daten.
+
+### Phase 5: Buchungs-Workflows
+
+- Zeitkorrekturen.
+- Urlaub.
+- Krankheit.
+- Arbeitstage.
+- Kalender.
+
+Akzeptanz:
+
+- Jeder Buchungsbereich deckt die Web-Funktionen ab.
+- Tablet nutzt Detailpanels, Smartphone nutzt fokussierte Einzelseiten.
+
+### Phase 6: Einstellungen
+
+- Profil.
+- Passwort aendern.
+- Zeitwuensche.
+- Zugriffe verwalten.
+- Einladen.
+- Kein Export in der Android-App, da laut Entscheidung nicht gewuenscht.
+
+Akzeptanz:
+
+- Alle Nicht-Admin-Web-Funktionen sind mobil verfuegbar.
+
+### Phase 7: Admin und Navigation
+
+- Feiertage.
+- Rollen/Rechte.
+- Menüpunkte für alle bereiche implementieren. mit submenüs arbeiten, wie in der weboberfläche
+
+Akzeptanz:
+
+- Admin-Funktionen sind mobil und auf Tablet sinnvoll bedienbar.
+- Nicht-Admins koennen sie weder sehen noch aufrufen.
+- Alle Bereiche sind ansteuerbar
+
+### Phase 8: Qualitaet
+
+- Unit-Tests fuer API/Repository/Auth.
+- UI-Tests fuer Login, Navigation und Kern-Zeiterfassung.
+- Manuelle Tests auf Smartphone- und Tablet-Emulator.
+- Dark-Mode-Entscheidung treffen: entweder sauber unterstuetzen oder explizit deaktivieren.
+- Accessibility pruefen: Touch-Zielgroessen, Kontrast, TalkBack-Beschriftungen.
+- Visuelle Regressionen zumindest ueber dokumentierte Screenshots fuer Smartphone und Tablet pruefen.
+
+## Implementierungsstand
+
+- Phase 1 umgesetzt: Grundapp, responsives App-Shell-Layout und Web-Farbdesign.
+- Phase 2 umgesetzt: Login, Session-Restore, Logout, API-Konfiguration und Token-Store.
+- Phase 3 umgesetzt: aktueller Status, Stempeln, laufender Eintrag und Wochenuebersicht.
+- Phase 4 umgesetzt: Zeitkorrekturen, Urlaub, Krankheit, Arbeitstage und Kalender.
+- Phase 5 umgesetzt: Profil, Passwort, Zeitwuensche, Zugriffe verwalten und Einladen.
+- Phase 6 umgesetzt: Admin-Feiertage und Rollen/Rechte.
+- Phase 7 umgesetzt: Smartphone-Submenues wie in der Web-Navigation, dynamische Hauptnavigation, Eintraege und Statistiken.
+- Phase 8 umgesetzt als erste Qualitaetsschicht: lokale Unit-Tests, Offline-Stempel-Queue, technischer OAuth-/Offline-Plan und erfolgreicher Test-/Buildlauf.
+- Export ist in Android aus Navigation und Menues entfernt.
+
+## Offene Entscheidungen
+
+- Soll die Android-App nur intern installiert werden oder spaeter in den Play Store? - später im playstore
+- Welche Android-Mindestversion ist gewuenscht? 15
+- Soll Registrierung in der App erlaubt sein oder nur Login? registrierung
+- Soll Google OAuth in Android direkt unterstuetzt werden oder vorerst nur E-Mail/Passwort? oauth
+- Soll Stempeln offline moeglich sein? ja
+- Welche Export-Zielform ist mobil gewuenscht: Download, Teilen, E-Mail oder System-Dateiauswahl? kein export
+- Gibt es bestehende Corporate-Design-Vorgaben ausser dem aktuellen Web-Look? nein
+- Soll der Web-Look exakt nachgebaut werden, auch wenn einzelne Material-Android-Konventionen dadurch weniger stark genutzt werden? ja.
+
+## Risiken
+
+- OAuth braucht fuer Android eine eigene Redirect-Strategie.
+- Datums-/Zeitzonenlogik kann zwischen Web, Backend und Android abweichen, wenn sie nicht frueh getestet wird.
+- Tablet-Paritaet braucht eigene Layout-Entscheidungen, sonst entsteht nur eine gestreckte Smartphone-App.
+- Backend-Endpunkte muessen fuer alle Web-Funktionen ausreichend dokumentiert oder aus den Controllern abgeleitet werden.
+- Wenn die Grundwidgets nicht zuerst stehen, entsteht spaeter schnell ein uneinheitlicher Mix aus Web-Look und Android-Material-Defaults.
+
+## Naechster sinnvoller Schritt
+
+1. OAuth-Deep-Link/Custom-Tab-Flow mit Backend-Konfiguration umsetzen.
+2. Offline-Stempeln mit UI-Anzeige, Konfliktbehandlung und Sync-Status erweitern.
+3. Compose-Screenshot-/Instrumented-Tests fuer Smartphone und Tablet ergaenzen.