From 2bd1e1116c91b67feec9b1fbb2983e0479e054c4 Mon Sep 17 00:00:00 2001 From: Hermes Bot Date: Tue, 14 Jul 2026 18:21:11 +0200 Subject: [PATCH] =?UTF-8?q?AGENTS.md:=20Kompletter=20Projekt-Guide=20f?= =?UTF-8?q?=C3=BCr=20Agenten?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- AGENTS.md | 392 ++++++++++++++++++++++++++++++++++++------------ data/state.json | 6 + 2 files changed, 303 insertions(+), 95 deletions(-) create mode 100644 data/state.json 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 - " +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. +``` diff --git a/data/state.json b/data/state.json new file mode 100644 index 0000000..5d1eb92 --- /dev/null +++ b/data/state.json @@ -0,0 +1,6 @@ +{ + "current_round": 1, + "rounds": [], + "red_score": 1, + "green_score": 0 +} \ No newline at end of file