Files

Deploy to NAS / deploy (push) Failing after 4s

Details

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

3.1 KiB

Raw Blame History

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)

REST API Ingest: Single + Batch Trackpoints (Idempotenz via event_id)
Idempotenz/Dedupe: Unique Key (device_id, event_id); Duplikate = 200 OK
Stop Detection: Aufenthalte erkennen (minDuration + radiusMeters konfigurierbar)
Suggestions: Aus Stops Vorschläge ableiten + speichern
Reverse-Geocoding: Nominatim gecached, Provider austauschbar via Config
Web UI: Login (Session Cookie), Tagesübersicht, Tagesdetail, Karte
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

3.1 KiB Raw Blame History