Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 2bd1e1116c | |||
| 9ca06cad58 | |||
| 4f1a91eb13 |
@@ -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 `<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.
|
||||
|
||||
---
|
||||
|
||||
## 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 - <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
|
||||
|
||||
```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 <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"
|
||||
```bash
|
||||
go build -o releases/sportscore-linux-amd64 ./cmd/sportscore/...
|
||||
git add -A && git commit -m "Frontend: <Beschreibung>" && 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: <Beschreibung>" && 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.
|
||||
```
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"current_round": 1,
|
||||
"rounds": [],
|
||||
"red_score": 1,
|
||||
"green_score": 0
|
||||
}
|
||||
@@ -384,18 +384,12 @@
|
||||
initDom();
|
||||
showLoading(true);
|
||||
|
||||
// Event Listener
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
// Initialen State laden
|
||||
// DOM ist bereits vollständig geladen (Script am Ende von body)
|
||||
// Sofort loslegen
|
||||
poll().then(function () {
|
||||
// Sobald erster Poll erfolgreich war, Overlay ausblenden
|
||||
showLoading(false);
|
||||
});
|
||||
|
||||
// Polling starten
|
||||
startPolling();
|
||||
|
||||
// WebSocket versuchen (falls API WS unterstützt)
|
||||
connectWebSocket();
|
||||
|
||||
// Reset-Button
|
||||
@@ -441,14 +435,9 @@
|
||||
event.stopPropagation();
|
||||
postNext();
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// App starten
|
||||
if (document.readyState === 'loading') {
|
||||
document.addEventListener('DOMContentLoaded', init);
|
||||
} else {
|
||||
init();
|
||||
}
|
||||
|
||||
})();
|
||||
|
||||
Binary file not shown.
Binary file not shown.
Reference in New Issue
Block a user