From f65f87722cdb1a7684cc89cf9d7b760188148c1c Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Sun, 21 Jun 2026 18:35:29 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20documenta=20la=20modalit=C3=A0=20time?= =?UTF-8?q?=20out=20e=20dettaglia=20tutte=20le=20funzioni?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: sezione Funzionalità riscritta per spiegare in modo completo display e controller (layout, punteggio/set, config, cambi, servizio, voce, time out/spot, reset/referto, regole partita e amichevole). - CLAUDE.md: descrizione di toggleTimeout, flag `timeout`, cartella `spot/`, endpoint `/spot/list` e nota sull'autoplay con audio in kiosk. --- CLAUDE.md | 4 ++- README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 74 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 637085d..9a04724 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,7 +46,9 @@ Punteggio, set e servizio si ricavano sempre dalla `striscia`: al primo punto di `src/referto.js` genera il referto di gara: `buildRefertoHtml(state, now)` è una funzione pura che restituisce l'HTML (testabile), mentre `generaReferto(state)` è il wrapper che apre la finestra con `window.open` e avvia la stampa. -`src/persist.js` carica/salva lo stato su `.segnapunti/state.json`. `src/server-utils.js` ricava gli IP di rete (`getNetworkIPs`, con sorgente iniettabile) e stampa gli URL all'avvio. +`src/persist.js` carica/salva lo stato su `.segnapunti/state.json`. `src/server-utils.js` ricava gli IP di rete (`getNetworkIPs`, con sorgente iniettabile) e stampa gli URL all'avvio. `src/spot-utils.js` espone `listSpotVideos(spotDir)`, che elenca i `.mp4` (ordinati) della cartella `spot/`; ritorna `[]` se la cartella manca. + +**Time out / spot video** — l'action `toggleTimeout` commuta il flag booleano `state.timeout`. Quando attivo, il display mostra a tutto schermo i video `.mp4` della cartella `spot/` nella root (non versionata): uno solo va in loop, più video girano in sequenza ripartendo dal primo; se la cartella è vuota mostra un overlay "TIME OUT". La lista è esposta dall'endpoint HTTP `/spot/list` (JSON) e i file sono serviti staticamente da `/spot/.mp4`, sia in produzione (`server.js`) sia in sviluppo (`vite-plugin-websocket.js`). I video partono con audio; se il browser blocca l'autoplay con suono si ripiega automaticamente su muto — per avere l'audio reale il browser del display (schermo senza input) va avviato in kiosk con autoplay consentito (es. Chrome `--autoplay-policy=no-user-gesture-required`). `server.js` (Express) espone `createApp(distDir)` (solo routing, testabile) e `startServer(port)` (HTTP + WebSocket); serve entrambe le interfacce sulla porta 3000: `/display` → `dist/index.html`, `/controller` → `dist/controller.html`. Singolo endpoint WebSocket su `/ws`. L'avvio automatico parte solo se il file è eseguito come entrypoint. diff --git a/README.md b/README.md index 4bc3e5f..3c13639 100644 --- a/README.md +++ b/README.md @@ -81,34 +81,88 @@ http://:3000/controller ## Funzionalità -### Display +Il sistema è composto da due interfacce complementari: il **display** è in sola lettura e mostra al pubblico lo stato della partita; il **controller** è il pannello operatore da cui parte ogni azione. Tutto ciò che l'operatore tocca sul controller si riflette istantaneamente sul display via WebSocket. -- 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) +### Display (tabellone pubblico) -### Controller +Pagina di sola visualizzazione, pensata per uno schermo grande o un proiettore. Mostra: -- **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) -- **Referto** — a fine partita, dal dialog *PARTITA FINITA*, genera un referto di gara stampabile/PDF (punteggi per set, formazioni di partenza, andamento punto-punto). *Funzione prototipale.* +- **Nomi squadre** con **indicatore di servizio** (l'icona della palla compare accanto alla squadra che sta servendo). +- **Punteggio del set corrente** in caratteri molto grandi, leggibili da lontano. +- **Contatore dei set vinti** per ciascuna squadra. +- **Striscia storica dei punti** del set in corso: una sequenza scorrevole che ricostruisce l'andamento punto su punto. +- **Modalità formazioni**: in alternativa al punteggio, mostra le posizioni dei 6 giocatori in campo (numeri di maglia disposti come a referto). +- **Ordine di visualizzazione invertibile**: le due squadre possono essere scambiate di lato per rispecchiare l'orientamento reale del campo. +- **Overlay time out / spot**: durante un time out copre il tabellone con i video della cartella `spot/` (vedi sotto). +- **Annuncio vocale del punteggio** (sintesi vocale del browser), comandato dal controller. +- **Indicatore di connessione**: scompare quando tutto è connesso, diventa un punto rosso lampeggiante con scritta *Disconnesso* in caso di problemi. +- **Fullscreen automatico** all'apertura sui dispositivi mobili. + +### Controller (pannello operatore) + +Il controller adatta automaticamente il proprio layout all'orientamento del dispositivo: + +- **Verticale (smartphone)** — layout compatto: anteprima punteggio toccabile in alto e griglia di pulsanti sotto. +- **Orizzontale (tablet)** — layout esteso "da regia": due grandi pannelli squadra affiancati con punteggio, campo e tasto set, più una barra di azioni in basso. + +#### Gestione del punteggio + +- **Punto** — tocca il punteggio/la card di una squadra per assegnarle `+1`. Il sistema gestisce automaticamente il **cambio palla** e la **rotazione** della squadra che riconquista il servizio. +- **Annulla punto** — rimuove l'ultimo punto assegnato, ripristinando anche eventuale rotazione e servizio. +- **Tasti SET** — incrementano manualmente il contatore dei set vinti di una squadra (utile per correzioni); il contatore cicla da 0. +- **Dialog automatico SET VINTO / PARTITA FINITA** — compare da solo al raggiungimento delle condizioni di vittoria (25 punti, o 15 nel set decisivo, con 2 di scarto). Da qui puoi: + - **VAI AL SET SUCCESSIVO** — chiude il set, lo registra come vinto e prepara il set successivo aprendo la configurazione delle formazioni; + - **INDIETRO** — annulla l'ultimo punto se il dialog è comparso per errore; + - a partita conclusa, **REFERTO** per generare il referto e **CHIUDI** per tornare al tabellone. + +#### Configurazione partita + +Dal pulsante **Config** si apre una finestra che permette di impostare: + +- **Nomi delle squadre** (Home e Guest); +- **Modalità partita**: `2/3` (al meglio dei 3 set), `3/5` (al meglio dei 5 set) o `Amichevole` (senza vittoria automatica della partita); +- **Formazioni iniziali**: i numeri di maglia dei 6 giocatori in campo per ciascuna squadra, disposti per zona. + +#### Cambi giocatore + +Il pulsante **Cambi** apre, dopo aver scelto la squadra, un dialog con righe `IN → OUT`. Le sostituzioni vengono **validate** prima di essere applicate: i numeri devono essere cifre, il giocatore entrante non può essere già in campo, quello uscente deve essere effettivamente in formazione, e nessuno può sostituire sé stesso. Eventuali errori sono segnalati in chiaro. + +#### Servizio e visualizzazione + +- **Cambio Palla** — assegna manualmente il servizio; disponibile **solo a 0-0** (a inizio set). +- **Inverti** — scambia il lato delle due squadre sul display. +- **Formazioni / Punteggio** — alterna sul display la vista formazioni in campo e la vista punteggio. +- **Striscia ON/OFF** — mostra o nasconde lo storico punti del set sul display. +- **Voce** — fa annunciare al display il punteggio corrente con la sintesi vocale (es. *"15 a 12"*, *"15 pari"*, *"zero a zero"*). + +#### Time Out e spot pubblicitari + +Il pulsante **Time Out** attiva/disattiva la proiezione degli spot sul display. Quando la modalità è attiva il controller resta **pienamente operativo** ma è chiaramente evidenziato: compare un banner *MODALITÀ TIME OUT ATTIVA* e il pulsante diventa arancione e pulsante. Ripremendolo si esce e il display torna al punteggio. + +I video da proiettare vanno messi in una cartella **`spot/`** nella root del progetto (non versionata). Comportamento: + +- **un solo** video `.mp4` → riprodotto in loop continuo; +- **più** video `.mp4` → riprodotti in sequenza in ordine alfabetico, poi si riparte dal primo; +- **cartella vuota o assente** → il display mostra un overlay nero con la scritta *TIME OUT*. + +> **Audio:** i video partono con audio, ma il display è in genere uno schermo senza tastiera/mouse e i browser bloccano l'autoplay con suono senza un'interazione dell'utente. In assenza di configurazione il video parte automaticamente **muto** (il video si vede comunque). Per avere l'audio, avvia il browser del display in modalità kiosk consentendo l'autoplay con suono (es. Chrome con `--autoplay-policy=no-user-gesture-required`, oppure impostando un'eccezione del sito per audio/video). + +#### Reset e referto + +- **Reset** — azzera la partita (punteggi, set e formazioni) previa conferma, e riapre subito la configurazione per impostare la partita successiva. +- **Referto** — a fine partita, dal dialog *PARTITA FINITA*, genera un referto di gara stampabile/PDF con i punteggi per set, le formazioni di partenza e l'andamento punto-punto. *Funzione prototipale.* ### Regole pallavolo integrate +Le condizioni di vittoria del set sono applicate automaticamente dal server (è quello che fa comparire il dialog *SET VINTO*): + | 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 | +La **partita** è vinta da chi raggiunge 3 set su 5 (modalità `3/5`) o 2 set su 3 (modalità `2/3`). In modalità **Amichevole** non c'è vittoria automatica della partita: si continua a giocare set senza che compaia *PARTITA FINITA*. + ---