stechuhr3/ANDROID_FRONTEND_PLAN.md

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:

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:

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.