segnapunti/CHANGELOG.md

# Changelog

Tutte le modifiche significative a questo progetto sono documentate in questo file.

Il formato si basa su [Keep a Changelog](https://keepachangelog.com/it/1.0.0/),
e questo progetto aderisce al [Versionamento Semantico](https://semver.org/lang/it/).

---

## [2.1.0] - 2026-07-08

### Aggiunto
- Time out con spot pubblicitari: sul controller una modal fa scegliere squadra e video (o nessuno) tra i file `.mp4` della cartella `spot/`; il display copre il tabellone con un overlay a countdown, riproduce il video scelto (con fallback su testo "TIME OUT <squadra>" se manca o finisce in anticipo) e sfuma nell'ultimo secondo; il server chiude automaticamente il time out dopo 30s anche in caso di disconnessione del controller; video elencati da `/spot/list` e serviti da `/spot/<file>.mp4`
- Storico di cambi e time out registrato per ogni set nella `striscia` (popolato lazy, ordinato per punteggio, usato dal referto)
- Modalità **Amichevole**: i set si vincono normalmente ma la partita non termina mai automaticamente, per giocare set illimitati
- Dialog dedicato a fine partita che blocca ulteriori punti e apre le azioni post-match (referto, chiusura)
- Prototipo di generazione referto di gara stampabile (`src/referto.js`): formazioni di partenza, griglia punti, cambi e time out per set
- Layout esteso "da regia" per il controller in orientamento landscape (tablet), con pannelli squadra affiancati
- Indicatore ON/OFF sul pulsante Striscia del controller; config si riapre automaticamente dopo un reset
- Supporto WSL2 in sviluppo: `getNetworkIPs()` interroga PowerShell per ottenere gli IP reali della rete Windows
- Flusso di sviluppo containerizzato con hot reload: `docker-compose.dev.yml` e nuovo target `dev` nel Dockerfile multi-stage
- Suite di test estesa a oltre il 99% di copertura statement, con nuovi test e2e (time out, referto, accessibilità, visual regression)

### Modificato
- `punteggio`/`setVinti`/`servizio` derivati sempre dalla `striscia` invece di essere memorizzati nello stato
- Struttura dati `striscia` compattata da array a stringa
- Il controller rispetta `state.order` (scambio lato squadre) come il display
- Logica di connessione WebSocket lato client estratta in `src/wsMixin.js` riusabile
- Dev server esposto su tutte le interfacce di rete (`vite --host`)
- Persistenza dati passata da named volume a bind mount (`./.segnapunti`) per accesso diretto ai file dall'host

### Rimosso
- Sezione shortcut da tastiera dal README (funzionalità non più implementata)
- Emoji da codice, UI e commenti (ora vietate salvo richiesta esplicita)

### Corretto
- Immagine Docker di produzione: mancava la copia di `src/spot-utils.js`, causando errori nel serving degli spot video

---

## [2.0.0] - 2026-05-12

### Aggiunto
- Architettura client-server con WebSocket: server Express (`server.js`) + handler (`src/websocket-handler.js`) come unica fonte di verità; display e controller sono client separati sincronizzati in tempo reale
- Interfaccia display (`/display`) e controller (`/controller`) su porta singola `:3000`
- Robustezza connessione WebSocket: reconnect automatico con backoff esponenziale, indicatore stato connessione sul display
- Supporto query parameter `?wsHost=` per scenari WSL2 / development remoto
- Validazione cambi giocatori già in formazione lato client
- Sintesi vocale inoltrata dal controller al display via WebSocket
- Dialog set vinto sul controller al raggiungimento dei 25 punti: mostra il vincitore, permette di annullare l'ultimo punto (INDIETRO) o avanzare al set successivo con reset automatico formazioni
- Struttura striscia ottimizzata: array di set `[{ serv, r[] }]` che registra la sequenza dei punti e preserva la storia di tutti i set; elimina `storicoServizio`
- Persistenza stato su `.segnapunti/state.json`: salvato ad ogni azione, ricaricato all'avvio del server
- Suite di test completa: unit (Vitest), integration, component (Vue Test Utils + Happy-DOM), stress (50+ client), E2E (Playwright su Chromium, Firefox, Mobile Chrome)
- Dockerfile multi-stage (builder + runtime minimale) e docker-compose con volume per persistenza stato; immagine pubblicata su registro Gitea

### Modificato
- `applyAction` usa `structuredClone` al posto di `JSON.parse/stringify`
- Calcolo cambio palla deduplicato in `applyAction`
- Undo punto (`decPunt`) ricostruisce il servizio precedente dalla storia `r[]`
- `nuovoSet` come azione dedicata per la progressione regolare tra set

### Rimosso
- Terminal controller CLI (`cli.js`)
- Dipendenze inutilizzate: `wave-ui`, `vue-router`, `concurrently`
- Script npm ridondanti: `preview`, `start`, `cli`, `cli:dev`
- Asset template Vite: `vite.svg`, `vue.svg`, `serve.png`

---

## [1.0.0] - 2026-02-10

Rilascio iniziale di **Segnapunti Anto**, un'applicazione web Progressive Web App (PWA) professionale per il tracciamento in tempo reale dei punteggi durante partite di pallavolo.

### Funzionalità Principali

#### Gestione Partite e Punteggi
- **Tracciamento punti in tempo reale** per entrambe le squadre (casa e ospite)
- **Conteggio automatico dei set** con supporto per modalità al meglio di 3 o al meglio di 5
- **Logica regolamentare completa**:
  - Set regolari: primo a 25 punti con almeno 2 di vantaggio
  - Set decisivo (tie-break): primo a 15 punti con almeno 2 di vantaggio
  - Blocco automatico assegnazione punti al raggiungimento della vittoria
- **Indicatore visivo del servizio** per identificare quale squadra è al servizio
- **Cronologia punti** con striscia visiva per seguire l'andamento della partita
- Possibilità di **incrementare e decrementare punti** e **set**
- **Annullamento punti** con ripristino automatico del servizio precedente

#### Formazioni e Rotazioni
- **Visualizzazione interattiva** della formazione in campo con 6 giocatori per squadra
- **Rotazione automatica regolamentare** quando la squadra conquista il servizio (cambio palla)
- **Configurazione manuale dei numeri di maglia** per ogni giocatore
- **Sistema di cambi giocatori**:
  - Dialog dedicato per effettuare i cambi
  - Supporto per cambi singoli o multipli
  - Tabella IN/OUT con validazione degli input
  - Verifica che i numeri di maglia siano numerici
  - Scorciatoie da tastiera dedicate per squadra casa e ospite
- **Limitazione cambio palla manuale** solo a inizio set (0-0) per prevenire errori nella rotazione

#### Interfaccia Utente e Personalizzazione
- **Interfaccia fullscreen touch-friendly** ottimizzata per tablet e smartphone
- **Layout responsive** con media queries per schermi piccoli (<768px)
- **Modalità di visualizzazione**:
  - Punteggio semplice
  - Formazioni complete con posizioni giocatori
  - Toggle tra le due modalità con scorciatoia da tastiera
- **Personalizzazione squadre**:
  - Configurazione dinamica dei nomi squadre
  - Inversione layout orizzontale (scambio posizione casa/ospite)
  - Configurazione numeri di maglia giocatori
- **Controlli nascondibili**: possibilità di nascondere/mostrare barra pulsanti e cronologia
- **Stabilizzazione UI**: dimensioni fisse per riquadri punteggio per evitare spostamenti durante gli aggiornamenti

#### Controlli e Accessibilità
- **Controlli da tastiera completi** con scorciatoie dedicate:
  - **Squadra Casa**: `Ctrl + ↑/↓` (punti), `Ctrl + →` (set), `Ctrl + C` (cambi)
  - **Squadra Ospite**: `Shift + ↑/↓` (punti), `Shift + →` (set), `Shift + C` (cambi)
  - **Comandi globali**:
    - `Ctrl + ←` (cambio palla, solo a 0-0)
    - `Ctrl + M` (configurazione)
    - `Ctrl + B` (toggle barra pulsanti)
    - `Ctrl + F` (fullscreen)
    - `Ctrl + S` (annuncio vocale)
    - `Ctrl + Z` (switch visualizzazione)
- **Sintesi vocale** per annunci punteggio in italiano usando Web Speech API
- **Sistema di alert professionale** usando Wave UI per notifiche e conferme

#### Progressive Web App (PWA)
- **Installabile** come app nativa su smartphone, tablet e desktop
- **Funzionamento offline completo** grazie ai Service Worker
- **Auto-update automatico** per ricevere nuovi aggiornamenti senza reinstallazione
- **Display fullscreen** per massimizzare lo spazio visivo
- **Orientamento landscape ottimizzato** per utilizzo su tablet
- **Orientamento sensor landscape** con supporto rotazione 180°
- **Icone PWA personalizzate** (192x192 e 512x512)
- **Prevenzione scroll indesiderato** su mobile (overscroll-behavior)
- **Supporto 100dvh** e position:fixed per layout mobile stabile
- **Blocco scroll** per evitare ricariche accidentali con swipe-down

#### Build e Deployment
- **Build APK Android** tramite Capacitor per distribuzione nativa
- **Setup automatico icone Android** con script dedicato per multi-densità (ldpi, mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi)
- **Configurazione Capacitor** ottimizzata per landscape senza splash screen
- **Output unificato** in `/dist/android` per build Android
- **Base path configurabile** (`/segnap`) per deployment su sottocartelle

### Tecnologie e Dipendenze

#### Stack Tecnologico
- **Vue 3.4.38** - Framework JavaScript reattivo
- **Vite 5.4.10** - Build tool e dev server veloce
- **Wave UI 3.17.0** - Libreria UI components per alert e dialogs
- **NoSleep.js 0.12.0** - Prevenzione standby durante le partite
- **vite-plugin-pwa 0.20.5** - Plugin per generazione PWA
- **Capacitor 6.2.0** - Framework per build app native Android/iOS

#### Ambiente di Sviluppo
- **Node.js 20.x LTS** (consigliato v20.2.0)
- **npm 9.0.0+** per gestione dipendenze
- **NVM support** per gestione versioni Node.js
- **Hot Module Replacement (HMR)** in modalità sviluppo
- **Source maps** per debugging
- **Vue DevTools** supportato

#### Browser Supportati
- **Chrome/Chromium 90+** - Supporto completo (consigliato)
- **Firefox 88+** - Supporto completo

### Build e Comandi

#### Comandi Disponibili
- `npm run dev` - Server di sviluppo con hot-reload su http://localhost:5173
- `npm run build` - Build di produzione ottimizzata in `/dist`
- `npm run preview` - Anteprima locale della build di produzione

#### Output Build
- File statici ottimizzati e minificati
- Service Worker generato automaticamente
- PWA manifest configurato
- Assets con hash per cache busting
- Permessi automatici per cartella dist in ambiente Docker

### Documentazione
- **README.md completo** con:
  - Panoramica funzionalità
  - Requisiti di sistema dettagliati
  - Istruzioni di installazione e setup con NVM
  - Guida ai comandi per sviluppo e build
  - Tabella completa shortcuts tastiera
  - Configurazione PWA documentata
  - Spiegazione logica regolamentare pallavolo
  - Browser testati e supportati
- **Encoding corretto** per caratteri accentati italiani

### Miglioramenti Architetturali
- **Separazione componenti**: HomePage estratta in componente dedicato
- **Rimozione codice legacy**: eliminati file non utilizzati (HelloWorld.vue)
- **Refactoring CSS**: file style.css organizzato e ottimizzato
- **Gestione servizio migliorata**: variabile booleana `servHome` per gestione cambio servizio
- **Validazione input**: controlli su numeri di maglia e cambi giocatori
- **Gestione errori**: prevenzione incrementi a set concluso senza notifiche spam

### Note di Sviluppo
- **Orientamento sensor landscape**: permette rotazione 180° del dispositivo
- **Fix tentati audio mobile**: implementati ma richiedono ancora debug (WIP)
  - Aggiunto supporto @capacitor-community/text-to-speech per audio nativo
  - Implementato fallback Web API su desktop, plugin nativo su mobile
  - Correzione lingua da 'it_IT' a 'it-IT'
- **Java 17 → 21**: aggiornamento per compatibilità plugin TTS
- **ImageMagick in Dockerfile**: per generazione automatica icone Android

### Configurazione
- **Base path**: `/segnap` (configurabile in vite.config.js)
- **Tema PWA**: background `#eee`, theme color `#ffffff`
- **Display**: fullscreen landscape
- **Manifest name**: app_segnap
- **Short name**: segnap

---

## Architettura e Funzionamento Interno

### Come Funziona l'Applicazione Web

L'applicazione è una **Single Page Application (SPA)** completamente **client-side**:

- **Server**: Serve solo file statici (nessun backend, nessun database)
- **Esecuzione**: Tutto gira nel browser dell'utente
- **Stato**: Memorizzato solo nella RAM del browser (si perde al refresh)
- **Offline**: Funziona completamente offline dopo la prima visita (Service Worker)

#### Build e Deployment

```bash
npm run build
```

1. Vite compila il codice Vue/JavaScript
2. Ottimizza e minifica JavaScript e CSS
3. Genera Service Worker e manifest PWA
4. Output in `/dist` con file statici pronti

**Deploy**: Copia `/dist` su web server statico (nginx, Apache, Vercel, Netlify). Non serve Node.js, PHP o database sul server.

#### Funzionamento Runtime

**Prima visita:**
1. Browser scarica index.html dal server
2. Carica bundle JavaScript e CSS
3. Vue.js inizializza l'applicazione
4. Service Worker cachea tutti gli asset
5. App pronta (nessuna ulteriore chiamata al server)

**Visite successive:**
1. Service Worker serve i file dalla cache locale
2. App si avvia istantaneamente anche senza internet
3. In background verifica se esistono aggiornamenti
4. Aggiornamenti applicati al prossimo refresh

#### Gestione Stato

Tutto lo stato della partita vive nella memoria del browser:

```javascript
data() {
  return {
    sp: {
      punt: { home: 0, guest: 0 },
      set: { home: 0, guest: 0 },
      servHome: true,
      form: { home: ["1","2","3","4","5","6"], guest: ["1","2","3","4","5","6"] }
    }
  }
}
```

**Limitazioni:**
- Refresh della pagina azzera tutto lo stato
- Nessuna sincronizzazione tra dispositivi
- Nessuno storico partite

**Vantaggi:**
- Privacy totale (nessun dato esce dal dispositivo)
- Velocità massima (nessuna latenza di rete)
- Funzionamento offline completo

**Possibili evoluzioni:**
- Persistenza con localStorage
- Backend con database per multi-dispositivo
- WebSocket per sincronizzazione real-time

### Note Tecniche

**Problemi noti:**
- Audio mobile: sintesi vocale non funziona su alcuni dispositivi Android
- Persistenza: lo stato si perde al refresh della pagina
- Codice legacy: presenza di file HomePage duplicati

**Architettura futura:**
- Stato centralizzato con Pinia/Vuex
- Architettura client-server con WebSocket per display remoto
- Persistenza con localStorage o database
- Testing con Vitest e Cypress

---

## Informazioni sul Progetto

**Nome progetto**: Segnapunti Anto
**Descrizione**: Applicazione web PWA per tracciare i punteggi di partite di pallavolo in tempo reale
**Sviluppato per**: Team Antoniana
**Licenza**: Privata
**Repository**: https://github.com/[username]/segnapunti

---

### Come Leggere Questo Changelog

- **Funzionalità Principali**: nuove caratteristiche aggiunte all'applicazione
- **Tecnologie e Dipendenze**: stack tecnologico e versioni utilizzate
- **Build e Comandi**: istruzioni per compilare ed eseguire il progetto
- **Documentazione**: miglioramenti alla documentazione utente e sviluppatore
- **Miglioramenti Architetturali**: refactoring e ottimizzazioni del codice
- **Note di Sviluppo**: work in progress e problemi noti

---

### Supporto e Contributi

Per segnalare bug o richiedere funzionalità, aprire una issue nel repository del progetto.

Per contribuire al progetto:
1. Fork del repository
2. Creare un branch per la feature (`git checkout -b feature/nome-feature`)
3. Commit delle modifiche (`git commit -m 'Aggiunge nome-feature'`)
4. Push al branch (`git push origin feature/nome-feature`)
5. Aprire una Pull Request

---

**Data primo commit**: 2024
**Data rilascio 1.0.0**: 2026-02-10