# 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 `. - 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.