Aggiorna README.md

2026-02-12 19:44:17 +01:00
parent e4d212eea3
commit aa88e2b7a1
1 changed files with 114 additions and 161 deletions
--- 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 <repository-url>
+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`