CRAPP/docs/modules/palloni.md

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 a 12, 6 e 3 ore dall'evento (DD-040). 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 12, 6 e 3 ore prima dell'evento, 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. 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).

---

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.