Convert backend from submodule to regular directory

Remove submodule tracking; backend is now a plain directory in the repo. Also update deploy workflow: remove --recurse-submodules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-07 16:59:50 +02:00
parent 0bb7758a2f
commit d0b0b4f8bd
35 changed files with 2271 additions and 8 deletions
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@@ -0,0 +1,109 @@
+# CLAUDE.md — Pamietnik Backend (Go Server)
+
+## Stack
+
+Language:   Go
+DB:         PostgreSQL
+API-Doc:    OpenAPI 3.1 (openapi.yaml)
+Auth:       Session Cookie (Web UI); API-Key oder JWT (Android Upload, TBD)
+Hashing:    Argon2id (Passwörter)
+Geocoding:  Nominatim (OSM) mit Cache + Rate-Limit; Provider austauschbar
+Maps:       OpenStreetMap Tiles (konfigurierbar, serverseitig)
+Dev:        docker-compose (API + PostgreSQL)
+
+---
+
+## Kern-Features (Backend)
+
+1. REST API Ingest: Single + Batch Trackpoints (Idempotenz via event_id)
+2. Idempotenz/Dedupe: Unique Key (device_id, event_id); Duplikate = 200 OK
+3. Stop Detection: Aufenthalte erkennen (minDuration + radiusMeters konfigurierbar)
+4. Suggestions: Aus Stops Vorschläge ableiten + speichern
+5. Reverse-Geocoding: Nominatim gecached, Provider austauschbar via Config
+6. Web UI: Login (Session Cookie), Tagesübersicht, Tagesdetail, Karte
+7. Auth: Argon2id Passwort-Hashing, Session-Store in PostgreSQL
+
+---
+
+## API Endpoints
+
+Ingest:
+  POST   /v1/trackpoints            <- Single Trackpoint
+  POST   /v1/trackpoints:batch      <- Batch Trackpoints
+  GET    /healthz
+  GET    /readyz
+
+Query (Auth required):
+  GET    /v1/days?from=YYYY-MM-DD&to=YYYY-MM-DD
+  GET    /v1/trackpoints?date=YYYY-MM-DD
+  GET    /v1/stops?date=YYYY-MM-DD
+  GET    /v1/suggestions?date=YYYY-MM-DD
+
+Web UI (Session Cookie, serverseitig gerendert):
+  GET    /login
+  POST   /login
+  POST   /logout
+  GET    /days
+  GET    /days/{yyyy-mm-dd}
+
+---
+
+## Datenmodell (Kern)
+
+Trackpoint:
+  event_id    string (UUID, client-generated)
+  device_id   string
+  trip_id     string
+  timestamp   RFC3339 oder epochMillis (TBD)
+  lat, lon    float64
+  source      "gps" | "manual"
+  note        string (optional)
+
+Stop:
+  stop_id     string
+  device_id, trip_id
+  start_ts, end_ts
+  center_lat, center_lon
+  duration_s  int
+  place_label string (optional, Nominatim)
+
+Suggestion:
+  suggestion_id
+  stop_id
+  type        "highlight" | "name_place" | "add_note"
+  title/text  string
+  created_at, dismissed_at
+
+---
+
+## Architektur-Prinzipien
+
+- Idempotenz zuerst: Kein Duplicate Insert, immer event_id prüfen
+- Geocoding nur ereignisbasiert (pro Stop), niemals periodisch/bulk
+- Geocoding-Provider über Config austauschbar (kein Hardcode)
+- Sessions serverseitig in PostgreSQL (invalidierbar bei Logout)
+- Stop Detection Parameter (minDuration, radiusMeters) konfigurierbar
+- OpenAPI immer aktuell halten; Änderungen nur via PR + CI Validation
+
+---
+
+## Offene Entscheidungen (TBD)
+
+- timestamp Format: epochMillis vs RFC3339
+- Android Upload Auth: X-API-Key vs JWT
+- Payload: JSON vs Protobuf
+- Batch limits (max items, max bytes)
+- Retention Policy (Trackpoints löschen nach X Tagen)
+- Stop-Detection Parameter (Mindestdauer, Radius)
+- Geocoding Provider: Nominatim public vs self-hosted vs Alternative
+
+---
+
+## Nächste Tasks (Reihenfolge)
+
+- [ ] T024  REST API finalisieren (Endpoints, Fehlerformat, Limits)
+- [ ] T027  PostgreSQL Schema + Migrationen + Indizes
+- [ ] T028  Idempotenz implementieren (unique event_id pro device)
+- [ ] T029  Observability (Logs/Metrics), Health/Ready
+- [ ] T030  docker-compose lokal (API + PostgreSQL) + Minimal-Client
+- [ ] T050  Auth-Konzept festlegen