# 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_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.

`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

`stale` ist aktuell bewusst nur eine kleine Diagnosehilfe fuer die Entwicklungsstufe und noch kein vollstaendiges Online-/Offline-Modell fuer spaetere Admin-Oberflaechen.

## 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