Documenta le notifiche automatiche di palloni e presenze e i testi formali (DD-040)

Specifica, senza ancora toccare il codice: promemoria con «oggi/domani», turno
palloni a 12, 6 e 3 ore con revoca dell'incarico e senza email, solleciti
presenze a 24, 12 e 6 ore con gli stessi destinatari del pulsante. I pulsanti
manuali restano. Aggiunge la sezione «Testi delle notifiche» al modulo notifiche.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/DESIGN_DECISIONS.md

@@ -55,6 +55,7 @@ Serve a rispondere a domande del tipo:
 | [DD-037](#dd-037--i-promemoria-evento-ricordano-di-essere-già-stati-generati)                    | Promemoria evento senza ritorni       |
 | [DD-038](#dd-038--ogni-notifica-ha-tre-canali-la-push-dei-promemoria-parte-dal-worker)           | Tre canali per ogni notifica          |
 | [DD-039](#dd-039--lallenatore-non-riceve-i-promemoria-degli-eventi)                              | Niente promemoria all'allenatore      |
+| [DD-040](#dd-040--promemoria-con-oggi-o-domani-turno-palloni-e-solleciti-automatici)             | Palloni e solleciti automatici        |
 
 **In valutazione**
 
@@ -1710,6 +1711,9 @@ Vercel e avevano già i tre canali.
   allenatori, anche di giocatori non più attivi.
 - Le altre notifiche non cambiano canali e non ricevono push doppie.
 
+**Aggiornamento (30 settembre 2026)** — DD-040 esclude dalle email le notifiche del turno palloni: per
+quei tipi i canali sono due (push e in-app).
+
 **Riesame**  
 Se l'host di casa si rivela poco affidabile per una notifica sensibile al tempo come la push, o se
 il database dovesse comunque chiamare l'app per altro, valutare di nuovo la chiamata dal database
@@ -1755,3 +1759,96 @@ restano invariati.
 **Riesame**  
 Se l'allenatore dovesse poter partecipare a certi eventi (per esempio la cena), si riapre insieme
 alla sua possibilità di rispondere.
+
+### DD-040 — Promemoria con «oggi» o «domani», turno palloni e solleciti automatici
+
+**Data:** 30 settembre 2026  
+**Stato:** Accettata (solo documentata: codice e migration `m26` non ancora scritti; fino al rilascio
+l'app si comporta come in 1.2.0)
+
+**Contesto**  
+Quattro notifiche su sei partivano da un pulsante premuto da un admin (DD-025 per i palloni): se nessuno
+lo premeva, nessuno veniva avvisato. I testi erano inoltre brevi e informali, e i promemoria non dicevano
+quando e dove. Si vuole che turno palloni e sollecito presenze partano anche da soli, a orari fissi prima
+dell'evento, e che i testi siano più formali e completi. I testi nuovi sono nel
+[catalogo](modules/notifiche.md#testi-delle-notifiche).
+
+**Decisione**
+
+1. **Promemoria a 24 e 3 ore:** nuovo testo con data, ora e luogo. La parola nel titolo e nella riga
+   «Data» è **«domani»** se la data dell'evento è quella di domani (fuso `Europe/Rome`), **«oggi»**
+   altrimenti. Vale per entrambi i promemoria, quindi anche quello a 3 ore di un evento dopo la
+   mezzanotte dice «domani». La parola la calcola la funzione SQL quando genera la notifica.
+2. **Turno palloni automatico.** Un job `pg_cron` ogni 15 minuti avvisa per gli eventi di tipo allenamento
+   o partita, in tre tempi con finestre che non si sovrappongono: **12 ore** (tra 12 e 6 ore prima
+   dell'inizio), **6 ore** (tra 6 e 3) e **3 ore** (meno di 3). Parte **solo se per l'evento c'è un
+   incaricato confermato** in `turni_palloni`: le proposte automatiche di `completaTurni()` non salvate non
+   contano. Gli avvisi sono due, con lo stesso testo nei tre tempi: «incarico assegnato» all'incaricato e
+   «riconsegna» a chi aveva i palloni all'evento precedente, se è un'altra persona.
+   - **Pulsante manuale.** «Avvisa chi è di turno» e la route `promemoria-palloni` **restano**: tipo
+     `turno_palloni`, testo nuovo, push mandata dalla route e non dalla coda. È una notifica in più;
+     riceverne due (automatica e manuale) va bene.
+   - **Incaricato cambiato dopo un avviso.** Il nuovo incaricato riceve il suo avviso al giro successivo,
+     con il tipo della finestra in cui cade. Chi aveva già ricevuto un avviso e non è più destinatario
+     riceve **una sola volta** «Turno palloni: incarico revocato» (`turno_palloni_revocato`), se
+     l'evento non è iniziato. Il job lo scopre confrontando i destinatari attuali con le notifiche
+     `turno_palloni*` già scritte per l'evento, senza trigger su `turni_palloni`.
+   - **Niente email.** Gli avvisi palloni (automatici, revoca e pulsante) arrivano come push e nel centro
+     notifiche, **non per email**: il trigger `notifiche_utente_accoda_email` salta i tipi
+     `turno_palloni`, `turno_palloni_12h`, `_6h`, `_3h` e `turno_palloni_revocato`. È un'eccezione a
+     DD-038 («ogni notifica ha tre canali») solo per questi tipi; l'interruttore «Email» non cambia.
+3. **Sollecito presenze automatico in tre tempi.** Lo stesso job manda il sollecito **24 ore** (tra 24 e
+   12 ore prima), **12 ore** (tra 12 e 6) e **6 ore** (meno di 6) prima, al massimo una notifica per
+   giocatore e per tipo. Lo riceve solo chi in quel momento non ha risposto o ha risposto «forse» ed è
+   destinatario dell'evento: i convocati, o tutta la rosa attiva se `convocati` è vuoto, mai l'allenatore.
+   Chi risponde presente, assente o in ritardo smette di riceverli; chi resta su «forse» li riceve tutti e
+   tre. Un evento creato a meno di 12 ore dall'inizio riceve solo il sollecito della sua finestra.
+   - **Pulsante manuale.** «Sollecita» e la route `sollecita-presenze` **restano**, anche per l'allenatore:
+     tipo `sollecita_presenze`, push mandata dalla route, testo nuovo con in più la riga «Richiesta di:
+     _Nome_». I destinatari sono **gli stessi dell'automatico** (convocati senza risposta o con «forse»);
+     oggi la route guarda invece tutti i giocatori attivi.
+4. **Stessa infrastruttura dei promemoria** (DD-037, DD-038): le notifiche automatiche nascono nel
+   database, il registro `promemoria_eventi_generati` impedisce i doppioni anche se il giocatore le
+   elimina, la push la manda il worker dalla coda `notifiche_push_coda`, l'email (quando c'è) nasce dal
+   trigger su `notifiche_utente`. Tipi nuovi: `sollecita_presenze_24h`, `_12h`, `_6h`;
+   `turno_palloni_12h`, `_6h`, `_3h` e `turno_palloni_revocato`. Il `turno_palloni` del pulsante resta.
+5. **Migration `m26`:** estende i `CHECK` sui tipi di `notifiche_utente` e del registro, il trigger della
+   coda push, il trigger della coda email (che salta i tipi dei palloni) e ridefinisce la funzione dei
+   promemoria. Le funzioni nuove riusano `giocatori_destinatari_evento()`.
+
+**Alternative scartate**
+
+- Togliere i pulsanti manuali (turno palloni e sollecito) una volta arrivati gli automatici → scartata su
+  indicazione esplicita: servono all'admin per rimandare un avviso o sollecitare fuori dagli orari fissi.
+- Mandare tutti i solleciti (o gli avvisi palloni) a un evento creato tardi → scartata: più messaggi nel
+  giro di pochi minuti sono rumore.
+- «Domani» e «oggi» fissi nei due testi → scartata: il job delle 24 ore scatta anche per eventi che
+  iniziano oggi, e quello delle 3 ore attraversa la mezzanotte.
+- Calcolare il testo nell'app invece che nel database → scartata: le notifiche nascono nei job `pg_cron`,
+  che non chiamano l'app (DD-038).
+- Spostare nel worker il calcolo di evento precedente e successivo dei palloni → scartata: un secondo
+  punto che scrive in `notifiche_utente`, per un vantaggio piccolo.
+- Ritirare l'avviso già consegnato al vecchio incaricato → scartata: per la push non si può, e in-app
+  confonde. Si manda la revoca.
+
+**Conseguenze**
+
+- Cambia la regola «quattro notifiche su sei dipendono da un gesto manuale»: restano solo manuali il
+  messaggio dello staff e il sondaggio pre-partita; per turno palloni e sollecito gli automatici si
+  aggiungono ai pulsanti, e un giocatore può ricevere lo stesso avviso due volte.
+- **Logica duplicata:** «evento precedente» e «evento successivo» per i palloni, oggi in `palloni-core.ts`
+  (usato dal pulsante e dalla schermata), vengono riscritti in SQL per i job. Se si cambia una regola in
+  una sola delle due versioni, pulsante e job danno risposte diverse: un test di integrazione le confronta
+  sugli stessi dati.
+- `destinatariSollecito()` riceve anche i convocati e serve al sollecito manuale; un giocatore non
+  convocato non è più sollecitato. `avvisiPalloniEvento()` resta come riferimento per i test finché il SQL
+  non la sostituisce del tutto.
+- Se un incaricato revocato viene poi riassegnato non riceve un secondo avviso, perché il registro lo ha
+  già generato per quella finestra: la revoca resta l'ultima notifica che ha letto.
+- Le mail automatiche per evento e giocatore sono al massimo **cinque** (due promemoria, tre solleciti),
+  più quelle dei pulsanti (sollecito, sondaggio). Il turno palloni non ne manda.
+- Il testo dei promemoria già generati non cambia (il registro impedisce di rigenerarli).
+
+**Riesame**  
+Dopo la prima stagione di uso: se i solleciti o gli avvisi palloni risultano troppi, ridurre le
+finestre o escludere chi ha risposto «forse» più di una volta.