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.

---

[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