segnapunti/README.md

# Segnapunti Anto

Applicazione web **fullstack real-time** per il tracciamento dei punteggi di partite di pallavolo, installabile come PWA.

---

## Panoramica

**Segnapunti Anto** è un'applicazione fullstack per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone in contesto sportivo.

### Architettura

Il sistema è composto da un **backend Node.js/Express** e due interfacce web separate:

| Interfaccia | Porta | Ruolo |
|-------------|-------|-------|
| **Display** | 3000 | Tabellone pubblico — mostra punteggi, formazioni e storico |
| **Controller** | 3001 | Pannello operatore — invia azioni e gestisce la partita |

Le due interfacce comunicano tramite **WebSocket** (`/ws`): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi.

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

### Ambiente di sviluppo

| Requisito | Versione minima | Consigliata |
|-----------|-----------------|-------------|
| **Node.js** | `>= 18.19.0` | `24 LTS` |
| **npm** | `>= 9` | — |
| **RAM** | 2 GB | 4 GB |
| **OS** | Linux, macOS, Windows | — |

### Test E2E

I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive.

```bash
npx playwright install chromium firefox
# Linux (con dipendenze di sistema):
# npx playwright install --with-deps chromium firefox
```

### Requisiti browser (utente finale)

| API | Utilizzo | Necessità |
|-----|----------|-----------|
| JavaScript ES6+ | Moduli, async/await | Obbligatorio |
| WebSocket | Sincronizzazione stato live | Obbligatorio |
| Service Worker | Supporto PWA offline | Consigliato |
| Web Speech API | Annunci vocali punteggio | Opzionale |

**Browser testati:** Chrome/Chromium, Firefox, Mobile Chrome (Playwright Pixel 5).

---

## Installazione

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

---

## Sviluppo

### Dev server

```bash
npm run dev
```

Avvia il server Vite con hot reload:
- `http://localhost:5173/` — Display
- `http://localhost:5173/controller.html` — Controller

### Build di produzione

```bash
npm run build
```

Genera la cartella `dist/` con asset ottimizzati, manifest e service worker PWA.

### Avvio in produzione (locale)

```bash
npm run serve
```

Espone i due server:
- `http://localhost:3000` — Display
- `http://localhost:3001` — Controller

---

## Terminal Controller (CLI)

Il CLI è un controller da terminale che si connette al server via WebSocket e permette di gestire la partita senza browser.

### Avvio

```bash
# Modalità produzione (server su porta 3000)
npm run cli

# Modalità sviluppo (server Vite su porta 5173)
npm run cli:dev

# Porta custom
node cli.js <porta>
```

Il CLI richiede che il server sia già in esecuzione in un altro terminale.

### Comandi disponibili

#### Punteggio

| Comando | Alias | Effetto |
|---------|-------|---------|
| `punto casa` | `+`, `pc` | Assegna un punto alla squadra di casa |
| `punto ospite` | `-`, `po` | Assegna un punto alla squadra ospite |
| `undo` | `u` | Annulla l'ultimo punto assegnato |

#### Set

| Comando | Effetto |
|---------|---------|
| `set casa` | Incrementa il contatore set della squadra di casa |
| `set ospite` | Incrementa il contatore set della squadra ospite |

#### Partita

| Comando | Effetto |
|---------|---------|
| `serv` | Cambia il servizio (disponibile solo se il punteggio è 0-0) |
| `reset` | Resetta la partita — chiede conferma prima di procedere |
| `nomi <casa> <ospite>` | Imposta i nomi delle squadre (es. `nomi Antoniana Teate`) |
| `modalita 2/3` | Imposta la modalità best-of-3 |
| `modalita 3/5` | Imposta la modalità best-of-5 |

#### Informazioni

| Comando | Alias | Effetto |
|---------|-------|---------|
| `stato` | — | Mostra il punteggio corrente nel terminale |
| `help` | — | Mostra la lista dei comandi |
| `exit` | `q` | Chiude il CLI |

### Note

- **Tab**: completamento automatico dei comandi
- **Freccia su/giù**: navigazione nella history dei comandi (ultime 100 voci)
- Il Display nel browser si aggiorna in tempo reale ad ogni comando inviato

---

## 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
docker-compose up --build
```

Espone le porte `3000` (Display) e `3001` (Controller).