Spiegare quali regole stanno nel dominio

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

Una delle verifiche più importanti durante la presentazione finale è questa: lo studente sa distinguere una regola di dominio da una regola dell’interfaccia? Sa motivare perché puoEsserePrestato sta in domain/ e non dentro un addEventListener?

Obiettivo della lezione

In questa lezione impari a spiegare con parole precise quali regole del laboratorio appartengono al dominio, come mostrarle nel codice durante la presentazione, e come rispondere alla domanda “perché non le hai messe nella UI?”.

Alla fine devi avere un risultato verificabile: la capacità di aprire domain/regolePrestito.js, leggere le funzioni ad alta voce e spiegare perché ogni regola sta lì.

Cosa appartiene al dominio nel Registro

Una regola appartiene al dominio se è vera indipendentemente dall’interfaccia. Chiediti: “questa regola varrebbe anche se l’app fosse una CLI da terminale invece di una pagina web?” Se la risposta è sì, è una regola di dominio.

Ecco le regole concrete del Registro che stanno in domain/:

puoEsserePrestato(strumento)
  → vero solo se strumento.stato === 'disponibile'
  → motivo: la regola del laboratorio reale, non del software

verificaTransizione(statoAttuale, statoNuovo)
  → controlla che la transizione sia valida
  → es. disponibile → in_prestito: OK
  → es. in_prestito → disponibile: solo tramite restituzione
  → es. guasto → disponibile: solo tramite manutenzione completata

isDisponibile(strumento)
  → comoda abbreviazione usata nei casi d'uso

stati validi di StatoStrumento
  → DISPONIBILE, IN_PRESTITO, GUASTO, IN_MANUTENZIONE
  → non esiste nessun altro stato: il dominio lo garantisce

Queste funzioni non sanno nulla di HTML, localStorage o fetch. Non importano nulla di esterno. Prendono un oggetto, applicano una regola, restituiscono un valore.

Script parlato per la presentazione

Prepara queste frasi da dire mentre mostri il file domain/regolePrestito.js:

Aprendo il file: “Questo file contiene le regole del laboratorio. Non ha nessuna importazione: non sa di localStorage, non sa di HTML. Questo è intenzionale.”

Mostrando puoEsserePrestato: “Questa funzione risponde a una domanda del laboratorio reale: ‘possiamo prestare questo strumento?’ La risposta dipende dallo stato dello strumento. Se è disponibile, sì. Altrimenti no. Questa regola è scritta una volta sola e tutti i casi d’uso la usano.”

Mostrando verificaTransizione: “Le transizioni di stato non sono tutte permesse. Uno strumento guasto non torna disponibile direttamente: deve passare per la manutenzione. Questa mappa di transizioni sta nel dominio perché è una regola del laboratorio, non una scelta dell’interfaccia.”

Alla domanda “perché non nella UI?”: “Se mettessi questa regola dentro il pulsante ‘Presta’, dovrei copiarla in ogni altro punto dove si può avviare un prestito. E se la regola cambia — per esempio, aggiungiamo una verifica sulla scadenza — dovrei trovarla e aggiornarla in ogni punto. Nel dominio la cambio una volta sola.”

Procedura guidata

1. Apri domain/regolePrestito.js e conta quante importazioni ha: deve essere zero.
2. Leggi puoEsserePrestato e scrivi in una frase la regola del laboratorio che implementa.
3. Leggi verificaTransizione e disegna il grafo degli stati validi su carta.
4. Cerca in tutto il progetto se la condizione strumento.stato === 'disponibile' appare fuori da domain/. Se la trovi, è un difetto da correggere.
5. Prepara la risposta alla domanda “perché non nella UI?” con l’esempio della regola che cambia.
6. Allena la spiegazione mostrando il file e commentando ogni funzione a voce.
7. Verifica che domain/ non importi nulla da infrastructure/, application/ o presentation/.

Attività in classe

Compila questa scheda prima della presentazione:

## Le regole del dominio nel mio progetto

File principale del dominio: _______________

Regole presenti (elencale):
1. _______________
2. _______________
3. _______________

Funzione che impedisce il prestito di uno strumento guasto:
  nome: _______________
  cosa controlla: _______________

Transizioni di stato valide (disegna o elenca):
  disponibile → _______________
  in_prestito → _______________
  guasto → _______________
  in_manutenzione → _______________

Risposta alla domanda "perché non nella UI?":
_______________

Verifica che domain/ non importa da altri livelli: [ ] superata

Se lavori in gruppo, una persona spiega le regole e un’altra verifica che non ci siano regole duplicate fuori dal dominio.

Spiegazione guidata per studiare

Le regole di dominio sono il cuore del progetto. Sono le regole che il laboratorio avrebbe anche senza software: uno strumento guasto non si presta, uno strumento in manutenzione non è disponibile, un prestito aperto non può essere riaperto.

Il rischio più comune è scrivere queste regole direttamente nell’interfaccia: un if dentro un addEventListener, una condizione dentro il codice che aggiorna il DOM. All’inizio sembra più veloce. Ma appena il progetto cresce — una seconda pagina, una seconda voce di menu, un’app mobile — devi riscrivere la stessa regola ogni volta.

Nel dominio la scrivi una volta. Tutti i casi d’uso la importano. Se cambia la regola, cambi un punto solo.

Quando studi, cerca di rispondere a questa domanda per ogni funzione di domain/: “questa funzione potrebbe essere usata da un programma che non ha né HTML né localStorage?” Se la risposta è sì, il codice è nel posto giusto. Se la funzione accede a document, localStorage o fetch, è nel posto sbagliato.

Il grafo delle transizioni di stato è particolarmente importante da capire bene. Non tutte le transizioni sono valide. verificaTransizione è la funzione che centralizza questa mappa. Se la mappa fosse distribuita in cinque punti dell’applicazione, aggiungere un nuovo stato (per esempio “in riparazione esterna”) richiederebbe cinque modifiche invece di una.

Passo per passo nel progetto

1. Apri domain/StatoStrumento.js e leggi i quattro stati definiti.
2. Per ogni stato, chiediti: “da questo stato, dove posso andare?” Rispondi consultando verificaTransizione.
3. Disegna il grafo su carta: ogni stato è un nodo, ogni transizione valida è una freccia.
4. Apri domain/regolePrestito.js e leggi puoEsserePrestato: controlla che dipenda solo da StatoStrumento, non da altri livelli.
5. Cerca la stringa stato === in tutto il progetto. Ogni occorrenza fuori da domain/ è un candidato da spostare.
6. Prepara un esempio concreto: “se la regola ‘guasto non si presta’ fosse nel bottone, cosa succederebbe se aggiungessimo la voce di menu ‘prestito rapido’?”

Esempio da leggere lentamente

Questo codice mostra come le regole di dominio funzionano in isolamento:

// domain/StatoStrumento.js
const StatoStrumento = {
  DISPONIBILE: 'disponibile',
  IN_PRESTITO: 'in_prestito',
  GUASTO: 'guasto',
  IN_MANUTENZIONE: 'in_manutenzione'
};

// domain/regolePrestito.js
function puoEsserePrestato(strumento) {
  return strumento.stato === StatoStrumento.DISPONIBILE;
}

const transizioniValide = {
  [StatoStrumento.DISPONIBILE]: [StatoStrumento.IN_PRESTITO, StatoStrumento.GUASTO],
  [StatoStrumento.IN_PRESTITO]: [StatoStrumento.DISPONIBILE, StatoStrumento.GUASTO],
  [StatoStrumento.GUASTO]: [StatoStrumento.IN_MANUTENZIONE],
  [StatoStrumento.IN_MANUTENZIONE]: [StatoStrumento.DISPONIBILE]
};

function verificaTransizione(statoAttuale, statoNuovo) {
  const permesse = transizioniValide[statoAttuale] || [];
  if (!permesse.includes(statoNuovo)) {
    throw new Error(
      `Transizione non valida: ${statoAttuale} → ${statoNuovo}`
    );
  }
}

Nota: nessuna importazione esterna. Nessun document, nessun localStorage. Queste funzioni sono testabili con un semplice node da terminale, senza browser.

Prova di comprensione

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

• Uno strumento in manutenzione può essere prestato? Quale funzione risponde a questa domanda?
• Se devo aggiungere la transizione “in_manutenzione → guasto” (la riparazione ha peggiorato il problema), in quale file faccio la modifica?
• Perché puoEsserePrestato non chiama localStorage per leggere lo stato aggiornato?
• Come risponderesti alla domanda: “ma se cambio la regola nel dominio, come faccio a sapere che l’interfaccia si aggiorna?”

Una risposta accettabile usa i nomi reali delle funzioni del progetto.

Errori da evitare

• avere strumento.stato === 'disponibile' scritto direttamente in un gestore di evento HTML;
• importare da infrastructure/ dentro domain/ — il dominio non conosce la persistenza;
• non saper disegnare il grafo delle transizioni di stato a voce;
• dire “le regole stanno nel dominio per organizzazione” invece di dare il motivo concreto della riusabilità;
• dimenticare verificaTransizione durante la presentazione — è la funzione più interessante da mostrare.

Prodotto da consegnare

Prepara per la presentazione:

• il grafo degli stati e transizioni valide disegnato su carta o in un file di testo;
• la spiegazione a voce di puoEsserePrestato in massimo trenta secondi;
• la risposta alla domanda “perché non nella UI?” con l’esempio concreto del menu aggiuntivo.

Checklist di chiusura

Prima di chiudere la lezione, controlla:

• sai leggere puoEsserePrestato e spiegarne la regola in una frase;
• hai disegnato il grafo delle transizioni di stato;
• hai verificato che domain/ non ha importazioni da altri livelli;
• sai rispondere a “perché non nella UI?” con un esempio concreto;
• hai cercato stato === fuori da domain/ e risolto le occorrenze trovate.

Risultato atteso

Alla fine lo studente deve saper dire:

In domain/ mettiamo le regole del laboratorio: puoEsserePrestato, verificaTransizione, StatoStrumento.
Queste funzioni non importano nulla di esterno.
puoEsserePrestato restituisce vero solo se lo strumento è disponibile.
verificaTransizione lancia un errore se la transizione non è nella mappa delle transizioni valide.
Stanno nel dominio perché devono valere ovunque, indipendentemente dall'interfaccia.

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