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** è 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.

### Funzionalità Principali

- **Gestione Completa Partite**
  - Tracciamento punti in tempo reale per entrambe le squadre
  - Conteggio automatico dei set (fino a 5 set)
  - Indicatore visivo del servizio
  - Cronologia punti con striscia visiva

- **Formazioni Squadra**
  - Visualizzazione interattiva dei 6 giocatori in campo
  - Rotazione automatica regolamentare al cambio palla
  - Configurazione manuale dei numeri di maglia
  - Supporto logica pallavolo ufficiale (25 punti + 2 di vantaggio, 5° set a 15)

- **Controlli Multimodali**
  - Scorciatoie da tastiera complete (vedi sezione [Shortcuts](#shortcuts))
  - Sintesi vocale per annunci punteggio in italiano (Web Speech API)

- **Personalizzazione**
  - Configurazione dinamica nomi squadre
  - Toggle layout orizzontale (inverti home/guest)
  - Modalità visualizzazione: punteggio semplice o formazioni complete
  - Nascondi/mostra controlli e cronologia

---

## Requisiti

### Requisiti di Sistema

#### Per Sviluppo
- **Sistema Operativo**: Linux, macOS, Windows (WSL2 consigliato)
- **Node.js**: v20.2.0 o superiore (LTS consigliato)
- **npm**: v9.0.0 o superiore (incluso con Node.js)
- **RAM**: Minimo 2GB, consigliato 4GB
- **Spazio Disco**: ~500MB per dipendenze e build

#### Per Deployment
- **Server Web**: Qualsiasi server statico (nginx, Apache, Vercel, Netlify)
- **HTTPS**: Obbligatorio per Service Worker e PWA (eccetto localhost)
- **Connessione Internet**: Solo per primo caricamento (poi funziona offline)

### Requisiti Browser (Utente Finale)

| Requisito | Dettaglio | Necessità |
|-----------|-----------|-----------|
| **JavaScript ES6+** | Supporto moduli, arrow functions, async/await | Obbligatorio |
| **Service Worker API** | Per funzionalità offline PWA | Obbligatorio |
| **Fullscreen API** | Per modalità schermo intero | Consigliato |
| **Web Speech API** | Per sintesi vocale punteggi | Opzionale |
| **Local Storage** | Per persistenza configurazioni | Consigliato |

### Browser Testati e Supportati

| Browser | Versione Minima | Supporto | Note |
|---------|-----------------|----------|------|
| Chrome/Chromium | 90+ | ✅ Completo | Consigliato per tutte le features |
| Firefox | 88+ | ✅ Completo | Supporto completo PWA e Speech API |

---

## Installazione e Setup

### Prerequisiti

- **Node.js** v20.2.0 (consigliato)
- **npm** o **yarn**

### Installazione con NVM (consigliato)

```bash
# Installa la versione corretta di Node.js
nvm install v20.2.0
nvm use v20.2.0

# Clona il repository
git clone <repository-url>
cd segnapunti

# Installa le dipendenze
npm install
```

---

## Comandi per Sviluppo

### Dev Server

Avvia il server di sviluppo con hot-reload:

```bash
npm run dev
```

L'applicazione sarà disponibile su [http://localhost:5173](http://localhost:5173)

### Modalità Sviluppo
- Hot Module Replacement (HMR) attivo
- Source maps per debugging
- Vue DevTools supportato
- Errori e warnings in console

---

## Comandi per Build

### Build Produzione

Genera i file ottimizzati per il deployment:

```bash
npm run build
```

**Output:**
- Cartella `/dist` con file statici ottimizzati
- Service Worker generato automaticamente
- PWA manifest configurato
- Assets minificati e con hash per cache busting
- Base path: `/segnap` (modificabile in `vite.config.js`)

### Preview Build

Anteprima locale della build di produzione:

```bash
npm run preview
```

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 |

### Controlli Tastiera Squadra Guest

| Scorciatoia | Azione |
|-------------|--------|
| `Shift + ↑` | Incrementa punti |
| `Shift + ↓` | Decrementa punti |
| `Shift + →` | Incrementa set |

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

L'applicazione è configurata come **Progressive Web App** nel file [vite.config.js](vite.config.js):

```javascript
VitePWA({
  registerType: 'autoUpdate',
  manifest: {
    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"

---

## Logica Regolamentare Pallavolo

### Vittoria Set

- **Set regolari (1-4)**: Primo a 25 punti con almeno 2 di vantaggio
- **Set decisivo (5°)**: Primo a 15 punti con almeno 2 di vantaggio
- **Blocco automatico**: Non consente assegnare punti oltre la vittoria

### Rotazione Formazione

La rotazione avviene **automaticamente** quando:
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

Visualizzazione a 6 posizioni standard:

```
        Rete
┌─────┬─────┬─────┐
│  4  │  3  │  2  │  ← Fila anteriore
├─────┼─────┼─────┤
│  5  │  6  │  1  │  ← Fila posteriore
└─────┴─────┴─────┘
```

La rotazione avviene in senso orario: 1→2→3→4→5→6→1