segnapunti/README.md

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
• Guida utente
• Funzionalità
• Shortcuts tastiera
• Deploy con Docker
• Sviluppo
• 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

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

docker compose up -d

Lo stato viene salvato nel volume Docker segnapunti-state e sopravvive ai riavvii del container.

Aggiornamento a nuova versione

docker compose pull && docker compose up -d

Build e pubblicazione immagine

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

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:

npx playwright install chromium firefox

---

Changelog

Vedere CHANGELOG.md per la storia delle versioni.