morz-infoboard/docs/PLAYER-STATUS-HTTP.md

Info-Board Neu - Erster HTTP-Statuspfad fuer den Player-Agent

Ziel

Dieses Dokument beschreibt den ersten bewusst kleinen Statuspfad zwischen player/agent und server/backend.

Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persistenz-, Authentifizierungs- oder MQTT-Modell.

V1-Dev-Entscheidung

• der Agent sendet zunaechst Statusdaten per HTTP an das Backend
• 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

• POST /api/v1/player/status

Request-Felder

Mindestens enthalten:

• screen_id
• ts
• status

Fuer die aktuelle Entwicklungsstufe sind zulaessig:

• status: starting, running, stopped
• server_connectivity: unknown, online, degraded, offline
• heartbeat_every_seconds: positive Ganzzahl

Aktuell zusaetzlich enthalten:

• server_connectivity
• server_url
• mqtt_broker
• heartbeat_every_seconds
• started_at
• last_heartbeat_at

Beispiel

{
  "screen_id": "info01-dev",
  "ts": "2026-03-22T16:00:00Z",
  "status": "running",
  "server_connectivity": "online",
  "server_url": "http://127.0.0.1:8080",
  "mqtt_broker": "tcp://127.0.0.1:1883",
  "heartbeat_every_seconds": 30,
  "started_at": "2026-03-22T15:59:30Z",
  "last_heartbeat_at": "2026-03-22T16:00:00Z"
}

Antwort

Bei gueltigem Request liefert das Backend aktuell:

{
  "status": "accepted"
}

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/status
• GET /api/v1/screens/{screenId}/status

GET /api/v1/screens/status liefert eine kleine Uebersicht aller bisher berichtenden Screens mit ihrem jeweils letzten bekannten Datensatz.

GET /api/v1/screens/{screenId}/status liefert den zuletzt akzeptierten Status fuer einen einzelnen Screen zurueck. Wenn fuer den Screen noch kein Status vorliegt, liefert das Backend 404 mit dem gemeinsamen Fehlerumschlag.

Der aktuell zurueckgelieferte Datensatz enthaelt damit sowohl den Lifecycle-Status (status) als auch den vom Agenten lokal abgeleiteten Reachability-Zustand (server_connectivity).

Zusaetzlich fuegt das Backend im Read-Pfad derzeit hinzu:

• received_at als serverseitigen Annahmezeitpunkt des letzten gueltigen Reports
• stale als einfache serverseitige Einordnung, ob der letzte Report bereits veraltet wirkt
• derived_state als zusammengefasste Diagnoseeinschaetzung fuer Konsumenten des Read-Pfads

stale ist aktuell bewusst nur eine kleine Diagnosehilfe fuer die Entwicklungsstufe und noch kein vollstaendiges Online-/Offline-Modell fuer spaetere Admin-Oberflaechen. Die Schwelle wird derzeit einfach aus dem gemeldeten heartbeat_every_seconds abgeleitet: mehr als zwei Intervalle ohne neuen Report gelten als veraltet.

derived_state wird aktuell bewusst einfach abgeleitet:

• offline bei stale = true oder server_connectivity = offline
• degraded bei server_connectivity = degraded|unknown oder wenn status nicht running ist
• online in den verbleibenden Faellen

Abgrenzung

Noch nicht Teil dieser Stufe:

• dauerhafte Speicherung in Datenbank oder State-Store
• Screen-Authentifizierung
• MQTT-Heartbeat oder MQTT-Status
• Admin-UI-Anzeige des letzten Status
• Retry-Queue oder lokale Zwischenspeicherung im Agent

Agent-seitig wird die Server-Erreichbarkeit aktuell lokal als unknown, online, degraded oder offline aus dem Erfolg der HTTP-Reports abgeleitet.

Fuer den transportierten Wert im erfolgreichen HTTP-Report gilt aktuell bewusst einfach:

• wenn ein Report vom Backend akzeptiert wurde, wird dieser Report selbst als server_connectivity = online gespeichert
• anhaltende Ausfaelle werden primaer ueber lokale Agent-Zustaende und serverseitige stale-Ableitung sichtbar

Folgeschritte

Auf diesem Pfad bauen spaeter auf:

• Screen-Identitaet und Authentifizierung
• persistierter letzter Heartbeat und letzter Status auf dem Server
• Trennung zwischen HTTP-Snapshot und MQTT-Heartbeat
• Admin-Vorschau fuer Online-/Offline- und Degraded-Zustaende