216 lines
5.8 KiB
Markdown
216 lines
5.8 KiB
Markdown
# Segnapunti
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Segnapunti digitale in tempo reale per partite di pallavolo. Un server centrale gestisce lo stato della partita; un **display** mostra il tabellone pubblico e un **controller** (smartphone o tablet) permette all'operatore di gestire punti, formazioni e cambi.
|
||
|
||
---
|
||
|
||
## Indice
|
||
|
||
- [Architettura](#architettura)
|
||
- [Guida utente](#guida-utente)
|
||
- [Funzionalità](#funzionalità)
|
||
- [Shortcuts tastiera](#shortcuts-tastiera)
|
||
- [Deploy con Docker](#deploy-con-docker)
|
||
- [Sviluppo](#sviluppo)
|
||
- [Test](#test)
|
||
|
||
---
|
||
|
||
## Architettura
|
||
|
||
```
|
||
Controller (smartphone) ──WebSocket──┐
|
||
├── Server Node.js ── gameState.js
|
||
Display (schermo) ──WebSocket──┘ │
|
||
└── .segnapunti/state.json
|
||
```
|
||
|
||
Il server è l'unica fonte di verità. Ogni azione del controller viene elaborata e trasmessa in broadcast a tutti i client connessi. Lo stato viene salvato su disco ad ogni azione e ricaricato all'avvio, sopravvivendo ai riavvii del server.
|
||
|
||
| Percorso | Ruolo |
|
||
|---|---|
|
||
| `http://<host>:3000/display` | Tabellone pubblico — sola lettura |
|
||
| `http://<host>:3000/controller` | Pannello operatore — gestione partita |
|
||
| `ws://<host>:3000/ws` | WebSocket endpoint |
|
||
|
||
---
|
||
|
||
## Guida utente
|
||
|
||
### Scenario tipico: schermo fisso + smartphone operatore
|
||
|
||
#### 1. Avvia il server
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
All'avvio il terminale mostra gli URL locali e di rete.
|
||
|
||
#### 2. Apri il display
|
||
|
||
Collega il PC/server allo schermo via HDMI e apri il browser a schermo intero:
|
||
|
||
```
|
||
http://localhost:3000/display
|
||
```
|
||
|
||
Se il display è su un dispositivo separato nella stessa rete:
|
||
|
||
```
|
||
http://<IP-del-server>:3000/display
|
||
```
|
||
|
||
> **Trovare l'IP:** il server lo stampa all'avvio. In alternativa usa `ip a` su Linux.
|
||
|
||
#### 3. Apri il controller sullo smartphone
|
||
|
||
Connetti il telefono alla stessa rete Wi-Fi e apri:
|
||
|
||
```
|
||
http://<IP-del-server>:3000/controller
|
||
```
|
||
|
||
> **Installazione come app:** nel browser tocca *"Aggiungi a schermata Home"* per avere il controller come icona dedicata.
|
||
|
||
---
|
||
|
||
## Funzionalità
|
||
|
||
### Display
|
||
|
||
- Nomi squadre con indicatore di servizio
|
||
- Punteggio del set corrente (grande, leggibile da lontano)
|
||
- Contatore set vinti
|
||
- Striscia storica punti del set in corso, scorrevole verso destra
|
||
- Modalità formazioni: posizioni dei 6 giocatori in campo
|
||
- Indicatore connessione WebSocket (scompare quando connesso, rosso lampeggiante se disconnesso)
|
||
|
||
### Controller
|
||
|
||
- **Punti** — `+1` per casa e ospite, con annullamento dell'ultimo punto
|
||
- **Dialog set vinto** — appare automaticamente al raggiungimento dei 25 punti (o 15 nel tie-break); permette di confermare il set o annullare l'ultimo punto
|
||
- **Formazioni** — configura i numeri di maglia; la rotazione avviene automaticamente al cambio palla
|
||
- **Cambi** — dialog `IN → OUT` con validazione
|
||
- **Servizio** — cambio manuale (disponibile solo a 0-0)
|
||
- **Visualizzazione** — alterna tra punteggio grande e formazioni in campo
|
||
- **Striscia** — mostra/nasconde lo storico punti sul display
|
||
- **Reset** — azzera la partita (richiede conferma)
|
||
|
||
### Regole pallavolo integrate
|
||
|
||
| Set | Condizione di vittoria |
|
||
|---|---|
|
||
| Set 1–4 (modalità 3/5) o 1–2 (modalità 2/3) | Primo a **25** con almeno 2 punti di scarto |
|
||
| Set decisivo (tie-break) | Primo a **15** con almeno 2 punti di scarto |
|
||
|
||
---
|
||
|
||
## Shortcuts tastiera
|
||
|
||
> Valide sul controller da browser desktop.
|
||
|
||
| Tasto | Azione |
|
||
|---|---|
|
||
| `Ctrl + ↑` | Punto casa |
|
||
| `Ctrl + ↓` | Annulla ultimo punto |
|
||
| `Shift + ↑` | Punto ospite |
|
||
| `Ctrl + ←` | Cambia servizio (solo a 0-0) |
|
||
| `Ctrl + M` | Apri configurazione |
|
||
| `Ctrl + C` | Cambi squadra casa |
|
||
| `Shift + C` | Cambi squadra ospite |
|
||
| `Ctrl + Z` | Toggle punteggio / formazioni |
|
||
| `Ctrl + S` | Annuncio vocale punteggio |
|
||
| `Ctrl + B` | Mostra/nascondi barra pulsanti |
|
||
| `Ctrl + F` | Fullscreen |
|
||
|
||
---
|
||
|
||
## Deploy con Docker
|
||
|
||
### Prima installazione
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
Lo stato viene salvato nel volume Docker `segnapunti-state` e sopravvive ai riavvii del container.
|
||
|
||
### Aggiornamento a nuova versione
|
||
|
||
```bash
|
||
docker compose pull && docker compose up -d
|
||
```
|
||
|
||
### Build e pubblicazione immagine
|
||
|
||
```bash
|
||
docker build \
|
||
-t santantonio.sytes.net/attilio/segnapunti:2.0.0 \
|
||
-t santantonio.sytes.net/attilio/segnapunti:latest .
|
||
|
||
docker push santantonio.sytes.net/attilio/segnapunti:2.0.0
|
||
docker push santantonio.sytes.net/attilio/segnapunti:latest
|
||
```
|
||
|
||
---
|
||
|
||
## Sviluppo
|
||
|
||
### Requisiti
|
||
|
||
| Strumento | Versione minima |
|
||
|---|---|
|
||
| Node.js | >= 18 |
|
||
| npm | >= 9 |
|
||
|
||
### Avvio
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
| URL | Interfaccia |
|
||
|---|---|
|
||
| `http://localhost:5173/display` | Display |
|
||
| `http://localhost:5173/controller` | Controller |
|
||
|
||
Lo stato viene salvato in `.segnapunti/state.json` anche in modalità dev.
|
||
|
||
### Comandi disponibili
|
||
|
||
| Comando | Descrizione |
|
||
|---|---|
|
||
| `npm run dev` | Dev server con hot reload |
|
||
| `npm run build` | Build di produzione in `dist/` |
|
||
| `npm run serve` | Build + avvio server produzione |
|
||
|
||
---
|
||
|
||
## Test
|
||
|
||
| Comando | Descrizione |
|
||
|---|---|
|
||
| `npm run test:unit` | Unit + integration (Vitest) |
|
||
| `npm run test:component` | Componenti Vue (Happy-DOM) |
|
||
| `npm run test:stress` | Load test WebSocket (50+ client) |
|
||
| `npm run test:all` | Tutti i test tranne E2E |
|
||
| `npm run test:e2e` | Playwright — Chromium, Firefox, Mobile Chrome |
|
||
|
||
> I test E2E richiedono il server in esecuzione (`npm run serve`) e i browser Playwright installati:
|
||
> ```bash
|
||
> npx playwright install chromium firefox
|
||
> ```
|
||
|
||
---
|
||
|
||
## Changelog
|
||
|
||
Vedere [CHANGELOG.md](CHANGELOG.md) per la storia delle versioni.
|