Files
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

322 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
```