GET/it/projects/driving-school
Un gestionale per autoscuole italiane: allievi, istruttori, guide, esami e pagamenti, per più scuole sulla stessa installazione.
L’idea viene dagli anni in cui ho lavorato in autoscuola. Doveva essere sia un prodotto sia un progetto di studio, ed è rimasto il secondo: l’ambiente di sviluppo della Motorizzazione è aperto solo alle software house.
Più scuole condividono la stessa installazione, e la stessa persona può essere istruttore in una scuola e allievo in un’altra. L’obiettivo era tenere separati i dati di ogni scuola, e i confini fra le parti del dominio, mentre il progetto cresceva.
È partito con dei compagni dell’ITS e l’ho portato avanti da solo. Il disegno, gli obiettivi e le scelte sono miei; il codice l’ho scritto con l’aiuto di Claude Code.
Un’applicazione sola, divisa in moduli per area del dominio. Ogni modulo dichiara da chi dipende e cosa espone, e Spring Modulith lo verifica in un test: una dipendenza non dichiarata lo fa fallire.
In evidenza scheduling, il modulo delle guide: le linee lo uniscono ai moduli da cui dipende.
common tiene quello che serve a tutti i moduli: sicurezza, audit, eventi.
In evidenza scheduling, il modulo delle guide, con i moduli da cui dipende.
scheduling
dipende da
Gli altri moduli: auth, exam, finance, quiz.
common tiene quello che serve a tutti i moduli: sicurezza, audit, eventi.
L’agenda di una settimana, dal client al database. Tutte le scuole stanno nello stesso database, quindi ogni livello controlla che la richiesta resti dentro la sua scuola, e la ferma se non è così.
GET /
X-School-Id la scuola su cui si lavora, accanto al token
security Spring Security
403 nessuna membership attiva in quella scuola
controller endpoint REST
403 l’utente non è membro della scuola nel path
service modulo scheduling
404 path e header indicano scuole diverse
repository Spring Data JPA
WHERE school_
Postgre
l’indice dell’agenda comincia dalla scuola, così ogni scuola legge solo la sua parte
Chiudere una guida crea un addebito, scrive l’audit e avvisa l’allievo. Prima scheduling chiamava finance; ora pubblica un evento, e finance lo ascolta, così il modulo delle guide non dipende più da quello dei pagamenti.
prima
scheduling le guide
exam gli esami
finance gli addebiti
scheduling ed exam dipendono da finance
dopo
scheduling evento: guida completata
exam evento: iscrizione all’esame
finance gli addebiti
scheduling ed exam non importano niente da finance
L’evento si salva nella stessa transazione della guida, nel registro di Spring Modulith, che sta nello stesso PostgreSQL: niente broker. Se un listener fallisce, un job ripubblica l’evento, quindi la consegna è almeno una volta.
una transazione
guida completata modulo scheduling
evento nel registro, una riga per listener
commit: tutti e due o nessuno
finance listener
1 già fatto? c’è già un addebito nato da questo evento: si ferma
2 crea l’addebito un indice unico sull’evento d’origine ne ammette uno solo
3 vincolo violato se è quell’indice, un’altra consegna è arrivata prima: si ignora
common listener
scrive l’audit
common listener
avvisa l’allievo
dopo il commit, ogni listener lavora nella sua transazione
job pianificato legge il registro
ripubblica gli eventi che un listener non ha completato
una transazione
guida completata modulo scheduling
evento nel registro, una riga per listener
commit: tutti e due o nessuno
finance listener, nella sua transazione
già fatto? 1 c’è già un addebito nato da questo evento: si ferma
crea l’addebito 2 un indice unico sull’evento d’origine ne ammette uno solo
vincolo violato 3 se è quell’indice, un’altra consegna è arrivata prima: si ignora
Gli altri due listener scrivono l’audit e avvisano l’allievo, ognuno nella sua transazione.
job pianificato Ripubblica gli eventi che un listener non ha completato.
Due allievi possono prenotare lo stesso slot nello stesso momento. Decide un lock ottimistico: lo slot ha una colonna di versione, e la scrittura passa solo se la versione è ancora quella letta.
Allievo A
Allievo B
legge lo slot
prenota: UPDATE … WHERE version = 7
esito
applicazione. Nessuna sovrapposizione di orari, per l’istruttore e per l’allievo.
database. Un indice unico parziale: una sola prenotazione attiva per slot.
concorrenza. Una colonna di versione sullo slot: chi scrive per secondo riceve 409.
Nessun retry lato server: lo slot ormai è di un altro, e la scelta torna all’allievo.
Le altre scelte, con il loro perché.
ADR 001 Accettata
ADR 002 Accettata
ADR 003 Accettata
Cosa non andava, e com’è adesso.
Un pagamento senza allocazione copre gli addebiti aperti dal più vecchio. Per sapere quanto restava su ognuno chiedevo al database la somma già pagata, un addebito alla volta: un N+1. Ora una query sola prende le somme di tutti prima del ciclo, e un test conta le chiamate.
Il refresh token cambia a ogni uso, e se ne torna uno già usato è il segno di un furto: revoco tutti quelli dell’utente e rispondo 401. Un test di integrazione ha trovato che la revoca non restava.
Nella prima versione i test giravano su H2. Ma lo schema usa i tipi enum e gli indici unici parziali di PostgreSQL, e sono proprio quegli indici a fermare le doppie prenotazioni e i doppi addebiti: ora i test di integrazione girano su un PostgreSQL vero, in un container.
Finché i confini fra i moduli erano una convenzione, li rispettavo meno di quanto pensassi: la prima verifica di Spring Modulith ha trovato dei cicli che non avevo visto. Gli eventi tolgono una dipendenza, ma la consegna diventa almeno una volta, e ogni listener deve reggere lo stesso evento più di una volta.