# 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, speichert ihn in dieser Stufe aber noch nicht dauerhaft
- 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

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

```json
{
  "status": "accepted"
}
```

Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet.

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

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