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:
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 |
@@ -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 |
|
||||||
Reference in new issue
Block a user