# 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`): Nutzt `evdev` (cgo, Linux-only) - `usb_other.go` (`//go:build !linux`): Stub, der `ErrUSBNotSupported` zurü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 `
`. `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) ```bash 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 1. Dateien editieren: `internal/httpapi/static/` 2. Neuen Build machen (embed.FS!) 3. Testen ### Tests hinzufügen ```bash # Bestimmtes Paket testen go test ./internal/logik/... # Mit Coverage go test -cover ./... # Alle Tests go test ./... ``` --- ## Releases bauen ### Schritt-für-Schritt ```bash 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 -