# 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

```json
{
  "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:

```json
{
  "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.
Die Rueckgabe wird aktuell fuer Diagnosezwecke priorisiert sortiert: zuerst `offline`, dann `degraded`, dann `online`, innerhalb derselben Gruppe nach `screen_id`.

`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