CRAPP/docs/modules/presenze.md

# Modulo — Presenze

**Stato:** implementato
**File principali:** `src/lib/presenze.ts`, `src/lib/presenze-mese.ts`, `src/components/crapp/RosaPresenze.tsx`,
`src/components/crapp/EventoCard.tsx`, `src/routes/api/public/sollecita-presenze.ts`

---

## Obiettivo

Permettere a ogni giocatore di confermare o rifiutare la propria partecipazione a un evento
(allenamento o partita) e mostrare a tutta la squadra chi ha risposto e come, sostituendo i
solleciti a voce o su chat esterne.

---

## Dati

Tabella `risposte_presenze` (PK composita `evento_id, giocatore_id`), letta e scritta da
`src/lib/presenze.ts`. È il modello "in uso" citato in `docs/DATABASE.md`; le tabelle
`eventi`/`presenze` previste da DD-014 non sono referenziate da nessun punto del codice
attuale.

Stati possibili (`Stato` in `src/lib/crapp-data.ts`): `presente`, `assente`, `forse`,
`ritardo`, `infortunato`. Solo `presente` e `ritardo` contano come presenza effettiva nelle
statistiche. L'assenza di una riga per `(evento, giocatore)` equivale a "non ha ancora
risposto". Lo stato `infortunato` è offerto solo per partite e allenamenti: sugli eventi
extra-campo (`tipo === "evento"`, es. cena di squadra) non è pertinente e resta escluso
ovunque — badge di riepilogo, gruppi elenco e bottoni di risposta — sia nella card
(`EventoCard`, tramite `includeInfortunato()` in `presenze.ts`) sia nella scheda di dettaglio
(`RosaPresenze`, prop `tipo`).

---

## Implementazione

```
Giocatore tocca uno stato in RosaPresenze
      ↓
useSalvaPresenza()        → src/lib/presenze.ts   (upsert o delete su risposte_presenze,
      ↓                                             onConflict evento_id+giocatore_id)
risposte_presenze (Supabase)
      ↓  letta da
useRispostePresenze()     → src/lib/presenze.ts   (1 query per sessione, staleTime 5 min,
      ↓                                             legge tutta la tabella)
RosaPresenze               → src/components/crapp/RosaPresenze.tsx
      ↑ montato da           (riepilogo, bottoni di risposta, gruppi per stato;
allenamento.$id.tsx /          prop `tipo` esclude "infortunato" per gli eventi extra-campo)
partita.$id.tsx / evento.$id.tsx

EventoCard                 → src/components/crapp/EventoCard.tsx
      ↑ home / calendario    (riga compatta di stati; senza `infortunato` se tipo `evento`)

--- statistiche ---
contaPresenzeGiocatore() / totaliEventiGiocatore()  → src/lib/presenze.ts
usePresenzeUltimoMese()                             → src/lib/presenze-mese.ts
                                                       (percentuale ultimi 30gg, da cache già in memoria)

contaPresenzeGiocatore() alimenta il campo `presenze` del `Giocatore` in `useRosa()`, mostrato
come StatTile nel profilo e in home (sezione «Colpo d'occhio», `index.tsx`).

contaPartiteGiocate() è contaPresenzeGiocatore() ristretto alle sole partite (non
allenamenti): alimenta `Giocatore.partiteGiocate`, usato nel sottotitolo della classifica
interna di Squadra quando si ordina per MVP — un conteggio di eventi generico (allenamenti
compresi) sarebbe fuorviante lì, perché l'MVP si vota solo alle partite.

--- sollecito (solo admin) ---
Bottone "Sollecita" (RosaPresenze.tsx) → POST /api/public/sollecita-presenze
      ↓
src/routes/api/public/sollecita-presenze.ts
      ├─ legge l'evento (eventi_app) e le risposte già date
      ├─ destinatariSollecito()  → src/lib/presenze.ts
      │  (attivi senza risposta o con "forse"; funzione pura, testata in unit)
      ├─ per ciascuno invia una push col testo cifrato nel payload
      │  (src/lib/webpush.server.ts)
      └─ elimina le iscrizioni push scadute (404/410)
```

> **Sollecito automatico (DD-040, non ancora implementato).** Il pulsante «Sollecita» e la route
> **restano**, ma `destinatariSollecito()` passa a guardare anche i convocati (convocati che non hanno
> risposto o hanno risposto «forse», o tutta la rosa se `convocati` è vuoto); in più un job `pg_cron` manda il sollecito **24, 12 e 6 ore prima** dell'evento a chi in
> quel momento non ha risposto o ha risposto «forse», tra i destinatari dell'evento (convocati, o
> tutta la rosa attiva; mai l'allenatore). Testo e finestre nel [catalogo](notifiche.md#catalogo-delle-notifiche).
> Il diagramma sopra descrive lo stato attuale.

Un evento conta ai fini delle statistiche di presenza solo se è di tipo `partita` o
`allenamento` e il giocatore è tra i convocati (o non ci sono convocati specificati, cioè
vale per tutta la rosa) — `eventiContanoPresenze()` in `presenze.ts`.

---

## Regole rispettate

- Aggiornamento ottimistico della cache locale dopo ogni salvataggio: nessuna rilettura dal
  server, la UI risponde subito.
- Il sollecito è **manuale** (da DD-040 si aggiungono tre solleciti automatici, che non lo sostituiscono): nessun cron nel repository lo richiama automaticamente, parte
  solo dal bottone admin, e la route verifica il ruolo lato server con `richiediAdmin`
  (DD-024).
- Ognuno risponde **solo per sé**, e non è più una regola della sola interfaccia: dalla
  migration `m11_scritture_per_ruolo` la policy di `risposte_presenze` lega la riga allo slot
  `giocatori_squadra` collegato all'account, con gli amministratori come sola deroga
  (DD-023). Verificato da `test/integration/permessi.test.ts`.

---

## Limiti noti

- Nessuna finestra temporale per rispondere: si può cambiare risposta anche a evento passato.
- La risposta di un evento passato resta modificabile: `risposte_presenze` non ha una
  finestra di chiusura, né in UI né in RLS.
- `useRispostePresenze()` legge sempre l'intera tabella, non filtrata per evento: adeguato per
  una singola squadra, da rivedere se il volume cresce molto.

---

## Evoluzioni possibili

- Filtrare la lettura delle presenze per evento invece di caricare tutta la tabella.