diff --git a/presentazione/img/app-dashboard-admin.png b/presentazione/img/app-dashboard-admin.png new file mode 100644 index 0000000..96521fb Binary files /dev/null and b/presentazione/img/app-dashboard-admin.png differ diff --git a/presentazione/img/app-presenze.png b/presentazione/img/app-presenze.png new file mode 100644 index 0000000..6b0f37a Binary files /dev/null and b/presentazione/img/app-presenze.png differ diff --git a/presentazione/img/app-scout-live.png b/presentazione/img/app-scout-live.png new file mode 100644 index 0000000..77fe39d Binary files /dev/null and b/presentazione/img/app-scout-live.png differ diff --git a/presentazione/img/app-sollecito.png b/presentazione/img/app-sollecito.png new file mode 100644 index 0000000..7372219 Binary files /dev/null and b/presentazione/img/app-sollecito.png differ diff --git a/presentazione/technical-case-study.md b/presentazione/technical-case-study.md new file mode 100644 index 0000000..0ca2d32 --- /dev/null +++ b/presentazione/technical-case-study.md @@ -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:** + +> **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: + + + + + + + + +
+ Presenze
+ Presenze
+ Risposta in un tocco, chi c'è e chi no +
+ Sollecito
+ Sollecito
+ Un tocco per sollecitare chi non ha risposto +
+ Scout live
+ Scout live
+ Valutazione − / + per fondamentale, in diretta +
+ Dashboard admin
+ Dashboard admin
+ Certificati medici mancanti e profili +
+ +### 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
app installabile (PWA)
React 19 + cache lunga"] + subgraph V["Vercel"] + SSR["TanStack Start
pagine renderizzate lato server"] + API["Route API
notifiche, campionato CSI, cron di keepalive"] + MW["Middleware
gestione errori, protezione CSRF,
token di sessione"] + end + subgraph S["Supabase"] + DB[("PostgreSQL
permessi RLS per ruolo")] + AU["Autenticazione
login con Google"] + ST["Archivio file
foto e documenti"] + end + W["Worker email
container Docker su Raspberry Pi"] + EXT["Portale CSI
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 +``` + +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. + +**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
schermata"] -- "chiede i dati" --> H["Hook del modulo
es. usePresenze"] + H -- "legge e scrive" --> Q["Cache locale
TanStack Query"] + Q -- "solo se la cache è scaduta" --> DB[("Database")] + H -- "delega i calcoli" --> P["Funzioni pure
calcoli senza rete"] + P -- "provate da" --> TU["Test unit veloci"] + classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF + class Q hl +``` + +Figura 2 — Le schermate leggono dalla cache; il database si interroga solo quando serve. + +**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
dall'app o fatta a mano"] --> JWT["Identità verificata
token di sessione"] + JWT --> RLS{"Policy RLS
cosa può fare
questo utente?"} + RLS -- "consentito" --> OK["Dati restituiti
o modifica salvata"] + RLS -- "non consentito" --> NO["Nessuna riga,
modifica rifiutata"] + classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF + class RLS hl +``` + +Figura 3 — Il database decide per ogni richiesta, anche se non arriva dall'app. + +**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
valido?"} + TK -- "no" --> E401["401 non autenticato"] + TK -- "sì" --> RL{"Ruolo admin
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 +``` + +Figura 4 — Le credenziali si controllano prima di tutto, anche prima dell'input. + +**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
1 query in più"] + end + subgraph SI["Approccio di CrAPP"] + direction LR + M2["Modifica"] --> S["Aggiorna la cache
con il valore già noto"] --> R2["Nessuna query in più"] + end + classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF + class S,R2 hl +``` + +Figura 5 — Dopo una modifica la cache si aggiorna con il valore già noto: una query in meno. + +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 +``` + +Figura 6 — Una sessione scout ferma da più di 5 minuti si considera libera: chi arriva dopo può riprenderla. + +**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
del giocatore"] --> INS["INSERT consentito"] --> SAL[("Voto salvato")] + V2["Secondo voto
stessa partita"] --> UQ{"Vincolo UNIQUE
match_id, votante_id"} + UQ -- "violato" --> RIF["Rifiutato dal database"] + ADM["Admin"] --> COR["UPDATE / DELETE
per correggere un errore"] --> SAL + classDef hl fill:#C71B1E,stroke:#16161A,color:#FFFFFF + class UQ hl +``` + +Figura 7 — Il secondo voto lo rifiuta il database, non l'interfaccia. + +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["1 · Il database
24 ore prima dell'evento controlla
chi non ha risposto o ha risposto «forse»"] + B["2 · La coda
per ognuno scrive una notifica:
in-app, push ed email"] + C["3 · Il worker
un piccolo programma in Docker
legge la coda e consegna"] + T["Push
sul telefono,
anche ad app chiusa"] + M["Email
nella casella
di posta"] + IA["Avviso in-app
nel centro
notifiche"] + R["Il giocatore risponde
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 +``` + +Figura 8 — Dal controllo nel database alla risposta del giocatore: la coda separa chi decide da chi consegna. + +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["user_roles
chi è admin"] + G["giocatori_squadra
lo slot del giocatore"] + E["eventi_app
allenamenti e partite"] + PR["risposte_presenze
chi c'è"] + VO["voti
MVP, pagelle, badge"] + SC["scout
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 +``` + +Figura 9 — Al centro l'evento: presenze, voti e scout nascono da lui e spariscono con lui. Sono mostrate le tabelle principali. + +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
e riga in ROADMAP"] --> B["Decisione scritta
se la scelta non è ovvia"] + B --> C["Schema: documentazione,
nuova migration, policy, test permessi"] + C --> D["Logica pura con test unit,
poi hook e interfaccia"] + D --> E["CHANGELOG e checklist
di fine lavoro"] +``` + +Figura 10 — Dalla scheda del modulo al rilascio: la documentazione viene prima del codice. + +- **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 |