From 4bfc12fb00cbe22ce0e9b87130dbf05527a6f8ea Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 12 May 2026 14:46:35 +0200 Subject: [PATCH] docs(readme): riscrive documentazione con guida utente e architettura 2.0.0 --- README.md | 333 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 183 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index fd2a453..8ad76f2 100644 --- a/README.md +++ b/README.md @@ -1,213 +1,246 @@ # Segnapunti Anto -Applicazione web **fullstack real-time** per il tracciamento dei punteggi di partite di pallavolo, installabile come PWA. +![Version](https://img.shields.io/badge/versione-2.0.0-blue) +![Node](https://img.shields.io/badge/node-%3E%3D18-green) +![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white) +![License](https://img.shields.io/badge/licenza-privata-lightgrey) + +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. --- -## Panoramica +## Indice -**Segnapunti Anto** è un'applicazione fullstack per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone in contesto sportivo. +- [Architettura](#architettura) +- [Guida utente](#guida-utente) +- [Funzionalità](#funzionalità) +- [Shortcuts tastiera](#shortcuts-tastiera) +- [Terminal Controller CLI](#terminal-controller-cli) +- [Deploy con Docker](#deploy-con-docker) +- [Sviluppo](#sviluppo) +- [Test](#test) -### Architettura +--- -Il sistema è composto da un **backend Node.js/Express** e due interfacce web separate: +## Architettura -| Interfaccia | Porta | Ruolo | -|-------------|-------|-------| -| **Display** | 3000 | Tabellone pubblico — mostra punteggi, formazioni e storico | -| **Controller** | 3001 | Pannello operatore — invia azioni e gestisce la partita | +``` +Controller (smartphone) ──WebSocket──┐ +Display (schermo) ──WebSocket──┤── Server Node.js ── gameState.js +CLI (terminale) ──WebSocket──┘ │ + └── .segnapunti/state.json +``` -Le due interfacce comunicano tramite **WebSocket** (`/ws`): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi. +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. -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. +| Percorso | Ruolo | +|---|---| +| `http://:3000/display` | Tabellone pubblico — sola lettura | +| `http://:3000/controller` | Pannello operatore — gestione partita | +| `ws://:3000/ws` | WebSocket endpoint | -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. +--- + +## 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://: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://:3000/controller +``` + +> **Installazione come app:** nel browser tocca *"Aggiungi a schermata Home"* per avere il controller come icona dedicata. --- ## 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 +### 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 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/3` o `3/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) +| 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 | --- -## Requisiti +## Shortcuts tastiera -### Ambiente di sviluppo +> Valide sul controller da browser desktop. -| Requisito | Versione minima | Consigliata | -|-----------|-----------------|-------------| -| **Node.js** | `>= 18.19.0` | `24 LTS` | -| **npm** | `>= 9` | — | -| **RAM** | 2 GB | 4 GB | -| **OS** | Linux, macOS, Windows | — | +| 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 | -### Test E2E +--- -I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive. +## Terminal Controller CLI + +Alternativa al controller browser, utile da terminale. ```bash -npx playwright install chromium firefox -# Linux (con dipendenze di sistema): -# npx playwright install --with-deps chromium firefox +npm run cli # server su porta 3000 +npm run cli:dev # dev server su porta 5173 +node cli.js # porta custom ``` -### Requisiti browser (utente finale) +| Comando | Alias | Effetto | +|---|---|---| +| `punto casa` | `+`, `pc` | Punto alla squadra di casa | +| `punto ospite` | `-`, `po` | Punto alla squadra ospite | +| `undo` | `u` | Annulla l'ultimo punto | +| `set casa` / `set ospite` | — | Incrementa contatore set | +| `serv` | — | Cambia servizio (solo a 0-0) | +| `nomi ` | — | Imposta i nomi delle squadre | +| `modalita 2/3` / `3/5` | — | Modalità partita | +| `reset` | — | Azzera la partita (chiede conferma) | +| `stato` | — | Mostra punteggio nel terminale | +| `help` | — | Lista comandi | +| `exit` | `q` | Chiude il CLI | -| 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). +`Tab` per completamento automatico — `↑ ↓` per navigare nella history dei comandi. --- -## Installazione +## Deploy con Docker + +### Prima installazione ```bash -git clone https://santantonio.sytes.net/attilio/segnapunti.git -cd segnapunti -npm install +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 -### Dev server +### Requisiti -```bash -npm run dev -``` - -Avvia il server Vite con hot reload: -- `http://localhost:5173/` — Display -- `http://localhost:5173/controller.html` — Controller - -### Build di produzione - -```bash -npm run build -``` - -Genera la cartella `dist/` con asset ottimizzati, manifest e service worker PWA. - -### Avvio in produzione (locale) - -```bash -npm run serve -``` - -Espone i due server: -- `http://localhost:3000` — Display -- `http://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. +| Strumento | Versione minima | +|---|---| +| Node.js | >= 18 | +| npm | >= 9 | ### Avvio ```bash -# 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 +npm install +npm run dev ``` -Il CLI richiede che il server sia già in esecuzione in un altro terminale. +| 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 -#### 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 ` | 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 +| 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 | +| `npm run cli` | Terminal controller (porta 3000) | +| `npm run cli:dev` | Terminal controller (porta 5173) | --- ## Test -La suite di test copre tutti i livelli dell'applicazione: +| 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 | -| 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`](tests/README.md). +> I test E2E richiedono il server in esecuzione (`npm run serve`) e i browser Playwright installati: +> ```bash +> npx playwright install chromium firefox +> ``` --- -## Docker +## Changelog -```bash -docker-compose up --build -``` - -Espone le porte `3000` (Display) e `3001` (Controller). +Vedere [CHANGELOG.md](CHANGELOG.md) per la storia delle versioni.