diff --git a/README.md b/README.md index 2b9e9c6..c806df7 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,90 @@ # Segnapunti Anto -Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di partite di pallavolo in tempo reale. +Applicazione web **fullstack real-time** per il tracciamento dei punteggi di partite di pallavolo, installabile come PWA. --- ## Panoramica -**Segnapunti Anto** e un'applicazione digitale per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone. +**Segnapunti Anto** è un'applicazione fullstack per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone in contesto sportivo. -L'app e composta da due interfacce: -- **Display** (tabellone pubblico) -- **Controller** (pannello operatore) +### Architettura -Le due interfacce condividono lo stato in tempo reale tramite WebSocket. +Il sistema è composto da un **backend Node.js/Express** e due interfacce web separate: -### Funzionalita Principali +| Interfaccia | Porta | Ruolo | +|-------------|-------|-------| +| **Display** | 3000 | Tabellone pubblico — mostra punteggi, formazioni e storico | +| **Controller** | 3001 | Pannello operatore — invia azioni e gestisce la partita | -- **Gestione partita in tempo reale** - - Tracciamento punti home/guest - - Gestione set - - Indicatore servizio - - Storico punti (striscia) - - Blocchi logici quando il set e gia vinto +Le due interfacce comunicano tramite **WebSocket** (`/ws`): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi. -- **Regole pallavolo integrate** - - Set normali: vittoria a 25 con almeno 2 punti di scarto - - Set decisivo: vittoria a 15 con almeno 2 punti di scarto - - Modalita partita `2/3` o `3/5` +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. -- **Formazioni e cambi** - - Gestione formazione a 6 giocatori - - Rotazione automatica al cambio palla - - Dialog cambi con validazioni (`IN -> OUT`) +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. -- **Controlli e personalizzazione** - - Configurazione nomi squadre - - Toggle ordine squadre (inverti) - - Toggle visualizzazione punteggio/formazioni - - Toggle striscia storico - - Sintesi vocale punteggio (Web Speech API) +--- + +## 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/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) --- ## Requisiti -### Requisiti di Sistema +### Ambiente di sviluppo -#### Per Sviluppo -- **Sistema Operativo**: Linux, macOS, Windows -- **Node.js**: `>= 18.19.0` (consigliato `20 LTS`) -- **npm**: `>= 9` -- **RAM**: minimo 2GB (consigliato 4GB) +| Requisito | Versione minima | Consigliata | +|-----------|-----------------|-------------| +| **Node.js** | `>= 18.19.0` | `24 LTS` | +| **npm** | `>= 9` | — | +| **RAM** | 2 GB | 4 GB | +| **OS** | Linux, macOS, Windows | — | -#### Per Esecuzione Test E2E -- Browser Playwright installati (`chromium`, `firefox`) -- Su Linux, eventuali dipendenze sistema per browser headless +### Test E2E -Comandi utili: +I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive. ```bash -node -v -npm -v npx playwright install chromium firefox -# Linux, se necessario: +# Linux (con dipendenze di sistema): # npx playwright install --with-deps chromium firefox ``` -### Requisiti Browser (Utente Finale) +### Requisiti browser (utente finale) -| Requisito | Dettaglio | Necessita | -|-----------|-----------|-----------| +| API | Utilizzo | Necessità | +|-----|----------|-----------| | JavaScript ES6+ | Moduli, async/await | Obbligatorio | | WebSocket | Sincronizzazione stato live | Obbligatorio | -| Service Worker API | Supporto PWA offline | Consigliato | -| Web Speech API | Annunci vocali | Opzionale | +| Service Worker | Supporto PWA offline | Consigliato | +| Web Speech API | Annunci vocali punteggio | Opzionale | -### Browser Testati e Supportati - -| Browser | Supporto | Note | -|---------|----------|------| -| Chrome/Chromium | ✅ | Completo | -| Firefox | ✅ | Completo | -| Mobile Chrome (Playwright Pixel 5) | ✅ | Copertura E2E mobile | +**Browser testati:** Chrome/Chromium, Firefox, Mobile Chrome (Playwright Pixel 5). --- -## Installazione e Setup - -### Prerequisiti - -- Node.js `>= 18.19.0` -- npm `>= 9` - -### Installazione +## Installazione ```bash git clone https://santantonio.sytes.net/attilio/segnapunti.git @@ -102,107 +94,58 @@ npm install --- -## Comandi per Sviluppo +## Sviluppo -### Dev Server - -Avvia il server di sviluppo Vite: +### Dev server ```bash npm run dev ``` -Accesso tipico in sviluppo: -- `http://localhost:5173/` -> Display -- `http://localhost:5173/controller.html` -> Controller +Avvia il server Vite con hot reload: +- `http://localhost:5173/` — Display +- `http://localhost:5173/controller.html` — Controller -### Modalita Sviluppo -- Hot reload attivo -- Build veloce lato Vite -- Buona per sviluppo UI/UX - ---- - -## Comandi per Build - -### Build Produzione +### Build di produzione ```bash npm run build ``` -Output: -- cartella `dist/` -- asset ottimizzati -- file PWA (manifest + service worker) +Genera la cartella `dist/` con asset ottimizzati, manifest e service worker PWA. -### Avvio Server Applicativo Locale (Display + Controller) +### Avvio in produzione (locale) ```bash npm run serve ``` -Espone: -- `http://localhost:3000` -> Display -- `http://localhost:3001` -> Controller +Espone i due server: +- `http://localhost:3000` — Display +- `http://localhost:3001` — Controller -### Altri comandi utili +--- + +## 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`](tests/README.md). + +--- + +## Docker ```bash -npm run preview -npm run start +docker-compose up --build ``` ---- - -## Configurazione PWA - -L'app usa `vite-plugin-pwa` (vedi `vite.config.js`) con: -- `registerType: 'autoUpdate'` -- manifest installabile -- orientamento landscape -- modalita fullscreen - -Caratteristiche principali: -- installabile su dispositivi supportati -- aggiornamento automatico del service worker -- supporto utilizzo offline (in base alle risorse cache) - ---- - -## Logica Regolamentare Pallavolo - -### Vittoria Set - -- Set normali: vittoria a 25 con almeno 2 punti di scarto -- Set decisivo: vittoria a 15 con almeno 2 punti di scarto -- Modalita partita supportate: `2/3` e `3/5` - -### Rotazione Formazione - -La rotazione avviene durante i cambi palla secondo la logica implementata in `src/gameState.js`. - -### Formazione in Campo - -Il sistema gestisce 6 posizioni per squadra e permette cambi validati da Controller. - ---- - -## Test (stato attuale) - -Suite presenti: -- Unit -- Integration -- Component -- Stress -- E2E (Playwright) - -Comandi principali: - -```bash -npm run test:all -npm run test:e2e -``` - -Guida completa test: -- `tests/README.md` +Espone le porte `3000` (Display) e `3001` (Controller).