morz-infoboard/DEVELOPMENT.md

Info-Board Neu - Entwicklung

Ziel

Dieses Dokument soll den Einstieg auf einem anderen Entwicklungsrechner moeglichst reibungsfrei machen.

Es beschreibt:

• minimale Voraussetzungen
• wichtige Verzeichnisse
• Build- und Run-Kommandos
• aktuelle Annahmen fuer den lokalen Entwicklungsbetrieb

Repository

• Remote: git.az-it.net:az/morz-infoboard.git
• Standard-Branch: main

Projektwurzel:

• /srv/docker/info-board-neu

Wichtige Verzeichnisse

• docs/ fuer Architektur- und Fachkonzepte
• server/backend/ fuer das zentrale Go-Backend
• player/agent/ fuer den Go-basierten Player-Agent
• player/ui/ spaeter fuer die lokale Player-Oberflaeche
• ansible/ spaeter fuer Deployment und Provisionierung
• compose/ spaeter fuer den zentralen Server-Stack

Aktueller Entwicklungsstand

Bereits vorhanden:

• fachliche Architektur- und Betriebskonzepte
• relationaler Schema-Entwurf in docs/SCHEMA.md
• erstes Go-Geruest fuer server/backend
• erstes Go-Geruest fuer player/agent

Noch nicht vorhanden:

• produktive API-Endpunkte
• Datenbankanbindung
• MQTT-Anbindung
• Player-Sync
• Player-UI
• Compose-Stack fuer lokale Serverdienste

Voraussetzungen auf dem Entwicklungsrechner

Mindestens empfohlen:

• git
• go in Version 1.24.x
• make

Spaeter zusaetzlich sinnvoll:

• docker und docker compose
• postgresql-client
• mosquitto-clients
• golangci-lint

Fuer Container-Builds liegen erste Dockerfiles in:

• server/backend/Dockerfile
• player/agent/Dockerfile

Schnellstart

Repository klonen:

git clone git.az-it.net:az/morz-infoboard.git
cd morz-infoboard

Dokumentationsbasis lesen:

1. README.md
2. PLAN.md
3. TECH-STACK.md
4. docs/SCHEMA.md
5. docs/OFFENE-ARCHITEKTURFRAGEN.md
6. docs/LAYOUT-JSON.md

Build-Kommandos

Backend bauen

cd server/backend
go build ./...

Agent bauen

cd player/agent
go build ./...

Alternativ ueber Makefile

make build

Aktuell bedeutet das:

• make build baut Backend und Agent
• make build-backend baut nur server/backend
• make build-agent baut nur player/agent
• make run-backend startet das Backend
• make run-agent startet den Agenten
• make fmt formatiert beide Go-Module
• make lint prueft beide Go-Module mit golangci-lint

Hinweis:

• auf dem aktuellen System dieser Session sind make und go nicht installiert; die Befehle sind fuer den Entwicklungsrechner vorbereitet

Lokaler Start

Backend lokal starten

cd server/backend
go run ./cmd/api

Standard:

• HTTP-Adresse: :8080
• Health-Endpunkt: GET /healthz
• Basis-Endpunkt: GET /api/v1

Konfigurierbar ueber:

• MORZ_INFOBOARD_HTTP_ADDR – HTTP-Adresse (Standard: :8080)
• MORZ_INFOBOARD_STATUS_STORE_PATH – Pfad zur JSON-Datei fuer persistenten Status-Store; leer lassen fuer reinen In-Memory-Betrieb

Beispiele:

MORZ_INFOBOARD_HTTP_ADDR=:18080 go run ./cmd/api

MORZ_INFOBOARD_HTTP_ADDR=:8080 \
MORZ_INFOBOARD_STATUS_STORE_PATH=/tmp/screen-status.json \
go run ./cmd/api

Agent lokal starten

cd player/agent
go run ./cmd/agent

Standardwerte:

• MORZ_INFOBOARD_SCREEN_ID=unset-screen
• MORZ_INFOBOARD_SERVER_URL=http://127.0.0.1:8080
• MORZ_INFOBOARD_MQTT_BROKER=tcp://127.0.0.1:1883

Optional dateibasiert:

• MORZ_INFOBOARD_CONFIG=/etc/signage/config.json

Eine Beispielkonfiguration liegt in player/config/config.example.json.

Beispiel:

MORZ_INFOBOARD_SCREEN_ID=info01-dev \
MORZ_INFOBOARD_SERVER_URL=http://127.0.0.1:8080 \
MORZ_INFOBOARD_MQTT_BROKER=tcp://127.0.0.1:1883 \
go run ./cmd/agent

Aktuelle Architekturentscheidungen mit direkter Auswirkung auf Entwicklung

• message_wall wird serverseitig in konkrete Screen-Szenen aufgeloest
• Kampagnengruppen werden serverseitig in konkrete Screen-Assignments expandiert
• playlist_items haben im finalen Implementierungsschema keinen direkten screen_id-Fremdschluessel
• Provisionierung wird worker-/jumphost-faehig geplant
• API-Fehler sollen einen einheitlichen Fehlerumschlag nutzen

Empfohlene naechste Implementierungsschritte

1. Backend: einheitliches Fehlerformat und Routing-Grundstruktur anlegen
2. Backend: Konfigurations- und App-Lifecycle stabilisieren
3. Agent und Backend: den HTTP-Statuspfad als Grundlage fuer Identitaet, Persistenz und spaetere Admin-Vorschau erweitern
4. Agent: danach MQTT-spezifische Reachability und feinere Connectivity-Schwellenlogik aufsetzen
5. Danach die Netzwerk-, Sync- und Kommandopfade schrittweise produktionsnah ausbauen

End-to-End-Entwicklungstest (Backend + Agent)

Backend und Agent koennen lokal gegeneinander laufen. Reihenfolge:

1. Backend starten (Terminal 1):

cd server/backend
MORZ_INFOBOARD_STATUS_STORE_PATH=/tmp/screen-status.json go run ./cmd/api

2. Agent starten (Terminal 2):

cd player/agent
MORZ_INFOBOARD_SCREEN_ID=info01-dev \
MORZ_INFOBOARD_SERVER_URL=http://127.0.0.1:8080 \
go run ./cmd/agent

3. Status pruefen:

# JSON-Uebersicht
curl http://127.0.0.1:8080/api/v1/screens/status

# HTML-Diagnoseseite
open http://127.0.0.1:8080/status

# Einzelner Screen
curl http://127.0.0.1:8080/api/v1/screens/info01-dev/status

# Screen loeschen
curl -X DELETE http://127.0.0.1:8080/api/v1/screens/info01-dev/status

Die Datei /tmp/screen-status.json enthaelt nach dem ersten Heartbeat den persistierten Status-Store.

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
• letzter bekannter Player-Status wird im Backend pro Screen in-memory vorgehalten und lesbar gemacht
• Backend ergaenzt den Read-Pfad um received_at und eine einfache stale-Ableitung
• Backend bietet zusaetzlich eine kleine Uebersicht aller zuletzt meldenden Screens
• Backend validiert den Statuspfad jetzt enger auf erlaubte Lifecycle-/Connectivity-Werte und leitet stale aus dem gemeldeten Intervall ab
• Backend leitet im Read-Pfad zusaetzlich ein kompaktes derived_state fuer Diagnosekonsumenten ab
• Backend liefert unter /status eine erste sichtbare HTML-Diagnoseseite auf Basis derselben Statusdaten, inklusive Auto-Refresh, leichten Filtern und JSON-Drill-down
• Backend unterstuetzt q= (Screen-ID-Substring), derived_state=, server_connectivity=, stale=, updated_since=, limit= als Query-Filter
• Backend leitet derived_state (online / degraded / offline) aus stale, server_connectivity und status ab
• Backend erlaubt das Loeschen einzelner Screen-Eintraege via DELETE /api/v1/screens/{screenId}/status
• Backend persistiert den Status-Store optional in einer JSON-Datei (MORZ_INFOBOARD_STATUS_STORE_PATH)
• dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides
• strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown
• erster periodischer HTTP-Status-Reporter im Agent
• Server-Connectivity-Zustand im Agent (unknown, online, degraded, offline) auf Basis der Report-Ergebnisse
• der HTTP-Statuspfad transportiert jetzt neben status auch server_connectivity
• lokales Compose-Grundgeruest fuer PostgreSQL und Mosquitto

Arbeitsweise

Empfohlen:

• kleine, klar umrissene Commits
• zuerst Konzepte anpassen, dann Code
• Schema und API-Vertrag synchron halten
• neue Fachentscheidungen immer in docs/ dokumentieren

Hinweise fuer einen zweiten Entwicklungsrechner

• vor Arbeitsbeginn git pull --rebase oder gleichwertig den aktuellen Stand holen
• bei paralleler Arbeit zuerst in den Dokumenten pruefen, ob neue Architekturentscheidungen getroffen wurden
• falls lokale Tools abweichen, mindestens go version und make --version pruefen