- Projektstruktur (vollständig mit build tags) - Architektur-Diagramm - Besonderheiten & Fallstricke (embed.FS, USB, DOMContentLoaded, etc.) - Wartung & Entwicklung (local dev, tests, frontend changes) - Release-Build Schritt-für-Schritt (CLI + curl Befehle) - systemd-Service Installation - API-Referenz mit JSON-Beispielen - Quick-Reference für häufige Tasks
11 KiB
goSportpunktetafel – Projekt-Guide
Was ist das?
Eine digitale Punktetafel für Wettkämpfe mit zwei Teams (Rot/Grün). Backend in Go, Frontend als embedded Single-Page-App mit Echtzeit-Updates via WebSocket.
Projektstruktur
goSportpunktetafel/
├── AGENTS.md ← Dieser Guide
├── go.mod ← Go-Modul: git.jlserver.de/goSportpunktetafel
├── cmd/
│ └── sportscore/
│ └── main.go ← Entry-Point: Flags, Init, Shutdown
├── internal/
│ ├── config/ ← (noch nicht existiert, Flags in main.go)
│ ├── usb/ ← USB-Tastatur-Input (evdev, Linux)
│ │ ├── scancodes.go ← ScanCode → Key-Mapping (cross-platform)
│ │ ├── scancodes_test.go
│ │ ├── usb.go ← Key-Struct (cross-platform)
│ │ ├── usb_linux.go ← evdev-Implementierung (//go:build linux)
│ │ └── usb_other.go ← Stub für Nicht-Linux (//go:build !linux)
│ ├── logik/ ← Scoreboard-Logik
│ │ ├── logik.go ← Score, Runden, Reset
│ │ └── logik_test.go
│ ├── persistenz/ ← JSON-Dateispeicher
│ │ ├── persistenz.go ← Load/Save
│ │ └── persistenz_test.go
│ ├── mdns/ ← mDNS Service Discovery
│ │ ├── mdns.go ← zeroconf: announce + browse
│ │ └── mdns_test.go
│ └── httpapi/ ← HTTP-Server, WebSocket, Frontend
│ ├── httpapi.go ← HTTP-Router, API-Endpunkte, Flag-Parsing
│ ├── httpapi_test.go
│ ├── websocket.go ← WebSocket-Upgrade + Broadcast
│ ├── frontend.go ← embed.FS für static/
│ └── static/
│ ├── index.html ← Frontend HTML (dunkles Design, Vollbild)
│ ├── style.css ← CSS (Grid-Layout, Team-Farben)
│ └── app.js ← JS (polling + WebSocket, Team-Panel-Klicks)
├── releases/ ← Build-Artefakte (nicht im Git tracked?)
│ ├── sportscore-linux-amd64 ← ELF 64-bit (CGO, dynamisch)
│ └── sportscore-windows-amd64.exe ← PE32+ (CGO=0, statisch)
├── systemd/
│ └── sportscore.service ← systemd Unit für Produktion
├── docs/
│ └── usb.md ← USB-Dokumentation
├── data/ ← Runtime-Daten (Persistenz-JSON)
│ └── sportscore.json
└── test/ ← Test-Hilfsverzeichnisse
Architektur
┌─────────────────────────────────────────────────────┐
│ main.go (CLI-Flags: --port, --usb, --data, --host) │
│ │ │
│ ├─→ USB Input (Linux evdev, Hintergrund-Goroutine) │
│ │ └─→ Key → ScanToAction → Logik │
│ │ │
│ ├─→ HTTP Server (:3000) │
│ │ ├─ GET / → embed.FS Frontend │
│ │ ├─ GET /api/state → JSON State │
│ │ ├─ POST /api/score?team=red|green → +1 Point │
│ │ ├─ POST /api/next → Nächste Runde │
│ │ ├─ POST /api/reset → Alles zurücksetzen │
│ │ └─ GET /ws → WebSocket (Echtzeit) │
│ │ │
│ ├─→ Logik (Scoreboard-Engine) │
│ │ ├─ Teams: Rot, Grün │
│ │ ├─ Runden-Management │
│ │ └─ Events: Score, Next, Reset │
│ │ │
│ ├─→ Persistenz (JSON, --data Verzeichnis) │
│ │ ├─ Wird nach JEDEM State-Change geschrieben │
│ │ └─ Wird beim Start geladen │
│ │ │
│ └─→ mDNS (zeroconf) │
│ └─ Bekommt im Netzwerk bekannt gemacht │
└─────────────────────────────────────────────────────┘
Besonderheiten & Fallstricke
1. embed.FS braucht Rebuild
Alle Frontend-Dateien (index.html, style.css, app.js) werden beim Go-Build
in die Binary eingebettet. Änderungen am Frontend erfordern einen neuen Build.
2. USB-Input ist Linux-spezifisch
usb_linux.go(//go:build linux): Nutztevdev(cgo, Linux-only)usb_other.go(//go:build !linux): Stub, derErrUSBNotSupportedzurückgibt- Windows-Cross-Compile:
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 - Linux-Local-Build: Einfach
go build(CGO standardmäßig an)
3. Frontend-Host ist dynamisch
app.js liest window.location aus – kein hardcoded Host.
Funktioniert also überall, wo die Seite eingebettet wird.
4. DOMContentLoaded-Race (bereits gefixt)
Script steht am Ende von <body>. DOMContentLoaded war bereits gefeuert
als init() lief. Deshalb wird jetzt sofort losgelegt, nicht per Listener.
5. Persistenz-Schreibstrategie
Nach jedem API-Call (score, next, reset) wird direkt in die JSON-Datei geschrieben. Kein Batch-Writing, kein Caching.
6. mDNS-Service-Name
sportscore._sportscore._tcp.local. – kann in mdns.go geändert werden.
Wartung & Entwicklung
Voraussetzungen
- Go 1.19+ (getestet mit 1.19.8)
- Linux: Für USB-Input (evdev)
- Windows: Cross-Compile möglich, USB-Stub
Local Development (Linux)
cd /home/johann/goSportpunktetafel
# Alle Tests
go test ./...
# Binary bauen (mit USB, dynamisch gelinkt)
go build -o /tmp/sportscore ./cmd/sportscore/...
# Server starten
/tmp/sportscore --port 3000 --usb=false --data ./data
# Frontend aufrufen: http://localhost:3000/
Frontend-Änderungen
- Dateien editieren:
internal/httpapi/static/ - Neuen Build machen (embed.FS!)
- Testen
Tests hinzufügen
# Bestimmtes Paket testen
go test ./internal/logik/...
# Mit Coverage
go test -cover ./...
# Alle Tests
go test ./...
Releases bauen
Schritt-für-Schritt
cd /home/johann/goSportpunktetafel
# 1. Tests sicherstellen
go test ./...
# 2. Linux-Build (mit CGO, dynamisch)
go build -o releases/sportscore-linux-amd64 ./cmd/sportscore/...
# 3. Windows-Build (cross-compile, CGO=0)
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 \
go build -o releases/sportscore-windows-amd64.exe ./cmd/sportscore/...
# 4. Binaries prüfen
file releases/*
# 5. Commit + Push
git add -A
git commit -m "Rebuild: vX.Y.Z Binaries"
git push origin master
# 6. Neues Git-Tag (SemVer)
git tag -a vX.Y.Z -m "Release vX.Y.Z - <Beschreibung>"
git push origin vX.Y.Z
# 7. Release auf Gitea erstellen
curl -X POST "https://git.jlserver.de/api/v1/repos/JLtec/goSportpunktetafel/releases" \
-H "Authorization: token EURE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tag_name": "vX.Y.Z",
"name": "Release vX.Y.Z",
"body": "Beschreibung...",
"make_latest": true
}'
# 8. Binaries als Assets hochladen
curl -X POST "https://git.jlserver.de/api/v1/repos/JLtec/goSportpunktetafel/releases/ID/assets?name=sportscore-linux-amd64" \
-H "Authorization: token EURE_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @releases/sportscore-linux-amd64
curl -X POST "https://git.jlserver.de/api/v1/repos/JLtec/goSportpunktetafel/releases/ID/assets?name=sportscore-windows-amd64.exe" \
-H "Authorization: token EURE_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @releases/sportscore-windows-amd64.exe
Tag-Struktur
v0.1.0– Erste Release- SemVer:
vMAJOR.MINOR.PATCH MAJOR= Breaking ChangesMINOR= Neue Features (abwärtskompatibel)PATCH= Bugfixes
systemd-Service
# Service installieren
sudo cp systemd/sportscore.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sportscore
# Status prüfen
sudo systemctl status sportscore
# Logs lesen
sudo journalctl -u sportscore -f
Config-Datei: /etc/default/sportscore (wird vom Service geladen)
API-Referenz
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | / |
Frontend (HTML) |
| GET | /ws |
WebSocket-Echtzeit-Updates |
| GET | /api/state |
JSON: Score, Runde, History |
| POST | /api/score |
?team=red|green → +1 |
| POST | /api/next → Nächste Runde (Reset aktuelles Score) |
|
| POST | /api/reset |
Alles zurücksetzen |
State-Response (JSON)
{
"red_score": 5,
"green_score": 3,
"current_round": 2,
"rounds": [
{"red": 5, "green": 2},
{"red": 3, "green": 4}
]
}
WebSocket-Messages
Jeder State-Change wird als JSON an alle WebSocket-Clients broadcasted.
Git-Konvention
- Remote:
https://git.jlserver.de/JLtec/goSportpunktetafel.git - Branch:
master(Main) - Git-Autor:
Hermes Bot <noreply.hermes@jlserver.de> - Globale Git-Config verwenden, keine lokalen Overrides!
- Commits: Beschreibende Messages, Feature-Blöcke pro Commit
- Tags:
vMAJOR.MINOR.PATCHfür Releases
Quick-Reference: Häufige Tasks
"Frontend-Änderung deployed"
go build -o releases/sportscore-linux-amd64 ./cmd/sportscore/...
git add -A && git commit -m "Frontend: <Beschreibung>" && git push
"Binaries neu bauen"
go build -o releases/sportscore-linux-amd64 ./cmd/sportscore/...
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o releases/sportscore-windows-amd64.exe ./cmd/sportscore/...
"Neuer Meilenstein / Feature"
# 1. Code schreiben
# 2. Tests schreiben/erweitern
# 3. Tests laufen lassen
go test ./...
# 4. Build prüfen
go build ./cmd/sportscore/...
# 5. Commit + Push
git add -A && git commit -m "Mx: <Beschreibung>" && git push
"Persistenz-Datei manuell editieren"
# Struktur der JSON-Datei:
cat data/sportscore.json
# {
# "red_score": 0, "green_score": 0,
# "current_round": 1, "rounds": []
# }
# Direkt editieren, Server liest beim Restart.