pamietnik/app/CLAUDE.md

CLAUDE.md — RALPH Android Frontend

Stack

Language: Kotlin UI: Jetpack Compose DB: Room (SQLite) Worker: WorkManager Maps: MapLibre + OpenStreetMap HTTP: Retrofit oder Ktor Client (TBD) Auth: TBD (API-Key vs JWT für Upload)

---

Kern-Features (Android)

1. Background GPS-Tracking (COARSE/FINE + Background permission)
2. Offline Queue (Room) + WorkManager Upload (Idempotenz via event_id)
3. Manuelle Punkte hinzufügen (lat/lon/timestamp/notiz + Validierung)
4. Kartenansicht (MapLibre, Tile-Quelle konfigurierbar)
5. Datei-Export (SAF ACTION_CREATE_DOCUMENT)

---

Architektur-Prinzipien

• Offline-First: Jeder Punkt wird zuerst lokal in Room gespeichert
• Upload via WorkManager mit Constraint: Network connected + Retry/Backoff
• Idempotenz: Jeder Punkt erhält eine client-seitige event_id (UUID)
• source-Feld: "gps" | "manual" unterscheidet Punkt-Typ
• Validierung manueller Punkte: as the user types im ViewModel

---

Offene Entscheidungen (TBD)

• HTTP Client: Retrofit vs Ktor
• timestamp Format: epochMillis vs RFC3339
• Android Upload Auth: X-API-Key vs JWT
• minSdk festlegen

---

Nächste Tasks (Reihenfolge)

• T001 Compose-Projekt anlegen (Kotlin, minSdk festlegen)
• T001a Kotlin-Standards festlegen (Coroutines, KTX, Code Style)
• T004 Permissions Manifest + Runtime-Flow (COARSE/FINE + Background)
• T006 Background-Tracking Architektur (Foreground Service)
• T033 Room-Setup (Entities/DAOs/Migrations)
• T008 Upload-Queue (pending/sent/failed, retryCount)
• T012 Upload-Worker (WorkManager, Retry/Backoff)
• T080 UI: Manuellen Punkt hinzufügen
• T081 Eingabevalidierung Compose (as the user types)
• T018 Export via SAF

---

Antwort-Stil

• Kotlin-Code immer mit Coroutines/Flow
• Compose-Code: State Hoisting, ViewModel pattern
• Kein direkter DB/Network-Zugriff in Composables
• Tests: JVM Unit Tests für Domain/Queue; Instrumentation für Room/Worker