davide
f5459f0871
La documentazione descriveva ancora il vecchio toggleTimeout (video in loop/sequenza); aggiornata a startTimeout/stopTimeout con scelta squadra/video, countdown e auto-chiusura server-side a 30s.
95 lines
7.3 KiB
Markdown
95 lines
7.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Scopo del progetto
|
|
|
|
**Segnapunti Anto** è una PWA per il segnapunti pallavolo in tempo reale. Un server Express/WebSocket gestisce lo stato di gioco; due interfacce Vue separate — **display** (tabellone pubblico) e **controller** (pannello operatore) — si sincronizzano via WebSocket.
|
|
|
|
## Comandi
|
|
|
|
```bash
|
|
npm run dev # Vite dev server — display: :5173/display, controller: :5173/controller
|
|
npm run serve # Build + avvio produzione — display: :3000/display, controller: :3000/controller
|
|
|
|
npm run test # Vitest in modalità watch
|
|
npm run test:all # Tutte le suite Vitest in una sola esecuzione
|
|
npm run test:unit # Solo unit + integration
|
|
npm run test:component # Test componenti Vue (happy-dom)
|
|
npm run test:stress # Load test (50+ client concorrenti)
|
|
npm run test:e2e # Playwright E2E (richiede npm run serve attivo)
|
|
npm run test:e2e:ui # Playwright con UI interattiva
|
|
```
|
|
|
|
Per eseguire un singolo file di test: `npx vitest run tests/unit/gameState.test.js`
|
|
|
|
## Architettura
|
|
|
|
```
|
|
Controller (Vue) ──WebSocket──┐
|
|
Display (Vue) ──WebSocket──┤── websocket-handler.js ── gameState.js
|
|
│ │
|
|
│ └── persist.js ── .segnapunti/state.json
|
|
```
|
|
|
|
**Tutta la logica di gioco** è in `src/gameState.js` come funzioni pure esportate:
|
|
- `createInitialState()` — restituisce lo stato iniziale
|
|
- `applyAction(state, action)` — reducer immutabile (deep-clone via `structuredClone`)
|
|
- `checkVittoria(state)` — condizioni di vittoria set (25 punti, vantaggio di 2; 15 punti nel set decisivo)
|
|
- `punteggio` / `setVinti` / `servizio` — derivano punteggio corrente, set vinti e chi serve dalla `striscia` (lo stato NON memorizza questi valori direttamente)
|
|
|
|
Punteggio, set e servizio si ricavano sempre dalla `striscia`: al primo punto di ogni set `applyAction('incPunt')` salva in `formInizio` uno snapshot della formazione di partenza (usato dal referto); `decPunt` lo rimuove se il set torna a 0-0.
|
|
|
|
`src/websocket-handler.js` riceve i messaggi WebSocket, valida che il mittente sia un `controller` (non un `display`), chiama `applyAction`, fa il broadcast del nuovo stato a tutti i client, poi invoca `onStateChange` per persistere su disco.
|
|
|
|
`src/wsMixin.js` è il mixin Vue lato client: gestisce connessione/riconnessione WebSocket (backoff esponenziale) ed espone i computed `punt`/`servHome`/`set`.
|
|
|
|
`src/referto.js` genera il referto di gara: `buildRefertoHtml(state, now)` è una funzione pura che restituisce l'HTML (testabile), mentre `generaReferto(state)` è il wrapper che apre la finestra con `window.open` e avvia la stampa.
|
|
|
|
`src/persist.js` carica/salva lo stato su `.segnapunti/state.json`. `src/server-utils.js` ricava gli IP di rete (`getNetworkIPs`, con sorgente iniettabile) e stampa gli URL all'avvio. `src/spot-utils.js` espone `listSpotVideos(spotDir)`, che elenca i `.mp4` (ordinati) della cartella `spot/`; ritorna `[]` se la cartella manca.
|
|
|
|
**Time out / spot video** — le action `startTimeout` (richiede `team`, `video` opzionale) e `stopTimeout` impostano/azzerano `state.timeout`, `timeoutTeam`, `timeoutVideo` e `timeoutStartedAt`. Il timestamp `startedAt` lo aggiunge `websocket-handler.js` (non il client), così `gameState.js` resta puro e deterministico; lo stesso handler arma un timer server-side di 30 secondi che invia automaticamente `stopTimeout` (sopravvive a refresh o disconnessione del controller). Sul controller il pulsante Time Out apre una modal per scegliere la squadra e uno dei video `.mp4` della cartella `spot/` nella root (non versionata), oppure nessun video; durante il time out il pulsante mostra il countdown e ripremerlo chiude in anticipo. Il display copre il tabellone con un overlay a tutto schermo con countdown: riproduce il video scelto (riallineandosi al punto giusto in caso di riconnessione a metà time out) e ripiega sulla scritta "TIME OUT <squadra>" se non c'è video o se il video finisce prima dei 30 secondi, con dissolvenza nell'ultimo secondo. La lista è esposta dall'endpoint HTTP `/spot/list` (JSON) e i file sono serviti staticamente da `/spot/<file>.mp4`, sia in produzione (`server.js`) sia in sviluppo (`vite-plugin-websocket.js`). I video partono con audio; se il browser blocca l'autoplay con suono si ripiega automaticamente su muto — per avere l'audio reale il browser del display (schermo senza input) va avviato in kiosk con autoplay consentito (es. Chrome `--autoplay-policy=no-user-gesture-required`).
|
|
|
|
`server.js` (Express) espone `createApp(distDir)` (solo routing, testabile) e `startServer(port)` (HTTP + WebSocket); serve entrambe le interfacce sulla porta 3000: `/display` → `dist/index.html`, `/controller` → `dist/controller.html`. Singolo endpoint WebSocket su `/ws`. L'avvio automatico parte solo se il file è eseguito come entrypoint.
|
|
|
|
In sviluppo, `vite-plugin-websocket.js` incorpora il server WebSocket dentro il dev server Vite con middleware di URL rewrite per `/display` e `/controller`.
|
|
|
|
## Vincoli di design
|
|
|
|
- **Tutta la logica sul server** — i client sono pura UI; il server è l'unica source of truth.
|
|
- **WebSocket role-based** — i client si registrano come `display` o `controller`; solo i controller possono inviare azioni.
|
|
- **Stato immutabile** — `applyAction` non muta mai lo stato, restituisce sempre un nuovo oggetto.
|
|
- **Un solo controller** — il design prevede un controller e un display attivi; non esiste conflict resolution per controller simultanei.
|
|
- **Stato persistente** — `src/persist.js` salva lo stato in `.segnapunti/state.json` dopo ogni azione e lo carica all'avvio del server.
|
|
|
|
## Layout dei test
|
|
|
|
| Suite | Percorso | Runner |
|
|
|-------|----------|--------|
|
|
| Unit | `tests/unit/` | Vitest + Node |
|
|
| Integration | `tests/integration/` | Vitest + Node |
|
|
| Component | `tests/component/` | Vitest + Happy-DOM |
|
|
| Stress | `tests/stress/` | Vitest + Node |
|
|
| E2E | `tests/e2e/` | Playwright (Chromium, Firefox, Mobile Chrome) |
|
|
|
|
I test E2E girano in serie (`workers: 1`) per evitare race condition sullo stato WebSocket. Eseguire `npm run serve` prima di `npm run test:e2e`.
|
|
|
|
## Deploy
|
|
|
|
Il progetto si distribuisce tramite Docker. L'immagine è pubblicata sul registry Gitea self-hosted (`santantonio.sytes.net`):
|
|
|
|
```bash
|
|
docker compose up -d # Avvia con immagine dal registry privato (porta 3000)
|
|
```
|
|
|
|
Il volume `./.segnapunti` persiste lo stato tra i riavvii del container.
|
|
|
|
## Istruzioni operative
|
|
|
|
- Per ogni nuova funzionalità: analizza come si inserisce nel flusso `action → applyAction → broadcast`, poi decidi se aggiungere un nuovo tipo di action o estendere uno esistente.
|
|
- Qualsiasi modifica alle regole di gioco va fatta esclusivamente in `src/gameState.js`.
|
|
- Qualsiasi modifica al protocollo WebSocket va fatta in `src/websocket-handler.js`.
|
|
- Aggiungere test unit in `tests/unit/gameState.test.js` per ogni nuovo action type o regola di gioco.
|
|
- Il codice deve essere scritto in italiano per commenti e nomi di variabili di dominio (es. `servHome`, `striscia`, `nomi`), ma in inglese per nomi tecnici standard (`state`, `action`, `handler`).
|
|
- Non inserire emoji in codice, UI (label, testi dei bottoni, banner) o commenti, a meno che l'utente non le richieda esplicitamente.
|