segnapunti/README.md

# Segnapunti Anto

Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di partite di pallavolo in tempo reale.

---

## Panoramica

**Segnapunti Anto** e un'applicazione digitale per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone.

L'app e composta da due interfacce:
- **Display** (tabellone pubblico)
- **Controller** (pannello operatore)

Le due interfacce condividono lo stato in tempo reale tramite WebSocket.

### Funzionalita Principali

- **Gestione partita in tempo reale**
  - Tracciamento punti home/guest
  - Gestione set
  - Indicatore servizio
  - Storico punti (striscia)
  - Blocchi logici quando il set e gia vinto

- **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)

---

## Requisiti

### Requisiti di Sistema

#### Per Sviluppo
- **Sistema Operativo**: Linux, macOS, Windows
- **Node.js**: `>= 18.19.0` (consigliato `20 LTS`)
- **npm**: `>= 9`
- **RAM**: minimo 2GB (consigliato 4GB)

#### 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 | Necessita |
|-----------|-----------|-----------|
| 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 | Supporto | Note |
|---------|----------|------|
| Chrome/Chromium | ✅ | Completo |
| Firefox | ✅ | Completo |
| Mobile Chrome (Playwright Pixel 5) | ✅ | Copertura E2E mobile |

---

## Installazione e Setup

### Prerequisiti

- Node.js `>= 18.19.0`
- npm `>= 9`

### Installazione

```bash
git clone https://santantonio.sytes.net/attilio/segnapunti.git
cd segnapunti
npm install
```

---

## Comandi per Sviluppo

### Dev Server

Avvia il server di sviluppo Vite:

```bash
npm run dev
```

Accesso tipico in sviluppo:
- `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

```bash
npm run build
```

Output:
- cartella `dist/`
- asset ottimizzati
- file PWA (manifest + service worker)

### Avvio Server Applicativo Locale (Display + Controller)

```bash
npm run serve
```

Espone:
- `http://localhost:3000` -> Display
- `http://localhost:3001` -> Controller

### Altri comandi utili

```bash
npm run preview
npm run start
```

---

## 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`