diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e1cd748..79948b0 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -186,8 +186,8 @@ go run ./cmd/agent 1. Backend: einheitliches Fehlerformat und Routing-Grundstruktur anlegen 2. Backend: Konfigurations- und App-Lifecycle stabilisieren -3. Agent und Backend: den ersten HTTP-Statuspfad um persistierte Speicherung und Screen-Identitaet erweitern -4. Agent: danach Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen +3. Agent und Backend: den HTTP-Statuspfad als Grundlage fuer Identitaet, Persistenz und spaetere Admin-Vorschau erweitern +4. Agent: danach einen expliziten `offline`-Zustand und weitere Connectivity-Schwellenlogik aufsetzen 5. Danach die Netzwerk-, Sync- und Kommandopfade schrittweise produktionsnah ausbauen Ergaenzt seit dem ersten Geruest: @@ -195,9 +195,11 @@ Ergaenzt seit dem ersten Geruest: - `message_wall`-Resolver im Backend - Basisendpunkte und `message_wall`-Validierung im Backend testseitig breiter abgedeckt - erster `POST /api/v1/player/status`-Endpunkt im Backend +- letzter bekannter Player-Status wird im Backend pro Screen in-memory vorgehalten und lesbar gemacht - dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides - strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown - erster periodischer HTTP-Status-Reporter im Agent +- Server-Connectivity-Zustand im Agent (`unknown`, `online`, `degraded`) auf Basis der Report-Ergebnisse - lokales Compose-Grundgeruest fuer PostgreSQL und Mosquitto ## Arbeitsweise diff --git a/docs/PLAYER-AGENT-LIFECYCLE.md b/docs/PLAYER-AGENT-LIFECYCLE.md index fb5d52b..5bbef03 100644 --- a/docs/PLAYER-AGENT-LIFECYCLE.md +++ b/docs/PLAYER-AGENT-LIFECYCLE.md @@ -10,6 +10,7 @@ Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierte - der Agent fuehrt zunaechst ein internes Health-Modell ohne externen HTTP-Endpunkt - Lifecycle-Wechsel werden ueber einen in-memory Snapshot verfolgt +- Server-Erreichbarkeit wird getrennt vom Lifecycle als eigener Connectivity-Zustand gefuehrt - Logs werden als stabile `key=value`-Ereignisse ausgegeben - Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM` @@ -18,6 +19,7 @@ Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierte Der Laufzeitsnapshot enthaelt mindestens: - `status` +- `server_connectivity` - `screen_id` - `server_base_url` - `mqtt_broker` @@ -38,6 +40,17 @@ Fuer die aktuelle Ausbaustufe gelten diese Stati: Ein separater Fehlerstatus wird in dieser Stufe noch nicht eingefuehrt. Technische Startfehler bleiben weiterhin normale Rueckgabefehler beim Initialisieren oder Starten. +## Connectivity-Modell + +Getrennt vom Lifecycle fuehrt der Agent fuer die Server-Erreichbarkeit aktuell diese Zustaende: + +- `unknown` vor dem ersten erfolgreichen oder fehlgeschlagenen Status-Report +- `online` nach einem erfolgreich bestaetigten HTTP-Status-Report +- `degraded` nach einem fehlgeschlagenen HTTP-Status-Report + +Damit bleibt der Lifecycle sauber von Netz- und Gegenstellenproblemen getrennt. +Ein Report-Fehler stoppt den Agenten nicht, sondern veraendert nur den Connectivity-Zustand. + ## Strukturierte Log-Ereignisse Der Agent emittiert in v1 mindestens diese Ereignisse: @@ -45,6 +58,8 @@ Der Agent emittiert in v1 mindestens diese Ereignisse: - `event=agent_starting` - `event=agent_configured` - `event=heartbeat_tick` +- `event=status_report_sent` +- `event=status_report_failed` - `event=agent_stopped` Ziel ist keine vollstaendige Logging-Plattform, sondern ein stabiler, maschinenlesbarer Anfang fuer lokale Verifikation, spaetere Journald-Auswertung und Device-Debugging. @@ -69,8 +84,10 @@ Nicht Teil dieser Stufe: - externer Health-Endpunkt - MQTT-Verbindungsstatus -- Backend-Reachability-Pruefung - Snapshot-Persistenz - Kommandos oder Sync-Status +Die erste Backend-Reachability-Pruefung ist in dieser Stufe bereits ueber den HTTP-Status-Report abgebildet. +Ein expliziter `offline`-Zustand, MQTT-Reachability und weitergehende Schwellenlogik folgen spaeter. + Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird. diff --git a/docs/PLAYER-STATUS-HTTP.md b/docs/PLAYER-STATUS-HTTP.md index e29f06f..9bbb525 100644 --- a/docs/PLAYER-STATUS-HTTP.md +++ b/docs/PLAYER-STATUS-HTTP.md @@ -9,7 +9,7 @@ Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persist ## V1-Dev-Entscheidung - der Agent sendet zunaechst Statusdaten per HTTP an das Backend -- das Backend validiert und bestaetigt den Request, speichert ihn in dieser Stufe aber noch nicht dauerhaft +- das Backend validiert und bestaetigt den Request und haelt den letzten bekannten Status pro Screen in-memory vor - der Pfad dient als erste echte Backend-Agent-Integration vor Registration, Sync und MQTT ## Endpoint @@ -59,6 +59,15 @@ Bei gueltigem Request liefert das Backend aktuell: Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet. +## Aktueller Read-Pfad + +Zusätzlich zur Write-Route gibt es in dieser Stufe: + +- `GET /api/v1/screens/{screenId}/status` + +Dieser Endpunkt liefert den zuletzt akzeptierten Status fuer einen Screen zurueck. +Wenn fuer den Screen noch kein Status vorliegt, liefert das Backend `404` mit dem gemeinsamen Fehlerumschlag. + ## Abgrenzung Noch nicht Teil dieser Stufe: @@ -69,6 +78,8 @@ Noch nicht Teil dieser Stufe: - Admin-UI-Anzeige des letzten Status - Retry-Queue oder lokale Zwischenspeicherung im Agent +Agent-seitig wird die Server-Erreichbarkeit aktuell lokal als `unknown`, `online` oder `degraded` aus dem Erfolg der HTTP-Reports abgeleitet. + ## Folgeschritte Auf diesem Pfad bauen spaeter auf: