davideandClaude Sonnet 5.5
cdf8b144e2
La migration m27 riduce il job automatico alla sola fascia delle 3 ore: l'avviso arriva una volta a chi deve portare i palloni e a chi li deve prendere. I tipi turno_palloni_12h e _6h restano ammessi per le notifiche già generate e per la revoca. Migration applicata in produzione. Test di integrazione aggiornati (nessun avviso a 4,5 e 9 ore); documentati DD-042, moduli, DATABASE, ROADMAP, glossario e changelog. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
100 lines
5.5 KiB
Markdown
100 lines
5.5 KiB
Markdown
# Modulo — Palloni
|
|
|
|
**Stato:** implementato
|
|
**File principali:** `src/lib/palloni.ts`, `src/lib/palloni-core.ts`,
|
|
`src/components/crapp/TurnoPalloni.tsx`, `src/components/crapp/PromemoriaPalloni.tsx`,
|
|
`src/routes/api/public/promemoria-palloni.ts`
|
|
|
|
---
|
|
|
|
## Obiettivo
|
|
|
|
Gestire un turno a rotazione condiviso per chi porta e riporta i palloni ad allenamenti e
|
|
partite, con proposta automatica, possibilità di modifica manuale e avvisi push, nel centro
|
|
notifiche e senza email 3 ore prima dell'evento (DD-040, DD-042). Gli eventi extra-campo (`tipo === "evento"`, es. cena di squadra) e i
|
|
compleanni non c'entrano: non richiedono palloni.
|
|
|
|
---
|
|
|
|
## Dati
|
|
|
|
Tabella `turni_palloni` (`evento_id`, `giocatore_id`, `aggiornato_da`, `aggiornato_il`) —
|
|
contiene solo i turni **confermati manualmente**; le proposte automatiche non salvate non vi
|
|
compaiono.
|
|
|
|
---
|
|
|
|
## Implementazione
|
|
|
|
- `eventiPalloni()` (`palloni-core.ts`) ordina gli eventi per data, poi ora, poi id (lo stesso ordine dei job SQL di `m26`: «evento precedente» e «successivo» dipendono da qui) ed è il filtro comune a tutta la pipeline (proposte,
|
|
conteggi, serie, promemoria): include solo `tipo === "partita"` e `tipo === "allenamento"`,
|
|
scarta eventi extra-campo e compleanni.
|
|
- `completaTurni()` (`palloni-core.ts`) propone, per ogni **partita** senza turno già salvato,
|
|
il candidato con meno turni fatti, poi quello che non lo fa da più tempo, poi per ordine
|
|
alfabetico — un algoritmo greedy, non un ordine fisso né solo per data. Gli **allenamenti**
|
|
non ricevono proposta automatica: restano «da assegnare» finché qualcuno non sceglie un
|
|
incaricato in `TurnoPalloni` (scelta della squadra).
|
|
- `useAssegnaTurno()` (`palloni.ts`) conferma una proposta o riassegna manualmente, con
|
|
upsert su `evento_id`.
|
|
- Il conteggio "quante volte hai portato i palloni" mostrato nel profilo e nei badge è
|
|
ricalcolato a runtime da `conteggioTurni()` sui **soli turni confermati** (`turniSalvati`
|
|
in `rosa.ts`) — non è uno storico in tabella dedicata, ma non include le proposte
|
|
automatiche di `completaTurni()` (quelle restano solo per la UI di rotazione,
|
|
`TurnoPalloni.tsx`/`PromemoriaPalloni.tsx`). Conta solo gli eventi già passati (`e.data <
|
|
oggi`, stesso criterio delle presenze): un turno assegnato in anticipo per un allenamento
|
|
futuro non è ancora "portato", quindi non sale finché quel giorno non arriva.
|
|
- `serieConsecutivaPalloni()` (`palloni-core.ts`) calcola le volte **consecutive** in cui il
|
|
giocatore ha portato i palloni (`Giocatore.seriePalloni` in `rosa.ts`), mostrate nel
|
|
sottotitolo della classifica interna di Squadra quando si ordina per Palloni. Stesso
|
|
criterio "solo eventi già passati" di `conteggioTurni()`; un evento passato senza turno
|
|
confermato non spezza la serie di nessuno (viene saltato, non conta come "non portati").
|
|
- `TurnoPalloni.tsx` mostra/assegna il turno sulla card di un evento; `PromemoriaPalloni.tsx`
|
|
è il banner in Home per il giocatore di turno.
|
|
|
|
---
|
|
|
|
## Route API pubblica `/api/public/promemoria-palloni`
|
|
|
|
> **Affiancata da un invio automatico (DD-040, migration `m26`).** Oltre al pulsante, un job
|
|
> `pg_cron` ogni 15 minuti manda l'avviso **una sola volta, 3 ore prima** dell'evento (DD-042, migration `m27`), solo se per l'evento c'è un
|
|
> incaricato confermato in `turni_palloni`. Il pulsante e la route **restano**, con tipo
|
|
> `turno_palloni` e push dalla route. I due destinatari e i testi nuovi («incarico assegnato» /
|
|
> «riconsegna», validi per il pulsante e per i job, più la revoca se l'incaricato cambia) sono nel
|
|
> [catalogo](notifiche.md#testi-delle-notifiche). Il resto della sezione descrive il pulsante.
|
|
|
|
La fa partire un **amministratore** dal pulsante «Avvisa chi è di turno» dentro il riquadro
|
|
palloni dell'evento (`TurnoPalloni.tsx`), riservato agli admin (DD-025). Riceve l'`eventoId`,
|
|
e `avvisiPalloniEvento()` calcola i due destinatari di _quell'evento_: chi deve **prendere** i
|
|
palloni e chi deve **riportarli** (l'incaricato dell'evento precedente), con un testo diverso
|
|
per ciascuno.
|
|
|
|
Titolo e testo viaggiano cifrati dentro la push, quindi il service worker li mostra senza
|
|
nessuna chiamata di rete. Stesso meccanismo di `apri-sondaggio` (vedi
|
|
[Notifiche](notifiche.md)).
|
|
|
|
---
|
|
|
|
## Limiti noti
|
|
|
|
- **L'avviso automatico parte solo con un incaricato confermato** (DD-040): per una partita la
|
|
proposta di `completaTurni()` non salvata non basta, e senza incaricato non parte nulla. Il pulsante
|
|
dell'admin (DD-025) resta per rimandare l'avviso o per una proposta non ancora confermata. `destinatariPromemoriaPalloni()` — la versione "chi è di
|
|
turno oggi" — resta in `palloni-core.ts` ma non la chiama più nessuno.
|
|
- La rotazione non considera le assenze dichiarate: può proporre il turno a chi ha risposto
|
|
"assente" o "infortunato" per quell'evento.
|
|
- **`conteggioTurni()` non filtra per tipo evento** (a differenza di `eventiPalloni()`, che
|
|
include solo partite e allenamenti): guarda solo `e.data < oggi`. Un turno registrato per
|
|
errore su un evento fuori dal dominio "richiede i palloni" conterebbe comunque per il badge
|
|
Sherpa dei palloni (`badge.md` § Problemi noti). Rischio basso — l'UI non offre questa
|
|
combinazione, dato che né `TurnoPalloni` né i promemoria automatici propongono più un turno
|
|
per eventi extra-campo o compleanni — ma il comportamento attuale è pinnato da un test
|
|
dedicato in `palloni-core.test.ts`.
|
|
|
|
---
|
|
|
|
## Evoluzioni possibili
|
|
|
|
- Versionare il cron (es. una migration con `cron.schedule`) invece di configurarlo solo
|
|
lato dashboard.
|
|
- Escludere dalla rotazione chi ha già dichiarato assenza per l'evento.
|