30b862008a
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
211 lines
4.9 KiB
Markdown
211 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd server/backend
|
|
go build ./...
|
|
```
|
|
|
|
### Agent bauen
|
|
|
|
```bash
|
|
cd player/agent
|
|
go build ./...
|
|
```
|
|
|
|
### Alternativ ueber Makefile
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
MORZ_INFOBOARD_HTTP_ADDR=:18080 go run ./cmd/api
|
|
```
|
|
|
|
### Agent lokal starten
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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: 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
|
|
|
|
Ergaenzt seit dem ersten Geruest:
|
|
|
|
- `message_wall`-Resolver im Backend
|
|
- dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides
|
|
- strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown
|
|
- 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
|