# 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 - " 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 Changes - `MINOR` = Neue Features (abwärtskompatibel) - `PATCH` = Bugfixes --- ## systemd-Service ```bash # 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) ```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 ` - **Globale Git-Config verwenden**, keine lokalen Overrides! - **Commits:** Beschreibende Messages, Feature-Blöcke pro Commit - **Tags:** `vMAJOR.MINOR.PATCH` für Releases --- ## Quick-Reference: Häufige Tasks ### "Frontend-Änderung deployed" ```bash go build -o releases/sportscore-linux-amd64 ./cmd/sportscore/... git add -A && git commit -m "Frontend: " && git push ``` ### "Binaries neu bauen" ```bash 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" ```bash # 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: " && git push ``` ### "Persistenz-Datei manuell editieren" ```bash # Struktur der JSON-Datei: cat data/sportscore.json # { # "red_score": 0, "green_score": 0, # "current_round": 1, "rounds": [] # } # Direkt editieren, Server liest beim Restart. ```