Publish expanded StaySense wiki documentation

2026-02-16 08:54:40 +01:00 · 2026-02-16 08:54:40 +01:00 · a1b75c72c9
commit a1b75c72c9
parent 74f4ebafb2
7 changed files with 264 additions and 1 deletions
--- a/API-Reference.md
+++ b/API-Reference.md
@ -0,0 +1,76 @@
+# API Reference
+
+Base URL:
+
+`https://staysense.vanityontour.de/api`
+
+## GET /health
+
+System- und Datenquellenstatus.
+
+Beispiel:
+
+```bash
+curl -s https://staysense.vanityontour.de/api/health
+```
+
+## GET /spot/score
+
+Query:
+- `lat` (float)
+- `lon` (float)
+- `at` (ISO-8601, z. B. `2026-02-16T22:30:00Z`)
+
+Antwort enthält u. a.:
+- `score` (0-100)
+- `ampel` (`green|yellow|red`)
+- `reasons`
+- `factors`
+- `explanation.factors` (transparente Details)
+- `explanation.spot_context` (Umfeld-Distanzen)
+- `meta.quality` (Datenqualität)
+
+Beispiel:
+
+```bash
+curl -s "https://staysense.vanityontour.de/api/spot/score?lat=51.10893&lon=6.90460&at=2026-02-16T22:30:00Z"
+```
+
+## POST /spot/signal
+
+Body:
+- `spot_id`
+- `signal_type` (`calm|noise|knock|police`)
+- `device_token`
+- `timestamp` (ISO-8601)
+
+Beispiel:
+
+```bash
+curl -s -X POST https://staysense.vanityontour.de/api/spot/signal \
+  -H "Content-Type: application/json" \
+  -d '{
+    "spot_id":"2a227634-683d-54e9-8a4b-32d434251380",
+    "signal_type":"noise",
+    "device_token":"550e8400-e29b-41d4-a716-446655440000",
+    "timestamp":"2026-02-16T22:35:00Z"
+  }'
+```
+
+Hinweis:
+- Cooldown aktiv (pro Spot/Device nur 1 Signal pro 24h); bei Verstoß: `429`.
+
+## GET /geocode/search
+
+Query:
+- `q` (Suchtext)
+
+Beispiel:
+
+```bash
+curl -s "https://staysense.vanityontour.de/api/geocode/search?q=Hilden"
+```
+
+## GET /map/tile/{z}/{x}/{y}.png
+
+Proxy für OSM-Tiles (für die Web-Karte).
--- a/Admin-API.md
+++ b/Admin-API.md
@ -0,0 +1,40 @@
+# Admin API
+
+Alle Admin-Endpunkte benötigen einen Bearer Token, außer Bootstrap Status/Login.
+
+Base URL:
+
+`https://staysense.vanityontour.de/api`
+
+## Token erhalten
+
+```bash
+curl -s -X POST https://staysense.vanityontour.de/api/admin/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"DEIN_USER","password":"DEIN_PASSWORT"}'
+```
+
+Token steht in `session.token`.
+
+## Header für Folgeanfragen
+
+`Authorization: Bearer <TOKEN>`
+
+## Endpunkte
+
+- `GET /admin/bootstrap/status`
+- `POST /admin/bootstrap` (nur initial)
+- `POST /admin/login`
+- `POST /admin/logout`
+- `GET /admin/overview`
+- `GET /admin/events?limit=100`
+- `POST /admin/events`
+- `PUT /admin/events/{id}`
+- `DELETE /admin/events/{id}`
+
+## Beispiel: Overview
+
+```bash
+curl -s https://staysense.vanityontour.de/api/admin/overview \
+  -H "Authorization: Bearer <TOKEN>"
+```
--- a/Data-Sources-and-Attribution.md
+++ b/Data-Sources-and-Attribution.md
@ -0,0 +1,24 @@
+# Data Sources and Attribution
+
+## Kernquellen
+
+1. OpenStreetMap (OSM)
+- Nutzung: Karte, POIs, Zonen-/Straßentypen
+- Lizenz: ODbL
+- Attribution erforderlich in der App
+
+2. Open Data NRW / Kommunale Feeds
+- Nutzung: lokale Events/Baustellen/verkehrsnahe Hinweise
+- Lizenz je Quelle prüfen (z. B. Datenlizenz Deutschland)
+
+## Datenschutz (MVP)
+
+- Kein Login für Community-Signale
+- Kein Device-Fingerprinting
+- Missbrauchsschutz über gehashte Device-Tokens (HMAC)
+
+## Rechtliche Seiten (Web)
+
+- Impressum: `https://vanityontour.de/impressum/`
+- Datenschutz: `https://staysense.vanityontour.de/datenschutz.html`
+- Quellen/Attribution: `https://staysense.vanityontour.de/quellen.html`
--- a/Deployment.md
+++ b/Deployment.md
@ -0,0 +1,31 @@
+# Deployment
+
+Zielplattform aktuell: Hetzner + CloudPanel + Nginx + systemd.
+
+## Komponenten
+
+- App-Code: `/opt/staysense`
+- API-Service: `staysense-api.service`
+- Import-Timer: `staysense-import.timer`
+- Frontend-Root: `/home/staysense-site/htdocs/staysense.vanityontour.de/`
+
+## Rollout (vereinfacht)
+
+```bash
+cd /opt/staysense
+git pull --ff-only
+rsync -a --delete /opt/staysense/src/ /home/staysense-site/htdocs/staysense.vanityontour.de/
+systemctl restart staysense-api.service
+nginx -t && systemctl reload nginx
+```
+
+## Pflichtchecks
+
+```bash
+systemctl is-active staysense-api.service
+curl -s -L https://staysense.vanityontour.de/api/health
+```
+
+## HTTPS
+
+TLS-Zertifikate werden über CloudPanel verwaltet.
--- a/Home.md
+++ b/Home.md
@ -1 +1,32 @@
-Welcome to the StaySense wiki!
+# StaySense Wiki
+
+StaySense bewertet in weniger als 10 Sekunden, wie ruhig ein Spot in der Nacht (22:00-06:00) voraussichtlich ist.
+
+## Produktstatus
+
+- Region: NRW (Pilot: Kreis Mettmann)
+- Plattform: WebApp / PWA (iOS-optimiert)
+- API + Admin-Bereich: aktiv
+- Offline-First: Score-Cache + Signal-Queue
+
+## Schnellstart
+
+1. API Health prüfen: `GET /api/health`
+2. Score laden: `GET /api/spot/score?lat=...&lon=...&at=...`
+3. Community-Signal senden: `POST /api/spot/signal`
+4. Admin Login: `POST /api/admin/login`
+
+## Dokumentation
+
+- [API Reference](API-Reference)
+- [Admin API](Admin-API)
+- [Deployment](Deployment)
+- [Operations Runbook](Operations-Runbook)
+- [Roadmap 30-60-90](Roadmap-30-60-90)
+- [Data Sources & Attribution](Data-Sources-and-Attribution)
+
+## Wichtige Links
+
+- WebApp: `https://staysense.vanityontour.de`
+- API Base: `https://staysense.vanityontour.de/api`
+- Repository: `https://github.com/OliverGiertz/StaySense`
--- a/Operations-Runbook.md
+++ b/Operations-Runbook.md
@ -0,0 +1,34 @@
+# Operations Runbook
+
+## Health & Status
+
+```bash
+systemctl status staysense-api.service --no-pager
+systemctl status staysense-import.timer --no-pager
+curl -s https://staysense.vanityontour.de/api/health
+```
+
+## Logs
+
+```bash
+journalctl -u staysense-api.service --no-pager -n 120
+journalctl -u staysense-import.service --no-pager -n 120
+```
+
+## Häufige Fehlerbilder
+
+1. `Kein Live-Score` bei Nutzern
+- API Health prüfen
+- `/api/spot/score` direkt mit Testkoordinaten prüfen
+
+2. DB readonly / Schreibfehler
+- Datenverzeichnisrechte prüfen
+- Service-User und Besitzrechte prüfen
+
+3. Importdaten veraltet
+- Timer-Status prüfen
+- Import-Service manuell starten
+
+```bash
+systemctl start staysense-import.service
+```
--- a/Roadmap-30-60-90.md
+++ b/Roadmap-30-60-90.md
@ -0,0 +1,27 @@
+# Roadmap 30-60-90
+
+Stand: 2026-02-16
+
+## Top-3 umgesetzt
+
+1. Transparente Score-Erklärung (`explanation.factors`, `explanation.spot_context`)
+2. Datenqualitätsindikator (`meta.quality`)
+3. Karten-UX mit verschiebbarem Pin
+
+## 0-30 Tage
+
+- Monitoring/Alerting API + Import
+- Bessere Admin-Filter + Fehlermeldungen
+- Degraded-Mode Monitoring
+
+## 31-60 Tage
+
+- Ruhigere Alternativen im Umkreis
+- Strukturierte Community-Signalfelder
+- Mehr NRW OpenData-Quellen
+
+## 61-90 Tage
+
+- PostgreSQL(+PostGIS) Migration
+- Anomalie-Erkennung gegen Missbrauch
+- Versionierte OpenAPI-Dokumentation