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
This commit is contained in:
2026-07-14 18:21:11 +02:00
parent 9ca06cad58
commit 76f8b03dc4
2 changed files with 303 additions and 95 deletions
+297 -95
View File
@@ -1,57 +1,9 @@
# goSportpunktetafel – Projektstatus # goSportpunktetafel – Projekt-Guide
## Projekt-Info ## Was ist das?
- **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
--- 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.
## 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`
--- ---
@@ -59,61 +11,311 @@
``` ```
goSportpunktetafel/ goSportpunktetafel/
├── AGENTS.md ├── AGENTS.md ← Dieser Guide
├── go.mod ├── go.mod ← Go-Modul: git.jlserver.de/goSportpunktetafel
├── cmd/ ├── cmd/
│ └── sportscore/ │ └── sportscore/
│ └── main.go │ └── main.go ← Entry-Point: Flags, Init, Shutdown
├── internal/ ├── internal/
│ ├── config/ – Flag-Parsing, Konfiguration │ ├── config/ ← (noch nicht existiert, Flags in main.go)
│ ├── usb/ – USB-Tastatur-Handling │ ├── usb/ ← USB-Tastatur-Input (evdev, Linux)
│ ├── logik/ – Zählerlogik (Rot/Grün, Runden) │ │ ├── scancodes.go ← ScanCode → Key-Mapping (cross-platform)
│ ├── persistenz/ – Datei-basierte Persistenz │ │ ├── scancodes_test.go
│ ├── mdns/ – mDNS-Bekanntmachung & Discovery │ │ ├── usb.go ← Key-Struct (cross-platform)
│ └── httpapi/ – HTTP-API-Server, WebSocket, eingebettetes Frontend │ │ ├── usb_linux.go ← evdev-Implementierung (//go:build linux)
├── systemd/ – Systemd-Service-Datei │ │ └── usb_other.go ← Stub für Nicht-Linux (//go:build !linux)
├── docs/ – Dokumentation │ ├── logik/ ← Scoreboard-Logik
└── scripts/ – Hilfs-Scripts │ │ ├── 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 | ## Architektur
|-------|-------------|
| `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 | │ main.go (CLI-Flags: --port, --usb, --data, --host) │
| `data/state.json` | Persistenz-Datei (JSON) | │ │ │
│ ├─→ 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 ### 1. `embed.FS` braucht Rebuild
- **Rot** und **Grün** 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) ### 2. USB-Input ist Linux-spezifisch
| Taste | Aktion | - `usb_linux.go` (`//go:build linux`): Nutzt `evdev` (cgo, Linux-only)
|-------|--------| - `usb_other.go` (`//go:build !linux`): Stub, der `ErrUSBNotSupported` zurückgibt
| `/` | +1 Punkt bei Team Rot | - Windows-Cross-Compile: `CGO_ENABLED=0 GOOS=windows GOARCH=amd64`
| `*` | +1 Punkt bei Team Grün | - Linux-Local-Build: Einfach `go build` (CGO standardmäßig an)
| `+` | Nächste Runde (0:0) |
| `-` | Alle Runden löschen, zurück zu Runde 1 (0:0) |
### Frontend-Anforderungen ### 3. Frontend-Host ist dynamisch
- Dunkles Design `app.js` liest `window.location` aus – **kein hardcoded Host**.
- Vollbild auf großem Bildschirm Funktioniert also überall, wo die Seite eingebettet wird.
- Zentral: Score (Rot : Grün)
- Unten: Highscores der vorherigen Runden (komma-getrennt) ### 4. `DOMContentLoaded`-Race (bereits gefixt)
- Menü oben links: Backend-Auswahl Script steht am Ende von `<body>`. `DOMContentLoaded` war bereits gefeuert
- Lokal als `init()` lief. Deshalb wird jetzt **sofort** losgelegt, nicht per Listener.
- mDNS-Ergebnisse (aktualisierbar)
- Manuelle Server-Eingabe ### 5. Persistenz-Schreibstrategie
- Ausgewähltes Backend wird in lokaler Persistenz gespeichert 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 ## Wartung & Entwicklung
**Letztes Update:** 2026-07-14 16:30 CET
**Aktueller Meilenstein:** M7 abgeschlossen ✅ ### Voraussetzungen
**Nächster Schritt:** Frontend-Design verfeinern (Vollbild-UX, Animationen, responsive) - **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.
```
+6
View File
@@ -0,0 +1,6 @@
{
"current_round": 1,
"rounds": [],
"red_score": 1,
"green_score": 0
}