Aggiunto il technical case study per i selezionatori IT, con schemi e screenshot

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-22 17:18:16 +01:00
1 parent 58a8693ceb
commit 6bb9d7e0d8
5 files changed
+433

No files matched your search

Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 166 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

+433
View File
@@ -0,0 +1,433 @@
# CrAPP — Technical case study
**Autore:** Davide Grilli · davide.grilli@outlook.com
**Progetto:** applicazione web per la gestione di una squadra di pallavolo, in produzione con utenti reali.
**Ruolo:** sviluppo full-stack (interfaccia, database, notifiche), insieme a Ivan Cacciari.
**Codice:** <https://github.com/ivancacciari1995-a11y/CRAPP>
> **In una frase:** un'applicazione full-stack completa (accesso con Google, database con permessi per ruolo, notifiche push ed email, valutazione delle partite in diretta), messa in produzione, testata e documentata.
**In sintesi:** sezioni 1–3 per una visione d'insieme; la sezione 5 entra nelle scelte tecniche, ciascuna con problema, soluzione e motivo; il glossario (sezione 8) spiega i termini specialistici.
---
## 1. In breve
| Cosa | Dato |
| -------------- | -------------------------------------------------------------------------------------------------- |
| Stato | In produzione, usata da una squadra reale (~17 utenti), versione 1.6.3 |
| Periodo | Primi commit 6 agosto 2026, versione 1.0.0 il 24 settembre, ultimo aggiornamento 22 novembre |
| Team | Due persone: 295 commit su 344 sono miei, il resto di Ivan Cacciari |
| Frontend | React 19, TypeScript, TanStack Start (rendering lato server), Vite, Tailwind CSS 4 |
| Backend | Supabase (PostgreSQL, autenticazione, archivio file); hosting su Vercel |
| Dimensioni | 109 file TypeScript (~17.700 righe), 50 migration SQL (~3.600 righe), oltre 60 policy di sicurezza |
| Qualità | 77 file di test su tre livelli, 54 decisioni di progetto scritte, 16 schede di modulo |
| Servizio extra | Un worker per le email, in un container Docker su un Raspberry Pi |
## 2. Cosa dimostra
| Competenza | Dove si vede |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| Sviluppo full-stack end to end | Dal database con RLS alla PWA, fino al worker in container e al job pianificato |
| Sicurezza applicativa | RLS per ruolo, test dei permessi con utenti veri, chiusura delle route aperte (DD-024) |
| Modellazione dati | 50 migration additive, vincoli a database, trigger di pulizia a cascata |
| Testing | 77 file di test su tre livelli, con test che rifiutano di toccare la produzione |
| Attenzione ai costi cloud | Regole di efficienza imposte per costruzione, eccezioni motivate |
| Affidabilità e casi limite | Sessioni con scadenza, fusi orari, timestamp non validi |
| Documentazione e comunicazione | 54 decisioni, 16 schede di modulo, indice e regole di manutenzione |
| Lavoro in team e con AI | Due sviluppatori, flusso di branch, regole scritte per gli assistenti |
| Operatività | Stack locale per le prove distruttive, migration verificate prima del push, backup e ripristino |
## 3. Il problema e il risultato
Una squadra di pallavolo gestisce tutto con chat, fogli di calcolo e carta: presenze rincorse su WhatsApp, scout delle partite su carta, certificati medici che scadono senza che nessuno se ne accorga, nessun promemoria per chi deve portare i palloni.
La soluzione è **una sola app sul telefono di tutti**, installabile dalla schermata Home senza passare dagli store. Due vincoli hanno guidato quasi ogni scelta tecnica:
- **facile da usare:** mobile-first, poche schermate e pochi tocchi (DD-005);
- **costo quasi nullo:** piano cloud minimo, nessun server da amministrare, per una squadra di ~17 persone.
Tre ruoli vedono cose diverse, e a farlo rispettare è il database:
| Ruolo | Cosa fa |
| ---------- | -------------------------------------------------------------------- |
| Giocatore | Risponde alle presenze, vede badge e statistiche, vota pagelle e MVP |
| Allenatore | Crea eventi e convoca, sollecita chi non risponde |
| Admin | Dashboard, certificati medici, profili, export CSV |
Come appare sul telefono:
<table>
<tr>
<td width="25%" align="center" valign="top">
<img src="img/app-presenze.png" width="100%" alt="Presenze" /><br />
<b>Presenze</b><br />
<sub>Risposta in un tocco, chi c'è e chi no</sub>
</td>
<td width="25%" align="center" valign="top">
<img src="img/app-sollecito.png" width="100%" alt="Sollecito" /><br />
<b>Sollecito</b><br />
<sub>Un tocco per sollecitare chi non ha risposto</sub>
</td>
<td width="25%" align="center" valign="top">
<img src="img/app-scout-live.png" width="100%" alt="Scout live" /><br />
<b>Scout live</b><br />
<sub>Valutazione − / + per fondamentale, in diretta</sub>
</td>
<td width="25%" align="center" valign="top">
<img src="img/app-dashboard-admin.png" width="100%" alt="Dashboard admin" /><br />
<b>Dashboard admin</b><br />
<sub>Certificati medici mancanti e profili</sub>
</td>
</tr>
</table>
### Il risultato, in numeri
Dati del database di produzione al 22 novembre 2026. Sono solo conteggi aggregati, senza dati personali, e includono le prove effettuate in produzione.
| Cosa | Numero |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| In uso da | 2 settembre 2026 (primo evento in calendario), 12 settimane |
| Eventi già svolti | 26: 20 allenamenti, 4 partite, 2 altri eventi |
| Eventi in calendario | 78 in tutto, fino al 31 maggio 2027 |
| Risposte di presenza registrate | 426 sugli eventi già svolti: 353 presente, 66 assente, 4 infortunato, 3 in ritardo |
| Voti dei giocatori | 26 voti MVP e 67 pagelle |
| Partite valutate con lo scout | 4, archiviate |
| Dispositivi con le push attive | 20 |
| Notifiche in-app inviate | 303 |
| Rilasci | 17, dalla 1.0.0 (24 settembre) alla 1.6.3 (16 novembre): meno di otto settimane |
Ogni correzione e ogni novità, rilascio per rilascio, è nel [CHANGELOG](../docs/CHANGELOG.md).
**Da dove nasce.** Il progetto è partito come prototipo su Lovable, un generatore di app. Per scelta (DD-001) è stato spostato su un repository indipendente, con Vercel e Supabase gestiti direttamente. Resta una traccia, un preset di build, censita nel piano di portabilità.
## 4. Architettura
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart TB
T["Telefono<br/>app installabile (PWA)<br/>React 19 + cache lunga"]
subgraph V["Vercel"]
SSR["TanStack Start<br/>pagine renderizzate lato server"]
API["Route API<br/>notifiche, campionato CSI, cron di keepalive"]
MW["Middleware<br/>gestione errori, protezione CSRF,<br/>token di sessione"]
end
subgraph S["Supabase"]
DB[("PostgreSQL<br/>permessi RLS per ruolo")]
AU["Autenticazione<br/>login con Google"]
ST["Archivio file<br/>foto e documenti"]
end
W["Worker email<br/>container Docker su Raspberry Pi"]
EXT["Portale CSI<br/>risultati del campionato"]
OUT["SMTP e servizi push dei browser"]
T -- "pagine" --> SSR
T -- "azioni e notifiche" --> API
SSR --> MW
API --> MW
MW -- "query con l'identità dell'utente" --> DB
MW -- "verifica la sessione" --> AU
T -- "carica foto e documenti" --> ST
API -- "legge i risultati" --> EXT
DB -- "coda di notifiche" --> W
W --> OUT
OUT --> T
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class MW hl
```
<sub><em>Figura 1 — Il telefono parla con Vercel; ogni richiesta passa da un middleware prima di toccare Supabase. Le notifiche escono da una coda, non dall'app.</em></sub>
**La regola centrale:** i componenti dell'interfaccia non parlano mai direttamente con il database. Ogni area funzionale ha un modulo in `src/lib/` (presenze, eventi, pagelle, scout…) che contiene due cose separate: gli _hook_ che leggono e scrivono i dati, e le _funzioni pure_ che fanno i calcoli.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart LR
C["Componente<br/>schermata"] -- "chiede i dati" --> H["Hook del modulo<br/>es. usePresenze"]
H -- "legge e scrive" --> Q["Cache locale<br/>TanStack Query"]
Q -- "solo se la cache è scaduta" --> DB[("Database")]
H -- "delega i calcoli" --> P["Funzioni pure<br/>calcoli senza rete"]
P -- "provate da" --> TU["Test unit veloci"]
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class Q hl
```
<sub><em>Figura 2 — Le schermate leggono dalla cache; il database si interroga solo quando serve.</em></sub>
**Perché conta:** se domani cambia il fornitore del database, si riscrive un solo livello e le schermate restano com'erano; e i calcoli (percentuali, badge, classifiche) si provano in millisecondi senza avviare nulla.
---
## 5. Le scelte tecniche, spiegate
### 5.1 La sicurezza sta nel database, non nell'interfaccia
**Il problema.** Nascondere un pulsante non protegge niente: chi chiama l'API a mano salta l'interfaccia.
**La scelta.** I permessi sono regole di PostgreSQL chiamate **Row Level Security** (RLS): il database stesso decide, riga per riga, cosa può leggere o scrivere l'utente che sta facendo la richiesta. L'app ne usa più di 60.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart LR
R["Richiesta<br/>dall'app o fatta a mano"] --> JWT["Identità verificata<br/>token di sessione"]
JWT --> RLS{"Policy RLS<br/>cosa può fare<br/>questo utente?"}
RLS -- "consentito" --> OK["Dati restituiti<br/>o modifica salvata"]
RLS -- "non consentito" --> NO["Nessuna riga,<br/>modifica rifiutata"]
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class RLS hl
```
<sub><em>Figura 3 — Il database decide per ogni richiesta, anche se non arriva dall'app.</em></sub>
**Come l'ho verificato.** Un test di integrazione (`permessi.test.ts`) **crea utenti veri su un database locale e interroga come loro**, controllando uno per uno i permessi della tabella di progetto. Rifiuta di girare contro la produzione: legge le credenziali dallo stack locale, non dal file `.env`, così non può puntare al database vero per sbaglio.
**Perché conta.** Un permesso scritto solo nel codice si verifica leggendolo; uno scritto nel database e provato con utenti reali si verifica eseguendolo.
### 5.2 Una vulnerabilità trovata, valutata e chiusa per iscritto
**Il problema.** Le route in `src/routes/api/public/` usano una chiave di servizio che salta la RLS. Una revisione ha mostrato che nessuna controllava chi la chiamava: chiunque conoscesse l'URL poteva far suonare i telefoni di tutta la squadra. La difesa apparente («serve un id evento valido») non lo era, perché l'id è prevedibile e visibile a qualsiasi utente loggato.
**La scelta (DD-024).** Le route che inviano notifiche verificano prima le credenziali, e lo fanno _prima ancora_ di validare l'input, così la risposta non rivela nemmeno se un evento esiste.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart TD
REQ["Chiamata alla route"] --> TK{"Token di sessione<br/>valido?"}
TK -- "no" --> E401["401 non autenticato"]
TK -- "sì" --> RL{"Ruolo admin<br/>in user_roles?"}
RL -- "no" --> E403["403 non autorizzato"]
RL -- "sì" --> VAL["Validazione dell'input"]
VAL --> ACT["Invio delle notifiche"]
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class TK,RL hl
```
<sub><em>Figura 4 — Le credenziali si controllano prima di tutto, anche prima dell'input.</em></sub>
**Perché conta.** Il danno possibile era molestia e consumo della quota push, non furto di dati; la decisione lo dichiara esplicitamente. Valutare il rischio in modo proporzionato e comunque chiudere la porta è il comportamento che si cerca in chi lavora su sistemi reali.
### 5.3 Costi bassi per costruzione, non per ottimizzazione
**Il problema.** Su un piano cloud minimo ogni query ha un costo, e un'app che ricarica i dati di continuo lo fa pagare.
**La scelta.** Regole imposte dall'inizio: niente polling, cache lunga (5 minuti) e passiva, e dopo una modifica la cache si aggiorna a mano con `setQueryData` invece di invalidarla, perché invalidare costerebbe una nuova lettura.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart LR
subgraph NO["Approccio comune"]
direction LR
M1["Modifica"] --> I["Invalida la cache"] --> R1["Rilegge dal database<br/>1 query in più"]
end
subgraph SI["Approccio di CrAPP"]
direction LR
M2["Modifica"] --> S["Aggiorna la cache<br/>con il valore già noto"] --> R2["Nessuna query in più"]
end
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class S,R2 hl
```
<sub><em>Figura 5 — Dopo una modifica la cache si aggiorna con il valore già noto: una query in meno.</em></sub>
Un aggregatore (`useRosa()`) compone tutto ciò che è già in cache e calcola statistiche e badge a runtime **senza query aggiuntive**. L'eccezione è documentata: nello scout live un altro dispositivo può aver preso il controllo, quindi lì si rilegge davvero.
**Perché conta.** L'efficienza è una regola del progetto con eccezioni motivate, non un'ottimizzazione tardiva.
### 5.4 Concorrenza e fusi orari: i bug che i test felici non trovano
**Scout live a più dispositivi.** Più persone possono aprire lo scout della stessa partita, ma ne scrive una sola alla volta. La sessione scade dopo 5 minuti di inattività, così se il telefono del referente si spegne nessuno resta bloccato; un timestamp illeggibile libera la sessione invece di bloccarla per sempre.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
stateDiagram-v2
[*] --> Libera
Libera --> InUso: un giocatore apre lo scout
InUso --> InUso: ogni tocco aggiorna l'orario
InUso --> Libera: nessun tocco per 5 minuti
InUso --> Libera: fine partita, salvata in archivio
```
<sub><em>Figura 6 — Una sessione scout ferma da più di 5 minuti si considera libera: chi arriva dopo può riprenderla.</em></sub>
**Mezzanotte italiana.** La data di «oggi» si calcola con il fuso `Europe/Rome` tramite `Intl`, non con i metodi locali di `Date`. Il motivo: sul server il fuso è spesso UTC, e `toISOString()` lo è sempre. Un errore qui sposta la mezzanotte, e nelle prime ore del giorno una partita già giocata risulterebbe «di domani».
**Perché conta.** Sono errori che compaiono solo in orari e situazioni particolari. Averli previsti e scritti nel codice con la spiegazione è ciò che distingue un prototipo da un'app usata davvero.
### 5.5 L'integrità dei dati la garantiscono i vincoli
**Il problema.** Il voto MVP deve essere definitivo: se si potesse cambiare, la classifica di una partita potrebbe ribaltarsi dopo che la squadra l'ha già vista.
**La scelta (DD-051).** Non basta togliere il pulsante «Cambia voto». Il vincolo `UNIQUE (match_id, votante_id)` fa rifiutare il secondo voto dal database, e al giocatore resta solo il permesso di inserimento: modifica e cancellazione sono riservate agli admin, che possono correggere un errore.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart LR
V1["Primo voto<br/>del giocatore"] --> INS["INSERT consentito"] --> SAL[("Voto salvato")]
V2["Secondo voto<br/>stessa partita"] --> UQ{"Vincolo UNIQUE<br/>match_id, votante_id"}
UQ -- "violato" --> RIF["Rifiutato dal database"]
ADM["Admin"] --> COR["UPDATE / DELETE<br/>per correggere un errore"] --> SAL
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class UQ hl
```
<sub><em>Figura 7 — Il secondo voto lo rifiuta il database, non l'interfaccia.</em></sub>
Lo stesso principio vale per le migration (le modifiche allo schema): sono solo additive, non si riscrivono mai una volta applicate, e prima di ogni push in produzione salvo lo schema.
**Perché conta.** L'interfaccia è un comfort; la regola vera sta nel dato, dove nessun bug dell'interfaccia può aggirarla.
### 5.6 Notifiche su tre canali, senza dipendenze proprietarie
**Il problema.** Chi non risponde alla convocazione va sollecitato, ma senza martellare la squadra e senza legarsi a un servizio esterno a pagamento.
**La scelta.** Le notifiche nascono dentro il database, da un job pianificato, e finiscono in code. Un worker separato le consegna.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontSize":"20px"},"flowchart":{"wrappingWidth":340,"padding":14}}}%%
flowchart TB
A["<b>1 · Il database</b><br/>24 ore prima dell'evento controlla<br/>chi non ha risposto o ha risposto «forse»"]
B["<b>2 · La coda</b><br/>per ognuno scrive una notifica:<br/>in-app, push ed email"]
C["<b>3 · Il worker</b><br/>un piccolo programma in Docker<br/>legge la coda e consegna"]
T["<b>Push</b><br/>sul telefono,<br/>anche ad app chiusa"]
M["<b>Email</b><br/>nella casella<br/>di posta"]
IA["<b>Avviso in-app</b><br/>nel centro<br/>notifiche"]
R["<b>Il giocatore risponde</b><br/>con un tocco"]
A --> B
B --> C
B -- "subito" --> IA
C --> T
C --> M
T --> R
IA --> R
M --> R
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class B hl
```
<sub><em>Figura 8 — Dal controllo nel database alla risposta del giocatore: la coda separa chi decide da chi consegna.</em></sub>
Dettagli che contano:
- **Push senza librerie di terzi:** il protocollo Web Push con firma VAPID è implementato con **Web Crypto**, disponibile in Node 18+.
- **Worker isolato:** parla solo con Supabase, con un server SMTP a scelta e con i servizi push dei browser. È in un container con controllo di salute, su un Raspberry Pi; nessuna porta in entrata, nessun IP pubblico.
- **Ognuno decide:** push, in-app ed email hanno ciascuna un interruttore personale.
- **Niente rumore:** il sollecito automatico parte una sola volta, a 24 ore dall'evento, e solo per chi non ha ancora risposto.
**Perché conta.** Tre canali con un'infrastruttura minima, tutta sostituibile.
### 5.7 Un modello dati pensato per i permessi
Le tabelle principali, dall'alto in basso: chi è l'utente, a quale evento si riferisce, quali dati produce.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontSize":"20px","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart TB
U["Account Google"]
R["<b>user_roles</b><br/>chi è admin"]
G["<b>giocatori_squadra</b><br/>lo slot del giocatore"]
E["<b>eventi_app</b><br/>allenamenti e partite"]
PR["<b>risposte_presenze</b><br/>chi c'è"]
VO["<b>voti</b><br/>MVP, pagelle, badge"]
SC["<b>scout</b><br/>la partita in numeri"]
U -- "ha un ruolo" --> R
U -- "si collega a" --> G
G -- "è convocato a" --> E
E -- "genera" --> PR
E -- "genera" --> VO
E -- "genera" --> SC
classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF
class E hl
```
<sub><em>Figura 9 — Al centro l'evento: presenze, voti e scout nascono da lui e spariscono con lui. Sono mostrate le tabelle principali.</em></sub>
Due regole di dominio che il modello codifica e che hanno richiesto una decisione scritta ciascuna:
- `convocati` **vuoto significa tutta la rosa**, non nessuno (DD-027);
- **cancellare un evento** pulisce a cascata, con un trigger, tutte le tabelle collegate: presenze, voti, turni, scout (DD-029).
---
## 6. Come lavoro: documentazione prima, codice dopo
Il progetto è **document-first** (DD-002): ogni funzione nasce come scheda in `docs/modules/` (obiettivo, dati, permessi), poi si scrive il codice. La scelta è deliberata: serve a lavorare bene in più persone e con assistenti AI, cioè con collaboratori che non ricordano nulla delle sessioni precedenti.
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F3F3F5","primaryBorderColor":"#C71B1E","primaryTextColor":"#16161A","secondaryColor":"#F7C5C6","tertiaryColor":"#FFFFFF","lineColor":"#C71B1E","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#F7C5C6","noteTextColor":"#16161A","actorBkg":"#F3F3F5","actorBorder":"#C71B1E","actorTextColor":"#16161A","signalColor":"#C71B1E","signalTextColor":"#16161A","labelBoxBkgColor":"#F7C5C6","labelTextColor":"#16161A","fontFamily":"Calibri, Arial, sans-serif"}}}%%
flowchart LR
A["Scheda del modulo<br/>e riga in ROADMAP"] --> B["Decisione scritta<br/>se la scelta non è ovvia"]
B --> C["Schema: documentazione,<br/>nuova migration, policy, test permessi"]
C --> D["Logica pura con test unit,<br/>poi hook e interfaccia"]
D --> E["CHANGELOG e checklist<br/>di fine lavoro"]
```
<sub><em>Figura 10 — Dalla scheda del modulo al rilascio: la documentazione viene prima del codice.</em></sub>
- **54 decisioni di progetto** (`docs/decisions/`), ognuna con contesto, scelta, alternative scartate e quando riaprire la questione. Chi arriva dopo capisce non solo cosa c'è, ma perché.
- **Una sola casa per ogni informazione**, per evitare che le copie divergano: funzioni in `ROADMAP`, schema in `DATABASE`, rilasci in `CHANGELOG`.
- **Portabilità dichiarata:** PostgreSQL standard, API HTTP standard, nessuna funzione proprietaria. Esiste un piano scritto per spostare tutto su un normale server Node + PostgreSQL, con script di backup e procedura di ripristino.
- **Guardia sulla catena di fornitura:** i pacchetti nuovi devono avere almeno 24 ore di vita, per ridurre il rischio di pacchetti compromessi appena pubblicati.
### Un metodo pensato per usare l'IA meglio
Un assistente AI ricomincia da zero a ogni sessione: non sa cosa si è deciso la settimana scorsa e non conosce le abitudini del progetto. Se la conoscenza vive nelle teste o nelle chat, l'assistente deve indovinarla; se vive nel repository, la legge. Per questo la documentazione è la **memoria condivisa** di persone e assistenti (la regola 4 di `AGENTS.md` lo dice: la fonte di verità è il repository, non la cronologia della conversazione). Il risultato è un'IA più _efficiente_, perché legge meno, e più _efficace_, perché sbaglia meno.
| Cosa c'è nel progetto | Cosa evita all'assistente | Vantaggio |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------ |
| Indice con ordine di lettura e una sola casa per ogni informazione | Esplorare tutto il codice a tappeto o trovare due versioni diverse dello stesso dato | Efficienza |
| Grafo del repository interrogabile (graphify) | Cercare file a tentativi per capire chi chiama cosa | Efficienza |
| Decisioni (DD) lette una per una, solo quelle richiamate dal modulo | Caricare tutta la storia del progetto per fare una modifica piccola | Efficienza |
| Scheda del modulo scritta prima del codice | Inventare funzioni o comportamenti non voluti (era il rischio che motivò DD-002) | Efficacia |
| Decisioni con le alternative già scartate | Riproporre ogni volta una soluzione già valutata e rifiutata | Efficacia |
| «Trappole note» in `ARCHITECTURE.md` | Ripetere errori già visti, come invalidare la cache o accedere al database dai componenti | Efficacia |
| Un solo file di regole, `AGENTS.md`, che Claude Code, Codex e Cursor leggono | Comportamenti diversi a seconda dello strumento usato | Coerenza |
| Test obbligatori e checklist di fine lavoro (lint, tipi, test, documentazione) | Dichiarare finito un lavoro che non lo è: la verifica la fa la macchina, non la fiducia | Affidabilità |
Funziona anche per le persone: chi entra nel progetto, come un nuovo collega, parte dagli stessi documenti. Il metodo non sostituisce il giudizio di chi revisiona, ma gli dà qualcosa di verificabile: ogni modifica dell'assistente si confronta con una scheda, una decisione e un test.
### Test su tre livelli
| Livello | File | Cosa prova |
| ----------- | ---- | ----------------------------------------------------------------- |
| Unit | 43 | Calcoli puri: veloci, senza rete né database |
| Integration | 33 | Route server vere e permessi per ruolo, su un database locale |
| End-to-end | 1 | Percorsi completi sull'app servita (da estendere, vedi sezione 7) |
### Uso dell'intelligenza artificiale
Sviluppo con assistenti AI (Claude Code e Cursor). Per governarli esiste un file di regole di progetto (`AGENTS.md`) con la procedura obbligatoria prima di dichiarare finito un lavoro: documentazione aggiornata, lint, controllo dei tipi, test. L'AI accelera la scrittura; decisioni, controllo dei permessi e verifica restano un lavoro di revisione, ed è ciò che questo repository documenta.
---
## 7. Limiti e prossimi passi
Cosa migliorerei, in ordine di priorità.
| Limite | Cosa farei |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Sviluppo e produzione condividono lo stesso Supabase | Separare gli ambienti; intanto le prove distruttive girano solo sullo stack locale |
| Il backup non è automatizzato per intero | Automatizzare anche l'export delle variabili d'ambiente di Vercel |
| Un solo test end-to-end | Aggiungere i percorsi principali sull'app servita |
| I dati del campionato si leggono dal portale a ogni richiesta | Sincronizzarli periodicamente in una tabella locale (obiettivo già scritto) |
| Statistiche calcolate a runtime (DD-007) | Rivalutare se i dati crescessero di molto |
## 8. Glossario
| Termine | Significato |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| PWA | App web che si installa dalla schermata Home del telefono, senza passare dagli store |
| SSR | Le pagine vengono preparate dal server prima di arrivare al telefono, quindi si aprono più in fretta |
| RLS (Row Level Security) | Regole del database che decidono, riga per riga, cosa può leggere o scrivere ogni utente |
| CSRF | Attacco in cui un sito esterno fa compiere azioni a un utente loggato a sua insaputa; il middleware lo blocca |
| Migration | File SQL che modifica lo schema del database in modo ordinato e ripetibile |
| Vincolo `UNIQUE` | Regola del database che impedisce di salvare due righe uguali su certi campi |
| Cache (TanStack Query) | Copia locale dei dati già scaricati, per non rileggerli dal database a ogni schermata |
| Hook / funzione pura | Hook: codice che legge o scrive dati. Funzione pura: calcolo che dà sempre lo stesso risultato, senza effetti |
| Job pianificato (`pg_cron`) | Attività che il database esegue da solo a orari stabiliti |
| Web Push / VAPID | Standard delle notifiche sul telefono, anche ad app chiusa; VAPID identifica chi le invia |
| Container (Docker) | Programma impacchettato con tutto ciò che serve, che gira uguale su qualsiasi computer |