d0b0b4f8bd
Some checks failed
Deploy to NAS / deploy (push) Failing after 4s
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>
110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
# 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
|