attilio/segnapunti
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Aggiorna README.md

Browse Source
This commit is contained in:
Davide Grilli
2026-02-12 19:44:17 +01:00
parent e4d212eea3
commit aa88e2b7a1
1 changed files with 114 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
README.md
View File

@@ -6,34 +6,39 @@ Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di parti
## Panoramica ## 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** Le due interfacce condividono lo stato in tempo reale tramite WebSocket.
- 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
- **Formazioni Squadra** ### Funzionalita Principali
- 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)
- **Controlli Multimodali** - **Gestione partita in tempo reale**
- Scorciatoie da tastiera complete (vedi sezione [Shortcuts](#shortcuts)) - Tracciamento punti home/guest
- Sintesi vocale per annunci punteggio in italiano (Web Speech API) - Gestione set
- Indicatore servizio
- Storico punti (striscia)
- Blocchi logici quando il set e gia vinto
- **Personalizzazione** - **Regole pallavolo integrate**
- Configurazione dinamica nomi squadre - Set normali: vittoria a 25 con almeno 2 punti di scarto
- Selettore modalità partita: al meglio di 3 o al meglio di 5 - Set decisivo: vittoria a 15 con almeno 2 punti di scarto
- Toggle layout orizzontale (inverti home/guest) - Modalita partita `2/3` o `3/5`
- Modalità visualizzazione: punteggio semplice o formazioni complete
- Nascondi/mostra controlli e cronologia - **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 ### Requisiti di Sistema
#### Per Sviluppo #### Per Sviluppo
- **Sistema Operativo**: Linux, macOS, Windows (WSL2 consigliato) - **Sistema Operativo**: Linux, macOS, Windows
- **Node.js**: v20.2.0 o superiore (LTS consigliato) - **Node.js**: `>= 18.19.0` (consigliato `20 LTS`)
- **npm**: v9.0.0 o superiore (incluso con Node.js) - **npm**: `>= 9`
- **RAM**: Minimo 2GB, consigliato 4GB - **RAM**: minimo 2GB (consigliato 4GB)
- **Spazio Disco**: ~500MB per dipendenze e build
#### Per Deployment #### Per Esecuzione Test E2E
- **Server Web**: Qualsiasi server statico (nginx, Apache, Vercel, Netlify) - Browser Playwright installati (`chromium`, `firefox`)
- **HTTPS**: Obbligatorio per Service Worker e PWA (eccetto localhost) - Su Linux, eventuali dipendenze sistema per browser headless
- **Connessione Internet**: Solo per primo caricamento (poi funziona offline)
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) ### Requisiti Browser (Utente Finale)
| Requisito | Dettaglio | Necessità | | Requisito | Dettaglio | Necessita |
|-----------|-----------|-----------| |-----------|-----------|-----------|
| **JavaScript ES6+** | Supporto moduli, arrow functions, async/await | Obbligatorio | | JavaScript ES6+ | Moduli, async/await | Obbligatorio |
| **Service Worker API** | Per funzionalità offline PWA | Obbligatorio | | WebSocket | Sincronizzazione stato live | Obbligatorio |
| **Fullscreen API** | Per modalità schermo intero | Consigliato | | Service Worker API | Supporto PWA offline | Consigliato |
| **Web Speech API** | Per sintesi vocale punteggi | Opzionale | | Web Speech API | Annunci vocali | Opzionale |
| **Local Storage** | Per persistenza configurazioni | Consigliato |
### Browser Testati e Supportati ### Browser Testati e Supportati
| Browser | Versione Minima | Supporto | Note | | Browser | Supporto | Note |
|---------|-----------------|----------|------| |---------|----------|------|
| Chrome/Chromium | 90+ | ✅ Completo | Consigliato per tutte le features | | Chrome/Chromium | ✅ | Completo |
| Firefox | 88+ | ✅ Completo | Supporto completo PWA e Speech API | | 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 ### Prerequisiti
- **Node.js** v20.2.0 (consigliato) - Node.js `>= 18.19.0`
- **npm** o **yarn** - npm `>= 9`
### Installazione con NVM (consigliato) ### Installazione
```bash ```bash
# Installa la versione corretta di Node.js git clone https://santantonio.sytes.net/attilio/segnapunti.git
nvm install v20.2.0
nvm use v20.2.0
# Clona il repository
git clone <repository-url>
cd segnapunti cd segnapunti
# Installa le dipendenze
npm install npm install
``` ```
@@ -100,19 +106,20 @@ npm install
### Dev Server ### Dev Server
Avvia il server di sviluppo con hot-reload: Avvia il server di sviluppo Vite:
```bash ```bash
npm run dev 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 ### Modalita Sviluppo
- Hot Module Replacement (HMR) attivo - Hot reload attivo
- Source maps per debugging - Build veloce lato Vite
- Vue DevTools supportato - Buona per sviluppo UI/UX
- Errori e warnings in console
--- ---
@@ -120,102 +127,46 @@ L'applicazione sarà disponibile su [http://localhost:5173](http://localhost:517
### Build Produzione ### Build Produzione
Genera i file ottimizzati per il deployment:
```bash ```bash
npm run build npm run build
``` ```
**Output:** Output:
- Cartella `/dist` con file statici ottimizzati - cartella `dist/`
- Service Worker generato automaticamente - asset ottimizzati
- PWA manifest configurato - file PWA (manifest + service worker)
- Assets minificati e con hash per cache busting
- Base path: `/segnap` (modificabile in `vite.config.js`)
### 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 ```bash
npm run preview 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 ## 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 Caratteristiche principali:
VitePWA({ - installabile su dispositivi supportati
registerType: 'autoUpdate', - aggiornamento automatico del service worker
manifest: { - supporto utilizzo offline (in base alle risorse cache)
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"
--- ---
@@ -223,33 +174,35 @@ VitePWA({
### Vittoria Set ### Vittoria Set
- **Set regolari (1-4)**: Primo a 25 punti con almeno 2 di vantaggio - Set normali: vittoria a 25 con almeno 2 punti di scarto
- **Set decisivo**: - Set decisivo: vittoria a 15 con almeno 2 punti di scarto
- Modalità 2/3: 3° set a 15 punti con almeno 2 di vantaggio - Modalita partita supportate: `2/3` e `3/5`
- Modalità 3/5: 5° set a 15 punti con almeno 2 di vantaggio
- **Blocco automatico**: Non consente assegnare punti oltre la vittoria
### Rotazione Formazione ### Rotazione Formazione
La rotazione avviene **automaticamente** quando: La rotazione avviene durante i cambi palla secondo la logica implementata in `src/gameState.js`.
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
### Formazione in Campo ### Formazione in Campo
Visualizzazione a 6 posizioni standard: Il sistema gestisce 6 posizioni per squadra e permette cambi validati da Controller.
``` ---
Rete
┌─────┬─────┬─────┐ ## Test (stato attuale)
│ 4 │ 3 │ 2 │ ← Fila anteriore
├─────┼─────┼─────┤ Suite presenti:
│ 5 │ 6 │ 1 │ ← Fila posteriore - 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`