diff --git a/API-MQTT-VERTRAG.md b/API-MQTT-VERTRAG.md index e79175f..4694342 100644 --- a/API-MQTT-VERTRAG.md +++ b/API-MQTT-VERTRAG.md @@ -163,6 +163,17 @@ Beispiel-Endpunkte: - `POST /api/v1/player/status` - `POST /api/v1/player/snapshot` +## Aktuelle Entwicklungsstufe + +Bevor das volle Player-Sync- und MQTT-Modell umgesetzt ist, existiert fuer die Entwicklung bereits ein bewusst kleiner HTTP-Statuspfad. + +Aktuell gilt: + +- `POST /api/v1/player/status` ist der erste reale Backend-Agent-Pfad +- die Payload enthaelt zunaechst Health- und Laufzeitdaten aus dem Agenten +- das Backend validiert den Request und bestaetigt ihn mit `status=accepted` +- Persistenz, Authentifizierung und die spaetere Trennung zwischen HTTP-Status und MQTT-Heartbeat folgen in spaeteren Schritten + ### 7. Admin-Kommandos Zweck: diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5f5cd28..d85ba7a 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -184,15 +184,18 @@ go run ./cmd/agent 1. Backend: einheitliches Fehlerformat und Routing-Grundstruktur anlegen 2. Backend: Konfigurations- und App-Lifecycle stabilisieren -3. Agent: MQTT-, API- und Sync-Bausteine auf Basis des Health-Modells vorbereiten -4. Agent: spaeter Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen -5. Danach die Netzwerk- und Kommandopfade schrittweise produktionsnah ausbauen +3. Agent und Backend: den ersten HTTP-Statuspfad um persistierte Speicherung und Screen-Identitaet erweitern +4. Agent: danach Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen +5. Danach die Netzwerk-, Sync- und Kommandopfade schrittweise produktionsnah ausbauen Ergaenzt seit dem ersten Geruest: - `message_wall`-Resolver im Backend +- Basisendpunkte und `message_wall`-Validierung im Backend testseitig breiter abgedeckt +- erster `POST /api/v1/player/status`-Endpunkt im Backend - dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides - strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown +- erster periodischer HTTP-Status-Reporter im Agent - lokales Compose-Grundgeruest fuer PostgreSQL und Mosquitto ## Arbeitsweise diff --git a/README.md b/README.md index 0462fde..5d161d5 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit: - Template-/Kampagnenkonzept: `docs/TEMPLATE-KONZEPT.md` - `layout_json` fuer `message_wall`: `docs/LAYOUT-JSON.md` - Player-Agent-Lifecycle und Health-Modell: `docs/PLAYER-AGENT-LIFECYCLE.md` +- Erster HTTP-Statuspfad fuer den Player-Agent: `docs/PLAYER-STATUS-HTTP.md` - Provisionierungskonzept: `docs/PROVISIONIERUNGSKONZEPT.md` - Player-Konzept: `docs/PLAYER-KONZEPT.md` - Server-Konzept: `docs/SERVER-KONZEPT.md` @@ -37,8 +38,8 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit: ## Aktueller Implementierungsstand -- `server/backend/` enthaelt ein lauffaehiges Go-Grundgeruest mit erster Tool-API fuer `message_wall` -- `player/agent/` enthaelt ein Go-Grundgeruest mit dateibasierter/env-basierter Konfiguration, strukturierten Logs und internem Health-Modell +- `server/backend/` enthaelt ein lauffaehiges Go-Grundgeruest mit erster Tool-API fuer `message_wall` und einem ersten `player/status`-Endpunkt +- `player/agent/` enthaelt ein Go-Grundgeruest mit dateibasierter/env-basierter Konfiguration, strukturierten Logs, internem Health-Modell und erstem HTTP-Status-Reporter - `compose/` enthaelt ein lokales Grundgeruest fuer PostgreSQL und Mosquitto - `ansible/` enthaelt erste Platzhalter fuer Inventory und Playbook-Struktur diff --git a/docs/PLAYER-STATUS-HTTP.md b/docs/PLAYER-STATUS-HTTP.md new file mode 100644 index 0000000..e29f06f --- /dev/null +++ b/docs/PLAYER-STATUS-HTTP.md @@ -0,0 +1,79 @@ +# 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