2bd1e1116c
- 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
322 lines
11 KiB
Markdown
322 lines
11 KiB
Markdown
# 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)
|
||
|
||
```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.
|
||
```
|