segnapunti/CHANGELOG.md

Changelog

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

Il formato si basa su Keep a Changelog, e questo progetto aderisce al Versionamento Semantico.

---

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

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:

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