Spiegare i livelli separati

Questa lezione appartiene al Modulo 24 — Presentazione, valutazione e retrospettiva.

La domanda più frequente durante una presentazione di architettura è: “perché hai separato tutto in cartelle diverse? Non era più semplice tenerlo insieme?”. Questa lezione ti prepara a rispondere con un esempio concreto del Registro, non con una definizione.

Obiettivo della lezione

In questa lezione impari a spiegare i quattro livelli — Domain, Application, Infrastructure, Presentation — mostrando un punto preciso nel codice per ognuno, dicendo in una frase cosa fa quel livello e perché non può fare le cose degli altri.

Alla fine devi avere un risultato verificabile: uno script parlato di quattro blocchi (uno per livello) e la capacità di rispondere alla domanda “perché separati?” con un esempio dal Registro.

I quattro livelli nel Registro

Prima di prepararti la risposta, ricorda cosa fa ogni livello nel progetto reale:

domain/
  Strumento.js          → struttura dati, stati validi
  StatoStrumento.js     → DISPONIBILE, IN_PRESTITO, GUASTO, IN_MANUTENZIONE
  regolePrestito.js     → puoEsserePrestato(), verificaTransizione()

application/
  registraStrumento.js  → crea e salva uno strumento
  registraPrestito.js   → apre un prestito verificando le regole
  cercaStrumenti.js     → filtra la lista per nome/categoria/stato

infrastructure/
  archivioStrumentiLocale.js  → legge e scrive in localStorage
  archivioPrestitiLocale.js   → gestisce i prestiti in localStorage

presentation/
  formRegistraStrumento.js    → form HTML + gestione click
  listaStrumenti.js           → render della lista a schermo
  messaggi.js                 → mostra successo o errore

Ogni cartella ha una sola responsabilità. Questo è il punto da far capire.

Script parlato: quattro blocchi

Prepara queste frasi e allenati a dirle mentre mostri il file corrispondente:

Domain — “Qui stanno le regole del laboratorio” “In domain/ mettiamo le regole che appartengono al laboratorio, non al software. Per esempio: uno strumento guasto non può essere prestato. Questa regola è qui, non nella pagina HTML, perché deve valere anche se domani cambiamo interfaccia.”

Application — “Qui coordiniamo le operazioni” “In application/ mettiamo i casi d’uso: registraPrestito raccoglie uno strumento e uno studente, chiede al dominio se il prestito è possibile, poi dice all’archivio di salvarlo. Non sa come viene salvato, non sa come viene mostrato: coordina soltanto.”

Infrastructure — “Qui parliamo con localStorage” “In infrastructure/ mettiamo tutto ciò che dipende da dove salviamo i dati. Oggi è localStorage. Domani potrebbe essere un server. Il resto del codice non cambierebbe, perché nessuno chiama localStorage direttamente — lo fa solo l’archivio.”

Presentation — “Qui sta l’interfaccia” “In presentation/ mettiamo HTML, DOM, form e messaggi. Questo livello sa cosa mostrare e quando, ma non decide se un prestito è valido. Per quello chiama il caso d’uso.”

Risposta pronta alla domanda “perché separati?”

Quando qualcuno chiede “perché non tenerlo tutto in un file?”, la risposta concreta è:

“Perché se metto la regola ‘uno strumento guasto non può essere prestato’ dentro il bottone HTML, la devo riscrivere ogni volta che aggiungo un altro posto dove si può fare un prestito — un’altra pagina, un’altra voce di menu. Nel dominio la scrivo una volta sola e tutti i casi d’uso la usano.”

Questa è la risposta da memorizzare. Non è una definizione: è un motivo concreto con un esempio del progetto.

Procedura guidata

1. Apri le quattro cartelle nel tuo editor e tieni aperto un file per cartella.
2. Per ogni livello, scrivi su carta la frase da dire durante la presentazione.
3. Allena la risposta alla domanda “perché separati?” usando l’esempio del guasto.
4. Chiedi a un compagno di fare la domanda “perché non hai messo tutto in un file?” e rispondi a voce.
5. Verifica che nessun file in domain/ importi da infrastructure/ o da presentation/.
6. Verifica che nessun file in application/ importi localStorage direttamente.
7. Segna i due controlli come superati nella checklist.

Attività in classe

Compila questa scheda prima della presentazione:

## I quattro livelli nel mio progetto

Domain — file principale: _______________
Frase che userò: _______________

Application — file principale: _______________
Frase che userò: _______________

Infrastructure — file principale: _______________
Frase che userò: _______________

Presentation — file principale: _______________
Frase che userò: _______________

Risposta alla domanda "perché non tutto in un file?":
_______________

Esempio concreto del Registro che uso per rispondere:
_______________

Se lavori in gruppo, una persona prepara lo script e un’altra lo ascolta e segnala ogni volta che la spiegazione diventa troppo astratta.

Spiegazione guidata per studiare

Separare i livelli non è una scelta estetica. È una risposta a un problema pratico: il codice che cambia spesso non deve stare vicino al codice che deve restare stabile.

Le regole del laboratorio cambiano raramente. “Uno strumento guasto non può essere prestato” è una regola del laboratorio reale, non del software. Se la scrivi nel dominio, dura. Se la scrivi in un bottone HTML, la perdi appena cambi la pagina.

La persistenza cambia più spesso delle regole. Oggi localStorage, domani un’API. Se tutto il progetto chiama localStorage.setItem direttamente, cambiare tecnologia significa cercare e modificare ogni singola chiamata. Se lo fa solo l’archivio, cambi un file solo.

L’interfaccia cambia più spesso di tutto il resto. Colori, layout, testi, pagine nuove. Se ogni componente grafico conosce le regole del prestito, ogni modifica dell’interfaccia rischia di rompere una regola. Se la pagina chiama il caso d’uso e basta, puoi ridisegnare l’intera UI senza toccare il dominio.

Quando studi, non memorizzare le definizioni. Apri i file reali del Registro e chiediti per ogni funzione: “se questa cambiasse, quali altri file dovrei aggiornare?” Più la risposta è lunga, più quella funzione sta nel livello sbagliato.

Passo per passo nel progetto

1. Apri domain/regolePrestito.js e identifica la funzione che impedisce il prestito di uno strumento guasto.
2. Cerca in tutto il progetto se quella stessa regola viene ripetuta altrove. Se la trovi duplicata, è un difetto da segnalare in presentazione.
3. Apri application/registraPrestito.js e conta quante importazioni ha. Deve importare da domain/ e da infrastructure/, mai da presentation/.
4. Apri infrastructure/archivioStrumentiLocale.js e conta le righe che contengono localStorage. Devono essere tutte in questo file.
5. Apri un file in presentation/ e verifica che non contenga logica di validazione o regole di business.
6. Prepara un elenco di tre cose che cambieresti senza toccare il dominio, e tre cose che cambieresti senza toccare l’infrastruttura.

Esempio da leggere lentamente

Questo esempio mostra come lo stesso dato attraversa i livelli senza che ognuno sappia del successivo:

// domain/regolePrestito.js
function puoEsserePrestato(strumento) {
  return strumento.stato === 'disponibile';
  // non sa di localStorage, non sa di HTML
}

// application/registraPrestito.js
function registraPrestito(idStrumento, nomeStudente) {
  const strumento = archivioStrumenti.trova(idStrumento);
  if (!puoEsserePrestato(strumento)) {
    throw new Error('Lo strumento non è disponibile per il prestito');
  }
  const prestito = {
    id: crypto.randomUUID(),
    idStrumento,
    nomeStudente,
    dataApertura: new Date().toISOString(),
    stato: 'aperto'
  };
  archivioPrestitiLocale.salva(prestito);
  archivioStrumenti.aggiornaStato(idStrumento, 'in_prestito');
}
// non sa di HTML, non sa di localStorage direttamente

// infrastructure/archivioStrumentiLocale.js
const archivioStrumenti = {
  trova(id) {
    return this._leggiTutti().find(s => s.id === id);
    // solo qui si tocca localStorage
  }
};

Ogni livello conosce solo ciò che gli serve. Questo è il confine che devi saper mostrare e spiegare.

Prova di comprensione

Prima di chiudere la lezione, rispondi per iscritto a queste domande:

• Se devi aggiungere la regola “uno studente non può avere più di tre prestiti aperti contemporaneamente”, in quale livello la aggiungi e perché?
• Se l’app cambia da localStorage a IndexedDB, quali file devi modificare?
• Se vuoi aggiungere una seconda pagina per i prestiti, quali livelli tocchi?
• Perché registraPrestito.js importa puoEsserePrestato invece di controllare strumento.stato === 'disponibile' direttamente?

Una risposta accettabile usa i nomi reali dei file del progetto.

Errori da evitare

• dire “separo per pulizia” senza dare un motivo concreto — la motivazione deve essere sempre “cosa cambia se faccio diversamente”;
• mostrare solo la struttura delle cartelle senza aprire i file — i confini si dimostrano nel codice;
• avere localStorage in un file di Application o Presentation — è un difetto da correggere prima della presentazione;
• avere una regola di dominio scritta dentro un addEventListener — è il difetto più comune;
• non saper rispondere alla domanda di follow-up: “e se voleste aggiungere un login?”.

Prodotto da consegnare

Prepara un foglio con:

• quattro frasi, una per livello, scritte a mano o stampate;
• la risposta alla domanda “perché separati?” con l’esempio del guasto;
• il risultato della verifica che localStorage appare solo in infrastructure/.

Durante la presentazione userai questo foglio come promemoria, non come testo da leggere.

Checklist di chiusura

Prima di chiudere la lezione, controlla:

• hai una frase pronta per ognuno dei quattro livelli;
• sai rispondere a “perché separati?” con l’esempio del guasto;
• hai verificato che localStorage non appare in application/ né in presentation/;
• sai indicare il file in domain/ che contiene puoEsserePrestato;
• hai allenato la spiegazione ad alta voce almeno una volta.

Risultato atteso

Alla fine lo studente deve saper dire:

Il Registro ha quattro livelli: Domain, Application, Infrastructure, Presentation.
Domain contiene le regole del laboratorio, come puoEsserePrestato().
Application coordina le operazioni, come registraPrestito().
Infrastructure gestisce localStorage, come archivioStrumentiLocale.
Presentation gestisce HTML e DOM, come listaStrumenti e i form.
Sono separati perché ogni livello cambia per ragioni diverse.

Se questa spiegazione non è possibile, la lezione non è ancora davvero conclusa.