Davide Grilli
606b2c1ee6
Nuovo script cli.js che si connette al server via WebSocket come controller e permette di gestire la partita da terminale con comandi testuali, colori ANSI, tab-completion e history dei comandi. Aggiunge script npm "cli" / "cli:dev" e documenta tutti i comandi nel README
Segnapunti Anto
Applicazione web fullstack real-time per il tracciamento dei punteggi di partite di pallavolo, installabile come PWA.
Panoramica
Segnapunti Anto è un'applicazione fullstack per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone in contesto sportivo.
Architettura
Il sistema è composto da un backend Node.js/Express e due interfacce web separate:
| Interfaccia | Porta | Ruolo |
|---|---|---|
| Display | 3000 | Tabellone pubblico — mostra punteggi, formazioni e storico |
| Controller | 3001 | Pannello operatore — invia azioni e gestisce la partita |
Le due interfacce comunicano tramite WebSocket (/ws): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi.
La logica di gioco risiede interamente lato server (gameState.js), con aggiornamenti di stato immutabili. Il frontend Vue 3 è puramente reattivo: riceve lo stato e lo visualizza senza gestirne la consistenza.
In produzione, entrambi i server sono gestiti da un unico processo Node.js (server.js) e l'intera applicazione è containerizzabile via Docker. Il frontend è installabile come PWA (service worker, manifest, modalità fullscreen landscape) per utilizzo kiosk su dispositivi sportivi.
Funzionalità
Gestione partita in tempo reale
- Tracciamento punti home/guest con indicatore di servizio
- Gestione set e storico punti (striscia)
- Blocco azioni quando il set è già vinto
Regole pallavolo integrate
- Set normali: vittoria a 25 con almeno 2 punti di scarto
- Set decisivo (5° set): vittoria a 15 con almeno 2 punti di scarto
- Modalità partita
2/3o3/5
Formazioni e cambi
- Gestione formazione a 6 giocatori per squadra
- Rotazione automatica al cambio palla
- Dialog cambi con validazione
IN → OUT
Controlli e personalizzazione
- Configurazione nomi squadre
- Inversione ordine di visualizzazione squadre
- Toggle punteggio/formazioni e visibilità striscia storico
- Sintesi vocale del punteggio (Web Speech API)
Requisiti
Ambiente di sviluppo
| Requisito | Versione minima | Consigliata |
|---|---|---|
| Node.js | >= 18.19.0 |
24 LTS |
| npm | >= 9 |
— |
| RAM | 2 GB | 4 GB |
| OS | Linux, macOS, Windows | — |
Test E2E
I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive.
npx playwright install chromium firefox
# Linux (con dipendenze di sistema):
# npx playwright install --with-deps chromium firefox
Requisiti browser (utente finale)
| API | Utilizzo | Necessità |
|---|---|---|
| JavaScript ES6+ | Moduli, async/await | Obbligatorio |
| WebSocket | Sincronizzazione stato live | Obbligatorio |
| Service Worker | Supporto PWA offline | Consigliato |
| Web Speech API | Annunci vocali punteggio | Opzionale |
Browser testati: Chrome/Chromium, Firefox, Mobile Chrome (Playwright Pixel 5).
Installazione
git clone https://santantonio.sytes.net/attilio/segnapunti.git
cd segnapunti
npm install
Sviluppo
Dev server
npm run dev
Avvia il server Vite con hot reload:
http://localhost:5173/— Displayhttp://localhost:5173/controller.html— Controller
Build di produzione
npm run build
Genera la cartella dist/ con asset ottimizzati, manifest e service worker PWA.
Avvio in produzione (locale)
npm run serve
Espone i due server:
http://localhost:3000— Displayhttp://localhost:3001— Controller
Terminal Controller (CLI)
Il CLI è un controller da terminale che si connette al server via WebSocket e permette di gestire la partita senza browser.
Avvio
# Modalità produzione (server su porta 3000)
npm run cli
# Modalità sviluppo (server Vite su porta 5173)
npm run cli:dev
# Porta custom
node cli.js <porta>
Il CLI richiede che il server sia già in esecuzione in un altro terminale.
Comandi disponibili
Punteggio
| Comando | Alias | Effetto |
|---|---|---|
punto casa |
+, pc |
Assegna un punto alla squadra di casa |
punto ospite |
-, po |
Assegna un punto alla squadra ospite |
undo |
u |
Annulla l'ultimo punto assegnato |
Set
| Comando | Effetto |
|---|---|
set casa |
Incrementa il contatore set della squadra di casa |
set ospite |
Incrementa il contatore set della squadra ospite |
Partita
| Comando | Effetto |
|---|---|
serv |
Cambia il servizio (disponibile solo se il punteggio è 0-0) |
reset |
Resetta la partita — chiede conferma prima di procedere |
nomi <casa> <ospite> |
Imposta i nomi delle squadre (es. nomi Antoniana Teate) |
modalita 2/3 |
Imposta la modalità best-of-3 |
modalita 3/5 |
Imposta la modalità best-of-5 |
Informazioni
| Comando | Alias | Effetto |
|---|---|---|
stato |
— | Mostra il punteggio corrente nel terminale |
help |
— | Mostra la lista dei comandi |
exit |
q |
Chiude il CLI |
Note
- Tab: completamento automatico dei comandi
- Freccia su/giù: navigazione nella history dei comandi (ultime 100 voci)
- Il Display nel browser si aggiorna in tempo reale ad ogni comando inviato
Test
La suite di test copre tutti i livelli dell'applicazione:
| Suite | Comando | Descrizione |
|---|---|---|
| Tutti | npm run test:all |
Unit + integration + component + stress |
| Unit + integration | npm run test:unit |
Logica di gioco e WebSocket |
| Component | npm run test:component |
Componenti Vue |
| Stress | npm run test:stress |
Load test WebSocket |
| E2E | npm run test:e2e |
Playwright (chromium, firefox, mobile) |
Per la guida completa ai test, consultare tests/README.md.
Docker
docker-compose up --build
Espone le porte 3000 (Display) e 3001 (Controller).