az/morz-infoboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
morz-infoboard/DEVELOPMENT.md

4.7 KiB
Raw Blame History

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

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

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: dateibasierte Konfiguration zusaetzlich zu Env vorbereiten
  4. Agent: strukturierte Logs und Health-Modell einziehen
  5. Danach erst DB-, MQTT- und API-Funktionalitaet ausbauen

Ergaenzt seit dem ersten Geruest:

  • message_wall-Resolver im Backend
  • dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides
  • 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