From 42f3baecb648ebf8d08a5a46b2a77f0644335a77 Mon Sep 17 00:00:00 2001 From: Oliver G Date: Mon, 16 Feb 2026 08:53:28 +0100 Subject: [PATCH] Add expanded GitHub wiki content and publish guide --- docs/WIKI_PUBLISH.md | 38 ++++++++++++ docs/wiki/API-Reference.md | 76 +++++++++++++++++++++++ docs/wiki/Admin-API.md | 40 ++++++++++++ docs/wiki/Data-Sources-and-Attribution.md | 24 +++++++ docs/wiki/Deployment.md | 31 +++++++++ docs/wiki/Home.md | 32 ++++++++++ docs/wiki/Operations-Runbook.md | 34 ++++++++++ docs/wiki/Roadmap-30-60-90.md | 27 ++++++++ 8 files changed, 302 insertions(+) create mode 100644 docs/WIKI_PUBLISH.md create mode 100644 docs/wiki/API-Reference.md create mode 100644 docs/wiki/Admin-API.md create mode 100644 docs/wiki/Data-Sources-and-Attribution.md create mode 100644 docs/wiki/Deployment.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations-Runbook.md create mode 100644 docs/wiki/Roadmap-30-60-90.md diff --git a/docs/WIKI_PUBLISH.md b/docs/WIKI_PUBLISH.md new file mode 100644 index 0000000..7c0b739 --- /dev/null +++ b/docs/WIKI_PUBLISH.md @@ -0,0 +1,38 @@ +# GitHub Wiki Publish + +Status: Wiki-Entwürfe liegen in `docs/wiki/`. + +## Voraussetzung + +In GitHub muss das Wiki im Repo aktiviert sein: + +- Repo `StaySense` -> `Settings` -> `Features` -> `Wikis` aktivieren + +Hinweis: Wenn deaktiviert, leitet `https://github.com/OliverGiertz/StaySense/wiki` nur auf das Repo zurück und `StaySense.wiki.git` ist nicht erreichbar. + +## Einmaliger Publish + +```bash +cd /tmp +rm -rf staysense-wiki-publish +mkdir -p staysense-wiki-publish +cd staysense-wiki-publish + +git init +cp -R /Users/oliver/StaySense/docs/wiki/. . +git add . +git commit -m "Initialize StaySense wiki" +git branch -M master +git remote add origin https://github.com/OliverGiertz/StaySense.wiki.git +git push -u origin master +``` + +## Update Publish (nach Änderungen) + +```bash +cd /tmp/staysense-wiki-publish +cp -R /Users/oliver/StaySense/docs/wiki/. . +git add . +git commit -m "Update wiki docs" +git push +``` diff --git a/docs/wiki/API-Reference.md b/docs/wiki/API-Reference.md new file mode 100644 index 0000000..014be16 --- /dev/null +++ b/docs/wiki/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). diff --git a/docs/wiki/Admin-API.md b/docs/wiki/Admin-API.md new file mode 100644 index 0000000..262b132 --- /dev/null +++ b/docs/wiki/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 ` + +## 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 " +``` diff --git a/docs/wiki/Data-Sources-and-Attribution.md b/docs/wiki/Data-Sources-and-Attribution.md new file mode 100644 index 0000000..065e9d8 --- /dev/null +++ b/docs/wiki/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` diff --git a/docs/wiki/Deployment.md b/docs/wiki/Deployment.md new file mode 100644 index 0000000..9bc9666 --- /dev/null +++ b/docs/wiki/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. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..92d0537 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,32 @@ +# 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` diff --git a/docs/wiki/Operations-Runbook.md b/docs/wiki/Operations-Runbook.md new file mode 100644 index 0000000..b40cc73 --- /dev/null +++ b/docs/wiki/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 +``` diff --git a/docs/wiki/Roadmap-30-60-90.md b/docs/wiki/Roadmap-30-60-90.md new file mode 100644 index 0000000..fa14f6b --- /dev/null +++ b/docs/wiki/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