diff --git a/AGENTS.md b/AGENTS.md index f271a20..9190066 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,57 +1,9 @@ -# goSportpunktetafel – Projektstatus +# goSportpunktetafel – Projekt-Guide -## Projekt-Info -- **Name:** goSportpunktetafel -- **Backend-Sprache:** Go -- **Git-Remote:** https://git.jlserver.de -- **Repository-URL:** https://git.jlserver.de/goSportpunktetafel.git (noch zu erstellen) -- **Go-Version:** 1.19.8 +## Was ist das? ---- - -## Meilensteine - -### ✅ M1: Projektstrukturierung und Planung -- [x] Projektverzeichnis erstellt -- [x] Alle notwendigen Verzeichnisse angelegt -- [x] AGENTS.md erstellt und wird fortlaufend aktualisiert -- [x] Repository auf git.jlserver.de erstellt und initialer Push durchgeführt -- [x] `go.mod` initialisiert - -### ✅ M2: Backend – USB-Tastatur-Handling -- [x] Tastatureingaben im Hintergrund auslesbar -- [x] Diagnostik und Log-Ausgabe über stderr -- [x] Systemd-Service-Beispieldatei -- [x] Dokumentation - -### ⏳ M3: Backend – Logik -- [ ] Zählerlogik implementiert -- [ ] Zustandsausgabe im Log -- [ ] Dokumentation - -### ⏳ M4: Backend – Persistenz -- [ ] Speicherung des aktuellen Zählerstands in Datei (Flag) -- [ ] Laden des Zustands beim Start (falls vorhanden) -- [ ] Dokumentation - -### ⏳ M5: Backend – mDNS -- [ ] HTTP-API über mDNS im Netzwerk bekannt machen -- [ ] Funktion zur Suche anderer Instanzen im Netzwerk - -### ✅ M6: Backend – HTTP-API-Schnittstelle -- [x] Flags für Listening-Port und -Adresse (Default: Port 3000, alle IPv6/IPv4) -- [x] `/api/...` – alle Steuer- und Statusfunktionen -- [x] Alle API-Endpunkte vor Commit auf Funktion geprüft (14 Tests) -- [x] Dokumentation - -### ✅ M7: Frontend -- [x] HTML, JS, CSS erstellt (dunkles Design, Vollbild, 2 Teams) -- [x] Plausibilitäts- und Funktionstest bestanden (17 Tests) -- [x] In Go-Binary integriert (embed.FS) -- [x] Unter `/` verfügbar -- [x] End-to-End-Test: Backend + Frontend gemeinsam -- [x] WebSocket-Endpoint `/ws` für Echtzeit-Updates -- [x] Persistenz-Datei: `state.json` +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. --- @@ -59,61 +11,311 @@ ``` goSportpunktetafel/ -├── AGENTS.md -├── go.mod +├── AGENTS.md ← Dieser Guide +├── go.mod ← Go-Modul: git.jlserver.de/goSportpunktetafel ├── cmd/ │ └── sportscore/ -│ └── main.go +│ └── main.go ← Entry-Point: Flags, Init, Shutdown ├── internal/ -│ ├── config/ – Flag-Parsing, Konfiguration -│ ├── usb/ – USB-Tastatur-Handling -│ ├── logik/ – Zählerlogik (Rot/Grün, Runden) -│ ├── persistenz/ – Datei-basierte Persistenz -│ ├── mdns/ – mDNS-Bekanntmachung & Discovery -│ └── httpapi/ – HTTP-API-Server, WebSocket, eingebettetes Frontend -├── systemd/ – Systemd-Service-Datei -├── docs/ – Dokumentation -└── scripts/ – Hilfs-Scripts +│ ├── 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 ``` -## Wichtige Dateien +--- -| Datei | Beschreibung | -|-------|-------------| -| `internal/httpapi/frontend.go` | Eingebettetes Frontend (embed.FS) | -| `internal/httpapi/static/` | Frontend-Dateien (index.html, style.css, app.js) | -| `internal/httpapi/websocket.go` | WebSocket-Handler für Echtzeit-Updates | -| `data/state.json` | Persistenz-Datei (JSON) | +## 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 │ +└─────────────────────────────────────────────────────┘ +``` --- -## Domänenlogik +## Besonderheiten & Fallstricke -### Teams -- **Rot** und **Grün** +### 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.** -### Tasten (USB-Tastatur) -| Taste | Aktion | -|-------|--------| -| `/` | +1 Punkt bei Team Rot | -| `*` | +1 Punkt bei Team Grün | -| `+` | Nächste Runde (0:0) | -| `-` | Alle Runden löschen, zurück zu Runde 1 (0:0) | +### 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) -### Frontend-Anforderungen -- Dunkles Design -- Vollbild auf großem Bildschirm -- Zentral: Score (Rot : Grün) -- Unten: Highscores der vorherigen Runden (komma-getrennt) -- Menü oben links: Backend-Auswahl - - Lokal - - mDNS-Ergebnisse (aktualisierbar) - - Manuelle Server-Eingabe -- Ausgewähltes Backend wird in lokaler Persistenz gespeichert +### 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. --- -## Aktueller Status -**Letztes Update:** 2026-07-14 16:30 CET -**Aktueller Meilenstein:** M7 abgeschlossen ✅ -**Nächster Schritt:** Frontend-Design verfeinern (Vollbild-UX, Animationen, responsive) +## 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 -