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

aggiorna README

Browse Source
This commit is contained in:
Davide Grilli
2026-04-01 18:58:02 +02:00
parent d1e8279608
commit 27e29a78e7
1 changed files with 84 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
README.md
View File

@@ -1,98 +1,90 @@
# Segnapunti Anto # 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 ## 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: ### Architettura
- **Display** (tabellone pubblico)
- **Controller** (pannello operatore)
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** Le due interfacce comunicano tramite **WebSocket** (`/ws`): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi.
- Tracciamento punti home/guest
- Gestione set
- Indicatore servizio
- Storico punti (striscia)
- Blocchi logici quando il set e gia vinto
- **Regole pallavolo integrate** 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.
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.
---
## 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 normali: vittoria a 25 con almeno 2 punti di scarto
- Set decisivo: vittoria a 15 con almeno 2 punti di scarto - Set decisivo (5° set): vittoria a 15 con almeno 2 punti di scarto
- Modalita partita `2/3` o `3/5` - Modalità partita `2/3` o `3/5`
- **Formazioni e cambi** ### Formazioni e cambi
- Gestione formazione a 6 giocatori - Gestione formazione a 6 giocatori per squadra
- Rotazione automatica al cambio palla - Rotazione automatica al cambio palla
- Dialog cambi con validazioni (`IN -> OUT`) - Dialog cambi con validazione `IN → OUT`
- **Controlli e personalizzazione** ### Controlli e personalizzazione
- Configurazione nomi squadre - Configurazione nomi squadre
- Toggle ordine squadre (inverti) - Inversione ordine di visualizzazione squadre
- Toggle visualizzazione punteggio/formazioni - Toggle punteggio/formazioni e visibilità striscia storico
- Toggle striscia storico - Sintesi vocale del punteggio (Web Speech API)
- Sintesi vocale punteggio (Web Speech API)
--- ---
## Requisiti ## Requisiti
### Requisiti di Sistema ### Ambiente di sviluppo
#### Per Sviluppo | Requisito | Versione minima | Consigliata |
- **Sistema Operativo**: Linux, macOS, Windows |-----------|-----------------|-------------|
- **Node.js**: `>= 18.19.0` (consigliato `20 LTS`) | **Node.js** | `>= 18.19.0` | `24 LTS` |
- **npm**: `>= 9` | **npm** | `>= 9` | — |
- **RAM**: minimo 2GB (consigliato 4GB) | **RAM** | 2 GB | 4 GB |
| **OS** | Linux, macOS, Windows | — |
#### Per Esecuzione Test E2E ### Test E2E
- Browser Playwright installati (`chromium`, `firefox`)
- Su Linux, eventuali dipendenze sistema per browser headless
Comandi utili: I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive.
```bash ```bash
node -v
npm -v
npx playwright install chromium firefox npx playwright install chromium firefox
# Linux, se necessario: # Linux (con dipendenze di sistema):
# npx playwright install --with-deps chromium firefox # 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 | | JavaScript ES6+ | Moduli, async/await | Obbligatorio |
| WebSocket | Sincronizzazione stato live | Obbligatorio | | WebSocket | Sincronizzazione stato live | Obbligatorio |
| Service Worker API | Supporto PWA offline | Consigliato | | Service Worker | Supporto PWA offline | Consigliato |
| Web Speech API | Annunci vocali | Opzionale | | Web Speech API | Annunci vocali punteggio | Opzionale |
### Browser Testati e Supportati **Browser testati:** Chrome/Chromium, Firefox, Mobile Chrome (Playwright Pixel 5).
| Browser | Supporto | Note |
|---------|----------|------|
| Chrome/Chromium | ✅ | Completo |
| Firefox | ✅ | Completo |
| Mobile Chrome (Playwright Pixel 5) | ✅ | Copertura E2E mobile |
--- ---
## Installazione e Setup ## Installazione
### Prerequisiti
- Node.js `>= 18.19.0`
- npm `>= 9`
### Installazione
```bash ```bash
git clone https://santantonio.sytes.net/attilio/segnapunti.git git clone https://santantonio.sytes.net/attilio/segnapunti.git
@@ -102,107 +94,58 @@ npm install
--- ---
## Comandi per Sviluppo ## Sviluppo
### Dev Server ### Dev server
Avvia il server di sviluppo Vite:
```bash ```bash
npm run dev npm run dev
``` ```
Accesso tipico in sviluppo: Avvia il server Vite con hot reload:
- `http://localhost:5173/` -> Display - `http://localhost:5173/` — Display
- `http://localhost:5173/controller.html` -> Controller - `http://localhost:5173/controller.html` — Controller
### Modalita Sviluppo ### Build di produzione
- Hot reload attivo
- Build veloce lato Vite
- Buona per sviluppo UI/UX
---
## Comandi per Build
### Build Produzione
```bash ```bash
npm run build npm run build
``` ```
Output: Genera la cartella `dist/` con asset ottimizzati, manifest e service worker PWA.
- cartella `dist/`
- asset ottimizzati
- file PWA (manifest + service worker)
### Avvio Server Applicativo Locale (Display + Controller) ### Avvio in produzione (locale)
```bash ```bash
npm run serve npm run serve
``` ```
Espone: Espone i due server:
- `http://localhost:3000` -> Display - `http://localhost:3000` — Display
- `http://localhost:3001` -> Controller - `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 ```bash
npm run preview docker-compose up --build
npm run start
``` ```
--- Espone le porte `3000` (Display) e `3001` (Controller).
## 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`