Files
goSportpunktetafel/AGENTS.md
T
hermes 2bd1e1116c AGENTS.md: Kompletter Projekt-Guide für Agenten
- 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
2026-07-14 18:21:11 +02:00

11 KiB
Raw Permalink Blame History

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 <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

  1. Dateien editieren: internal/httpapi/static/
  2. Neuen Build machen (embed.FS!)
  3. 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 Changes
  • MINOR = 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.PATCH fü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.