attilio/segnapunti
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs(readme): riscrive documentazione con guida utente e architettura 2.0.0

Browse Source
This commit is contained in:
Davide Grilli
2026-05-12 14:46:35 +02:00
parent 496266039b
commit 4bfc12fb00
1 changed files with 183 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+183 -150
View File
@@ -1,213 +1,246 @@
# Segnapunti Anto # Segnapunti Anto
Applicazione web **fullstack real-time** per il tracciamento dei punteggi di partite di pallavolo, installabile come PWA. ![Version](https://img.shields.io/badge/versione-2.0.0-blue)
![Node](https://img.shields.io/badge/node-%3E%3D18-green)
![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)
![License](https://img.shields.io/badge/licenza-privata-lightgrey)
Segnapunti digitale in tempo reale per partite di pallavolo. Un server centrale gestisce lo stato della partita; un **display** mostra il tabellone pubblico e un **controller** (smartphone o tablet) permette all'operatore di gestire punti, formazioni e cambi.
--- ---
## Panoramica ## Indice
**Segnapunti Anto** è un'applicazione fullstack per il tracciamento del punteggio durante partite di pallavolo, ottimizzata per tablet e smartphone in contesto sportivo. - [Architettura](#architettura)
- [Guida utente](#guida-utente)
- [Funzionalità](#funzionalità)
- [Shortcuts tastiera](#shortcuts-tastiera)
- [Terminal Controller CLI](#terminal-controller-cli)
- [Deploy con Docker](#deploy-con-docker)
- [Sviluppo](#sviluppo)
- [Test](#test)
### Architettura ---
Il sistema è composto da un **backend Node.js/Express** e due interfacce web separate: ## Architettura
| Interfaccia | Porta | Ruolo | ```
|-------------|-------|-------| Controller (smartphone) ──WebSocket──┐
| **Display** | 3000 | Tabellone pubblico — mostra punteggi, formazioni e storico | Display (schermo) ──WebSocket──┤── Server Node.js ── gameState.js
| **Controller** | 3001 | Pannello operatore — invia azioni e gestisce la partita | CLI (terminale) ──WebSocket──┘ │
└── .segnapunti/state.json
```
Le due interfacce comunicano tramite **WebSocket** (`/ws`): ogni azione del Controller viene elaborata dal server e trasmessa in broadcast a tutti i client connessi. Il server è l'unica fonte di verità. Ogni azione del controller viene elaborata e trasmessa in broadcast a tutti i client connessi. Lo stato viene salvato su disco ad ogni azione e ricaricato all'avvio, sopravvivendo ai riavvii del server.
La logica di gioco risiede interamente **lato server** (`gameState.js`), con aggiornamenti di stato immutabili. Il frontend Vue 3 è puramente reattivo: riceve lo stato e lo visualizza senza gestirne la consistenza. | Percorso | Ruolo |
|---|---|
| `http://<host>:3000/display` | Tabellone pubblico — sola lettura |
| `http://<host>:3000/controller` | Pannello operatore — gestione partita |
| `ws://<host>:3000/ws` | WebSocket endpoint |
In produzione, entrambi i server sono gestiti da un unico processo Node.js (`server.js`) e l'intera applicazione è containerizzabile via Docker. Il frontend è installabile come **PWA** (service worker, manifest, modalità fullscreen landscape) per utilizzo kiosk su dispositivi sportivi. ---
## Guida utente
### Scenario tipico: schermo fisso + smartphone operatore
#### 1. Avvia il server
```bash
docker compose up -d
```
All'avvio il terminale mostra gli URL locali e di rete.
#### 2. Apri il display
Collega il PC/server allo schermo via HDMI e apri il browser a schermo intero:
```
http://localhost:3000/display
```
Se il display è su un dispositivo separato nella stessa rete:
```
http://<IP-del-server>:3000/display
```
> **Trovare l'IP:** il server lo stampa all'avvio. In alternativa usa `ip a` su Linux.
#### 3. Apri il controller sullo smartphone
Connetti il telefono alla stessa rete Wi-Fi e apri:
```
http://<IP-del-server>:3000/controller
```
> **Installazione come app:** nel browser tocca *"Aggiungi a schermata Home"* per avere il controller come icona dedicata.
--- ---
## Funzionalità ## Funzionalità
### Gestione partita in tempo reale ### Display
- Tracciamento punti home/guest con indicatore di servizio
- Gestione set e storico punti (striscia) - Nomi squadre con indicatore di servizio
- Blocco azioni quando il set è già vinto - Punteggio del set corrente (grande, leggibile da lontano)
- Contatore set vinti
- Striscia storica punti del set in corso, scorrevole verso destra
- Modalità formazioni: posizioni dei 6 giocatori in campo
- Indicatore connessione WebSocket (scompare quando connesso, rosso lampeggiante se disconnesso)
### Controller
- **Punti** — `+1` per casa e ospite, con annullamento dell'ultimo punto
- **Dialog set vinto** — appare automaticamente al raggiungimento dei 25 punti (o 15 nel tie-break); permette di confermare il set o annullare l'ultimo punto
- **Formazioni** — configura i numeri di maglia; la rotazione avviene automaticamente al cambio palla
- **Cambi** — dialog `IN → OUT` con validazione
- **Servizio** — cambio manuale (disponibile solo a 0-0)
- **Visualizzazione** — alterna tra punteggio grande e formazioni in campo
- **Striscia** — mostra/nasconde lo storico punti sul display
- **Reset** — azzera la partita (richiede conferma)
### Regole pallavolo integrate ### Regole pallavolo integrate
- Set normali: vittoria a 25 con almeno 2 punti di scarto
- Set decisivo (5° set): vittoria a 15 con almeno 2 punti di scarto
- Modalità partita `2/3` o `3/5`
### Formazioni e cambi | Set | Condizione di vittoria |
- Gestione formazione a 6 giocatori per squadra |---|---|
- Rotazione automatica al cambio palla | Set 1–4 (modalità 3/5) o 1–2 (modalità 2/3) | Primo a **25** con almeno 2 punti di scarto |
- Dialog cambi con validazione `IN → OUT` | Set decisivo (tie-break) | Primo a **15** con almeno 2 punti di scarto |
### Controlli e personalizzazione
- Configurazione nomi squadre
- Inversione ordine di visualizzazione squadre
- Toggle punteggio/formazioni e visibilità striscia storico
- Sintesi vocale del punteggio (Web Speech API)
--- ---
## Requisiti ## Shortcuts tastiera
### Ambiente di sviluppo > Valide sul controller da browser desktop.
| Requisito | Versione minima | Consigliata | | Tasto | Azione |
|-----------|-----------------|-------------| |---|---|
| **Node.js** | `>= 18.19.0` | `24 LTS` | | `Ctrl + ↑` | Punto casa |
| **npm** | `>= 9` | — | | `Ctrl + ↓` | Annulla ultimo punto |
| **RAM** | 2 GB | 4 GB | | `Shift + ↑` | Punto ospite |
| **OS** | Linux, macOS, Windows | — | | `Ctrl + ←` | Cambia servizio (solo a 0-0) |
| `Ctrl + M` | Apri configurazione |
| `Ctrl + C` | Cambi squadra casa |
| `Shift + C` | Cambi squadra ospite |
| `Ctrl + Z` | Toggle punteggio / formazioni |
| `Ctrl + S` | Annuncio vocale punteggio |
| `Ctrl + B` | Mostra/nascondi barra pulsanti |
| `Ctrl + F` | Fullscreen |
### Test E2E ---
I test end-to-end richiedono i browser Playwright. Su Linux potrebbero essere necessarie dipendenze di sistema aggiuntive. ## Terminal Controller CLI
Alternativa al controller browser, utile da terminale.
```bash ```bash
npx playwright install chromium firefox npm run cli # server su porta 3000
# Linux (con dipendenze di sistema): npm run cli:dev # dev server su porta 5173
# npx playwright install --with-deps chromium firefox node cli.js <porta> # porta custom
``` ```
### Requisiti browser (utente finale) | Comando | Alias | Effetto |
|---|---|---|
| `punto casa` | `+`, `pc` | Punto alla squadra di casa |
| `punto ospite` | `-`, `po` | Punto alla squadra ospite |
| `undo` | `u` | Annulla l'ultimo punto |
| `set casa` / `set ospite` | — | Incrementa contatore set |
| `serv` | — | Cambia servizio (solo a 0-0) |
| `nomi <casa> <ospite>` | — | Imposta i nomi delle squadre |
| `modalita 2/3` / `3/5` | — | Modalità partita |
| `reset` | — | Azzera la partita (chiede conferma) |
| `stato` | — | Mostra punteggio nel terminale |
| `help` | — | Lista comandi |
| `exit` | `q` | Chiude il CLI |
| API | Utilizzo | Necessità | `Tab` per completamento automatico — `↑ ↓` per navigare nella history dei comandi.
|-----|----------|-----------|
| JavaScript ES6+ | Moduli, async/await | Obbligatorio |
| WebSocket | Sincronizzazione stato live | Obbligatorio |
| Service Worker | Supporto PWA offline | Consigliato |
| Web Speech API | Annunci vocali punteggio | Opzionale |
**Browser testati:** Chrome/Chromium, Firefox, Mobile Chrome (Playwright Pixel 5).
--- ---
## Installazione ## Deploy con Docker
### Prima installazione
```bash ```bash
git clone https://santantonio.sytes.net/attilio/segnapunti.git docker compose up -d
cd segnapunti ```
npm install
Lo stato viene salvato nel volume Docker `segnapunti-state` e sopravvive ai riavvii del container.
### Aggiornamento a nuova versione
```bash
docker compose pull && docker compose up -d
```
### Build e pubblicazione immagine
```bash
docker build \
-t santantonio.sytes.net/attilio/segnapunti:2.0.0 \
-t santantonio.sytes.net/attilio/segnapunti:latest .
docker push santantonio.sytes.net/attilio/segnapunti:2.0.0
docker push santantonio.sytes.net/attilio/segnapunti:latest
``` ```
--- ---
## Sviluppo ## Sviluppo
### Dev server ### Requisiti
```bash | Strumento | Versione minima |
npm run dev |---|---|
``` | Node.js | >= 18 |
| npm | >= 9 |
Avvia il server Vite con hot reload:
- `http://localhost:5173/` — Display
- `http://localhost:5173/controller.html` — Controller
### Build di produzione
```bash
npm run build
```
Genera la cartella `dist/` con asset ottimizzati, manifest e service worker PWA.
### Avvio in produzione (locale)
```bash
npm run serve
```
Espone i due server:
- `http://localhost:3000` — Display
- `http://localhost:3001` — Controller
---
## Terminal Controller (CLI)
Il CLI è un controller da terminale che si connette al server via WebSocket e permette di gestire la partita senza browser.
### Avvio ### Avvio
```bash ```bash
# Modalità produzione (server su porta 3000) npm install
npm run cli npm run dev
# Modalità sviluppo (server Vite su porta 5173)
npm run cli:dev
# Porta custom
node cli.js <porta>
``` ```
Il CLI richiede che il server sia già in esecuzione in un altro terminale. | URL | Interfaccia |
|---|---|
| `http://localhost:5173/display` | Display |
| `http://localhost:5173/controller` | Controller |
Lo stato viene salvato in `.segnapunti/state.json` anche in modalità dev.
### Comandi disponibili ### Comandi disponibili
#### Punteggio | Comando | Descrizione |
|---|---|
| Comando | Alias | Effetto | | `npm run dev` | Dev server con hot reload |
|---------|-------|---------| | `npm run build` | Build di produzione in `dist/` |
| `punto casa` | `+`, `pc` | Assegna un punto alla squadra di casa | | `npm run serve` | Build + avvio server produzione |
| `punto ospite` | `-`, `po` | Assegna un punto alla squadra ospite | | `npm run cli` | Terminal controller (porta 3000) |
| `undo` | `u` | Annulla l'ultimo punto assegnato | | `npm run cli:dev` | Terminal controller (porta 5173) |
#### Set
| Comando | Effetto |
|---------|---------|
| `set casa` | Incrementa il contatore set della squadra di casa |
| `set ospite` | Incrementa il contatore set della squadra ospite |
#### Partita
| Comando | Effetto |
|---------|---------|
| `serv` | Cambia il servizio (disponibile solo se il punteggio è 0-0) |
| `reset` | Resetta la partita — chiede conferma prima di procedere |
| `nomi <casa> <ospite>` | Imposta i nomi delle squadre (es. `nomi Antoniana Teate`) |
| `modalita 2/3` | Imposta la modalità best-of-3 |
| `modalita 3/5` | Imposta la modalità best-of-5 |
#### Informazioni
| Comando | Alias | Effetto |
|---------|-------|---------|
| `stato` | — | Mostra il punteggio corrente nel terminale |
| `help` | — | Mostra la lista dei comandi |
| `exit` | `q` | Chiude il CLI |
### Note
- **Tab**: completamento automatico dei comandi
- **Freccia su/giù**: navigazione nella history dei comandi (ultime 100 voci)
- Il Display nel browser si aggiorna in tempo reale ad ogni comando inviato
--- ---
## Test ## Test
La suite di test copre tutti i livelli dell'applicazione: | Comando | Descrizione |
|---|---|
| `npm run test:unit` | Unit + integration (Vitest) |
| `npm run test:component` | Componenti Vue (Happy-DOM) |
| `npm run test:stress` | Load test WebSocket (50+ client) |
| `npm run test:all` | Tutti i test tranne E2E |
| `npm run test:e2e` | Playwright — Chromium, Firefox, Mobile Chrome |
| Suite | Comando | Descrizione | > I test E2E richiedono il server in esecuzione (`npm run serve`) e i browser Playwright installati:
|-------|---------|-------------| > ```bash
| Tutti | `npm run test:all` | Unit + integration + component + stress | > npx playwright install chromium firefox
| Unit + integration | `npm run test:unit` | Logica di gioco e WebSocket | > ```
| Component | `npm run test:component` | Componenti Vue |
| Stress | `npm run test:stress` | Load test WebSocket |
| E2E | `npm run test:e2e` | Playwright (chromium, firefox, mobile) |
Per la guida completa ai test, consultare [`tests/README.md`](tests/README.md).
--- ---
## Docker ## Changelog
```bash Vedere [CHANGELOG.md](CHANGELOG.md) per la storia delle versioni.
docker-compose up --build
```
Espone le porte `3000` (Display) e `3001` (Controller).