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:

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