Files
CRAPP/presentazione/technical-case-study.md
T

434 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |