From aa88e2b7a1d72b898507180fc3fc3aaf756d808a Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 12 Feb 2026 19:44:17 +0100 Subject: [PATCH] Aggiorna README.md --- README.md | 275 ++++++++++++++++++++++-------------------------------- 1 file changed, 114 insertions(+), 161 deletions(-) diff --git a/README.md b/README.md index bcc23d1..2b9e9c6 100644 --- a/README.md +++ b/README.md @@ -6,34 +6,39 @@ Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di parti ## Panoramica -**Segnapunti Anto** è un'applicazione digitale per il tracciamento dei punteggi durante partite di pallavolo, ottimizzata per l'uso su tablet e smartphone. Sviluppata per il team Antoniana, l'app fornisce un'interfaccia fullscreen touch-friendly con supporto offline e controlli da tastiera. +**Segnapunti Anto** e un'applicazione digitale per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone. -### Funzionalità Principali +L'app e composta da due interfacce: +- **Display** (tabellone pubblico) +- **Controller** (pannello operatore) -- **Gestione Completa Partite** - - Tracciamento punti in tempo reale per entrambe le squadre - - Conteggio automatico dei set (modalità 2/3 o 3/5) - - Indicatore visivo del servizio - - Blocco incremento punti a set concluso - - Cronologia punti con striscia visiva +Le due interfacce condividono lo stato in tempo reale tramite WebSocket. -- **Formazioni Squadra** - - Visualizzazione interattiva dei 6 giocatori in campo - - Rotazione automatica regolamentare al cambio palla - - Configurazione manuale dei numeri di maglia - - Dialog cambi con uno o due cambi (IN → OUT) e validazioni - - Supporto logica pallavolo ufficiale (25 punti + 2 di vantaggio, tie-break a 15 nel set decisivo) +### Funzionalita Principali -- **Controlli Multimodali** - - Scorciatoie da tastiera complete (vedi sezione [Shortcuts](#shortcuts)) - - Sintesi vocale per annunci punteggio in italiano (Web Speech API) +- **Gestione partita in tempo reale** + - Tracciamento punti home/guest + - Gestione set + - Indicatore servizio + - Storico punti (striscia) + - Blocchi logici quando il set e gia vinto -- **Personalizzazione** - - Configurazione dinamica nomi squadre - - Selettore modalità partita: al meglio di 3 o al meglio di 5 - - Toggle layout orizzontale (inverti home/guest) - - Modalità visualizzazione: punteggio semplice o formazioni complete - - Nascondi/mostra controlli e cronologia +- **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` + +- **Formazioni e cambi** + - Gestione formazione a 6 giocatori + - Rotazione automatica al cambio palla + - Dialog cambi con validazioni (`IN -> OUT`) + +- **Controlli e personalizzazione** + - Configurazione nomi squadre + - Toggle ordine squadre (inverti) + - Toggle visualizzazione punteggio/formazioni + - Toggle striscia storico + - Sintesi vocale punteggio (Web Speech API) --- @@ -42,33 +47,41 @@ Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di parti ### Requisiti di Sistema #### Per Sviluppo -- **Sistema Operativo**: Linux, macOS, Windows (WSL2 consigliato) -- **Node.js**: v20.2.0 o superiore (LTS consigliato) -- **npm**: v9.0.0 o superiore (incluso con Node.js) -- **RAM**: Minimo 2GB, consigliato 4GB -- **Spazio Disco**: ~500MB per dipendenze e build +- **Sistema Operativo**: Linux, macOS, Windows +- **Node.js**: `>= 18.19.0` (consigliato `20 LTS`) +- **npm**: `>= 9` +- **RAM**: minimo 2GB (consigliato 4GB) -#### Per Deployment -- **Server Web**: Qualsiasi server statico (nginx, Apache, Vercel, Netlify) -- **HTTPS**: Obbligatorio per Service Worker e PWA (eccetto localhost) -- **Connessione Internet**: Solo per primo caricamento (poi funziona offline) +#### Per Esecuzione Test E2E +- Browser Playwright installati (`chromium`, `firefox`) +- Su Linux, eventuali dipendenze sistema per browser headless + +Comandi utili: + +```bash +node -v +npm -v +npx playwright install chromium firefox +# Linux, se necessario: +# npx playwright install --with-deps chromium firefox +``` ### Requisiti Browser (Utente Finale) -| Requisito | Dettaglio | Necessità | +| Requisito | Dettaglio | Necessita | |-----------|-----------|-----------| -| **JavaScript ES6+** | Supporto moduli, arrow functions, async/await | Obbligatorio | -| **Service Worker API** | Per funzionalità offline PWA | Obbligatorio | -| **Fullscreen API** | Per modalità schermo intero | Consigliato | -| **Web Speech API** | Per sintesi vocale punteggi | Opzionale | -| **Local Storage** | Per persistenza configurazioni | Consigliato | +| JavaScript ES6+ | Moduli, async/await | Obbligatorio | +| WebSocket | Sincronizzazione stato live | Obbligatorio | +| Service Worker API | Supporto PWA offline | Consigliato | +| Web Speech API | Annunci vocali | Opzionale | ### Browser Testati e Supportati -| Browser | Versione Minima | Supporto | Note | -|---------|-----------------|----------|------| -| Chrome/Chromium | 90+ | ✅ Completo | Consigliato per tutte le features | -| Firefox | 88+ | ✅ Completo | Supporto completo PWA e Speech API | +| Browser | Supporto | Note | +|---------|----------|------| +| Chrome/Chromium | ✅ | Completo | +| Firefox | ✅ | Completo | +| Mobile Chrome (Playwright Pixel 5) | ✅ | Copertura E2E mobile | --- @@ -76,21 +89,14 @@ Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di parti ### Prerequisiti -- **Node.js** v20.2.0 (consigliato) -- **npm** o **yarn** +- Node.js `>= 18.19.0` +- npm `>= 9` -### Installazione con NVM (consigliato) +### Installazione ```bash -# Installa la versione corretta di Node.js -nvm install v20.2.0 -nvm use v20.2.0 - -# Clona il repository -git clone +git clone https://santantonio.sytes.net/attilio/segnapunti.git cd segnapunti - -# Installa le dipendenze npm install ``` @@ -100,19 +106,20 @@ npm install ### Dev Server -Avvia il server di sviluppo con hot-reload: +Avvia il server di sviluppo Vite: ```bash npm run dev ``` -L'applicazione sarà disponibile su [http://localhost:5173](http://localhost:5173) +Accesso tipico in sviluppo: +- `http://localhost:5173/` -> Display +- `http://localhost:5173/controller.html` -> Controller -### Modalità Sviluppo -- Hot Module Replacement (HMR) attivo -- Source maps per debugging -- Vue DevTools supportato -- Errori e warnings in console +### Modalita Sviluppo +- Hot reload attivo +- Build veloce lato Vite +- Buona per sviluppo UI/UX --- @@ -120,102 +127,46 @@ L'applicazione sarà disponibile su [http://localhost:5173](http://localhost:517 ### Build Produzione -Genera i file ottimizzati per il deployment: - ```bash npm run build ``` -**Output:** -- Cartella `/dist` con file statici ottimizzati -- Service Worker generato automaticamente -- PWA manifest configurato -- Assets minificati e con hash per cache busting -- Base path: `/segnap` (modificabile in `vite.config.js`) +Output: +- cartella `dist/` +- asset ottimizzati +- file PWA (manifest + service worker) -### Preview Build +### Avvio Server Applicativo Locale (Display + Controller) -Anteprima locale della build di produzione: +```bash +npm run serve +``` + +Espone: +- `http://localhost:3000` -> Display +- `http://localhost:3001` -> Controller + +### Altri comandi utili ```bash npm run preview +npm run start ``` -Serve i file dalla cartella `/dist` per testare la build prima del deploy. - ---- - -## Shortcuts - -### Controlli Tastiera Squadra Home - -| Scorciatoia | Azione | -|-------------|--------| -| `Ctrl + ↑` | Incrementa punti | -| `Ctrl + ↓` | Decrementa punti | -| `Ctrl + →` | Incrementa set | -| `Ctrl + C` | Apri dialog cambi | - -### Controlli Tastiera Squadra Guest - -| Scorciatoia | Azione | -|-------------|--------| -| `Shift + ↑` | Incrementa punti | -| `Shift + ↓` | Decrementa punti | -| `Shift + →` | Incrementa set | -| `Shift + C` | Apri dialog cambi | - -### Comandi Globali - -| Scorciatoia | Azione | -|-------------|--------| -| `Ctrl + ←` | Cambio palla (servizio) - **solo a 0-0** | -| `Ctrl + M` | Apri configurazione nomi squadre e formazioni | -| `Ctrl + B` | Toggle visibilità barra pulsanti | -| `Ctrl + F` | Attiva/disattiva fullscreen | -| `Ctrl + S` | Annuncio vocale punteggio corrente | -| `Ctrl + Z` | Switch tra visualizzazione formazioni e punteggio | - --- ## Configurazione PWA -L'applicazione è configurata come **Progressive Web App** nel file [vite.config.js](vite.config.js): +L'app usa `vite-plugin-pwa` (vedi `vite.config.js`) con: +- `registerType: 'autoUpdate'` +- manifest installabile +- orientamento landscape +- modalita fullscreen -```javascript -VitePWA({ - registerType: 'autoUpdate', - manifest: { - name: "app_segnap", - short_name: "segnap", - description: "Segnapunti standalone.", - background_color: "#eee", - theme_color: '#ffffff', - display: "fullscreen", - orientation: "landscape", - icons: [ - { src: 'segnap-192x192.png', sizes: '192x192', type: 'image/png' }, - { src: 'segnap-512x512.png', sizes: '512x512', type: 'image/png' } - ] - } -}) -``` - -### Caratteristiche PWA - -- **Display**: Fullscreen per massimizzare lo spazio visivo -- **Orientamento**: Landscape (orizzontale) ottimizzato per tablet -- **Auto-update**: Service Worker con aggiornamento automatico -- **Offline**: Funzionamento completo senza connessione internet -- **Installabile**: Aggiungibile alla home screen come app nativa - -### Installazione PWA - -**Android/Desktop (Chrome):** -- Menu → "Installa app" o icona (⊕) nella barra degli indirizzi - -**iOS (Safari):** -- Share (□↑) → "Aggiungi a Home" +Caratteristiche principali: +- installabile su dispositivi supportati +- aggiornamento automatico del service worker +- supporto utilizzo offline (in base alle risorse cache) --- @@ -223,33 +174,35 @@ VitePWA({ ### Vittoria Set -- **Set regolari (1-4)**: Primo a 25 punti con almeno 2 di vantaggio -- **Set decisivo**: - - Modalità 2/3: 3° set a 15 punti con almeno 2 di vantaggio - - Modalità 3/5: 5° set a 15 punti con almeno 2 di vantaggio -- **Blocco automatico**: Non consente assegnare punti oltre la vittoria +- 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 **automaticamente** quando: -1. La squadra **conquista il servizio** (cambio palla) -2. Il punteggio è diverso da 0-0 - -**Limitazione cambio palla manuale:** -- Il cambio manuale del servizio (`Ctrl + ←`) è consentito **solo a 0-0** -- Questa limitazione previene errori nella rotazione delle formazioni +La rotazione avviene durante i cambi palla secondo la logica implementata in `src/gameState.js`. ### Formazione in Campo -Visualizzazione a 6 posizioni standard: +Il sistema gestisce 6 posizioni per squadra e permette cambi validati da Controller. -``` - Rete -┌─────┬─────┬─────┐ -│ 4 │ 3 │ 2 │ ← Fila anteriore -├─────┼─────┼─────┤ -│ 5 │ 6 │ 1 │ ← Fila posteriore -└─────┴─────┴─────┘ +--- + +## Test (stato attuale) + +Suite presenti: +- Unit +- Integration +- Component +- Stress +- E2E (Playwright) + +Comandi principali: + +```bash +npm run test:all +npm run test:e2e ``` -La rotazione avviene in senso orario: 1→6→5→4→3→2→1 +Guida completa test: +- `tests/README.md`