b04acdee09
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
79 lines
1.9 KiB
Markdown
79 lines
1.9 KiB
Markdown
# 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
|