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

Beispiel:

MORZ_INFOBOARD_HTTP_ADDR=:18080 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

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