Jesko Anschütz 2c780d3e60 Dokumentiere Statusspeicherung und Connectivity-Zustaende

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-03-22 18:22:31 +01:00

2.3 KiB

Raw Blame History

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

Aktuell zusaetzlich enthalten:

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_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/{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:

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 oder degraded aus dem Erfolg der HTTP-Reports abgeleitet.

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

2.3 KiB Raw Blame History