Aggiorna README.md

2026-01-28 13:31:42 +01:00
parent 9a808e566d
commit 2c6416bfe0
1 changed files with 246 additions and 5 deletions
--- a/README.md
+++ b/README.md
@@ -1,8 +1,249 @@
-# Vue 3 + Vite
-# nvm use v20.2.0
+# Segnapunti Anto

-This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+Applicazione web **Progressive Web App (PWA)** per tracciare i punteggi di partite di pallavolo in tempo reale.

-## Recommended IDE Setup
+---
+
+## 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

- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).