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

225
README.md
View File

@@ -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).