Spiegare un caso d’uso completo

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

Un caso d’uso completo è la dimostrazione più potente che puoi fare durante la presentazione. Mostra che non stai solo descrivendo una struttura di cartelle: stai spiegando come un’azione reale dell’utente attraversa tutti i livelli e produce un risultato verificabile.

Obiettivo della lezione

In questa lezione impari a spiegare registraPrestito dall’inizio alla fine: come viene chiamato dalla UI, cosa coordina nell’Application, quali regole del dominio applica, come salva in Infrastructure, e cosa restituisce alla pagina. Impari anche cosa sottolineare per fare buona impressione nella valutazione.

Alla fine devi avere un risultato verificabile: la capacità di spiegare l’intero flusso di registraPrestito senza guardare gli appunti, indicando ogni file nel codice.

Il caso d’uso registraPrestito passo per passo

Questo è ciò che accade quando uno studente preme “Presta strumento” nella UI:

Passo 1 — Presentation raccoglie l'input
  L'utente seleziona uno strumento dalla lista e inserisce il suo nome.
  La pagina chiama: registraPrestito(idStrumento, nomeStudente)

Passo 2 — Application verifica l'esistenza
  registraPrestito cerca lo strumento nell'archivio.
  Se non esiste, lancia un errore: "Strumento non trovato".

Passo 3 — Application chiede al Domain
  registraPrestito chiama puoEsserePrestato(strumento).
  Se lo strumento non è disponibile, lancia un errore: "Lo strumento non è disponibile".

Passo 4 — Application costruisce il prestito
  Crea l'oggetto prestito: { id, idStrumento, nomeStudente, dataApertura, stato: 'aperto' }

Passo 5 — Application aggiorna lo stato tramite Infrastructure
  Chiama archivioStrumenti.aggiornaStato(idStrumento, 'in_prestito').
  Chiama archivioPrestitiLocale.salva(prestito).

Passo 6 — Application restituisce il risultato
  Restituisce il prestito salvato alla UI.

Passo 7 — Presentation mostra il messaggio
  La pagina mostra: "Prestito registrato per [nomeStudente]".

Questo è lo script della presentazione. Ogni passo corrisponde a un punto nel codice.

Script parlato per la presentazione

Prepara queste frasi da dire mentre navighi il codice:

Aprendo presentation/formPrestito.js: “L’utente preme il pulsante. La pagina raccoglie l’ID dello strumento selezionato e il nome dello studente. Poi chiama registraPrestito. Non sa cosa succede dopo: non sa di localStorage, non sa delle regole sul guasto.”

Aprendo application/registraPrestito.js: “Questo è il caso d’uso. Prima cerca lo strumento nell’archivio. Se non lo trova, errore. Poi chiede al dominio se può essere prestato. Se non può, errore. Solo se tutto va bene crea il prestito e lo salva.”

Mostrando la riga con puoEsserePrestato: “Questa è la chiamata al dominio. Il caso d’uso non scrive mai strumento.stato === 'disponibile' direttamente. Chiede al dominio, che è l’unico responsabile di quella regola.”

Mostrando le righe con archivioStrumenti e archivioPrestitiLocale: “Qui il caso d’uso delega all’infrastruttura. Non sa che usiamo localStorage. Sa solo che esiste un archivio che sa salvare. Se domani cambiamo localStorage con un server, questo file non si tocca.”

Tornando alla pagina: “Il caso d’uso restituisce il prestito salvato. La pagina lo usa solo per mostrare il messaggio di conferma.”

Cosa sottolineare per la valutazione

I docenti verificano tipicamente questi tre aspetti:

1. Separazione delle responsabilità: il caso d’uso non conosce HTML né localStorage. Puoi dimostrarlo mostrando le importazioni del file.
2. Uso corretto del dominio: la regola sul prestito è nel dominio, non nel caso d’uso. Il caso d’uso la chiama, non la riscrive.
3. Gestione degli errori: ogni errore possibile è gestito esplicitamente. Non si arriva mai a salvare dati inconsistenti.

Procedura guidata

1. Apri application/registraPrestito.js e leggi il file dall’inizio alla fine.
2. Conta le importazioni: da domain/, da infrastructure/. Niente da presentation/.
3. Identifica il punto esatto dove viene chiamato il dominio e dove viene chiamata l’infrastruttura.
4. Prepara la risposta alla domanda: “cosa succede se provi a prestare uno strumento guasto?”
5. Apri il browser, vai sul form dei prestiti e registra un prestito reale.
6. Apri DevTools → Application → Local Storage e mostra il prestito salvato.
7. Mostra anche che lo stato dello strumento è cambiato da “disponibile” a “in_prestito”.

Attività in classe

Compila questa scheda prima della presentazione:

## Il caso d'uso registraPrestito

File del caso d'uso: _______________

Importazioni presenti:
  da domain/: _______________
  da infrastructure/: _______________
  da presentation/: (deve essere vuoto) _______________

Passo 1 — chi chiama registraPrestito?
  file: _______________ funzione: _______________

Passo 2 — quale errore viene lanciato se lo strumento non esiste?
  _______________

Passo 3 — quale funzione di domain/ viene chiamata?
  _______________

Passo 4 — come si chiama l'oggetto prestito creato?
  { id: ___, idStrumento: ___, nomeStudente: ___, dataApertura: ___, stato: ___ }

Passo 5 — quali metodi di infrastructure/ vengono chiamati?
  _______________

Passo 6 — cosa restituisce il caso d'uso alla UI?
  _______________

Se lavori in gruppo, una persona spiega il flusso e un’altra verifica che ogni passo corrisponda al codice aperto sullo schermo.

Spiegazione guidata per studiare

Un caso d’uso è un coordinatore. Non conosce i dettagli di come viene mostrata la pagina, né i dettagli di come vengono salvati i dati. Conosce le operazioni: prima verifica, poi trasforma, poi salva.

registraPrestito è l’esempio più completo perché coinvolge tutti e quattro i livelli: viene chiamato dalla Presentation, usa il Domain per validare, usa l’Infrastructure per persistere, e restituisce un risultato alla Presentation.

La cosa più importante da capire è che il caso d’uso non gestisce i dettagli: li delega. Non genera l’ID con crypto.randomUUID() in dieci punti diversi — lo fa una volta. Non controlla strumento.stato === 'disponibile' — chiama puoEsserePrestato. Non chiama localStorage.setItem — chiama archivioPrestitiLocale.salva.

Questa delega è la prova che l’architettura funziona. Se un caso d’uso inizia a fare troppo — controllare i dettagli dell’HTML, scrivere direttamente in localStorage, riscrivere le regole del dominio — significa che i confini si stanno erodendo.

Quando studi, leggi registraPrestito come se fosse una storia: “prima cerco lo strumento, poi chiedo se si può prestare, poi creo il record del prestito, poi aggiorno lo stato, poi restituisco il risultato.” Ogni frase corrisponde a una riga nel codice.

Passo per passo nel progetto

1. Apri application/registraPrestito.js e scrivi in linguaggio naturale cosa fa ogni riga.
2. Identifica la riga dove il flusso si biforca: caso di successo e caso di errore.
3. Verifica che ogni errore lanciato abbia un messaggio leggibile dall’utente.
4. Apri infrastructure/archivioStrumentiLocale.js e trova aggiornaStato: capisce la transizione o la esegue ciecamente?
5. Apri DevTools e fai un test completo: registra un prestito, poi tenta di prestare lo stesso strumento di nuovo. Verifica che il secondo tentativo lanci l’errore corretto.
6. Prepara la risposta alla domanda: “cosa succede se il browser si chiude a metà operazione?” (risposta onesta: tra aggiornaStato e salva c’è una finestra di inconsistenza — è un limite noto di localStorage).

Esempio da leggere lentamente

Questo è il codice completo di registraPrestito con commenti che spiegano ogni decisione:

// application/registraPrestito.js
import { puoEsserePrestato } from '../domain/regolePrestito.js';
import { archivioStrumenti } from '../infrastructure/archivioStrumentiLocale.js';
import { archivioPrestitiLocale } from '../infrastructure/archivioPrestitiLocale.js';

function registraPrestito(idStrumento, nomeStudente) {
  // Passo 1: verifica che lo strumento esista
  const strumento = archivioStrumenti.trova(idStrumento);
  if (!strumento) {
    throw new Error('Strumento non trovato');
  }

  // Passo 2: chiede al dominio se può essere prestato
  // NON scriviamo strumento.stato === 'disponibile' qui
  if (!puoEsserePrestato(strumento)) {
    throw new Error('Lo strumento non è disponibile per il prestito');
  }

  // Passo 3: costruisce il record del prestito
  const prestito = {
    id: crypto.randomUUID(),
    idStrumento,
    nomeStudente: nomeStudente.trim(),
    dataApertura: new Date().toISOString(),
    stato: 'aperto'
  };

  // Passo 4: aggiorna lo stato dello strumento
  archivioStrumenti.aggiornaStato(idStrumento, 'in_prestito');

  // Passo 5: salva il prestito
  archivioPrestitiLocale.salva(prestito);

  // Passo 6: restituisce il risultato alla UI
  return prestito;
}

Ogni importazione all’inizio dice esattamente da chi dipende il caso d’uso: domain/ e infrastructure/. Nessuna importazione da presentation/. Questo è il confine.

Prova di comprensione

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

• Quale file chiama registraPrestito e quale file viene chiamato da registraPrestito?
• Se uno strumento è in manutenzione, registraPrestito lancia un errore? In quale riga?
• Perché il caso d’uso aggiorna lo stato dello strumento e salva il prestito in due chiamate separate invece di una?
• Se crypto.randomUUID() non è disponibile nel browser target, in quale file devi apportare la modifica?

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

Errori da evitare

• scrivere strumento.stato === 'disponibile' dentro registraPrestito invece di chiamare puoEsserePrestato;
• importare localStorage direttamente in application/registraPrestito.js;
• non gestire il caso “strumento non trovato” e lasciare che il programma vada in crash;
• mostrare solo il risultato finale senza spiegare i passaggi intermedi;
• non avere una demo funzionante: la presentazione deve mostrare il flusso completo in azione.

Prodotto da consegnare

Prepara una demo di tre minuti che includa:

• partenza dalla UI con uno strumento disponibile;
• registrazione del prestito con nome reale;
• apertura di DevTools per mostrare il prestito in localStorage;
• cambio di stato dello strumento visibile nella lista;
• secondo tentativo di prestito dello stesso strumento con messaggio di errore visibile.

Checklist di chiusura

Prima di chiudere la lezione, controlla:

• sai spiegare i sei passi di registraPrestito senza guardare il codice;
• hai una demo funzionante che mostra sia il caso di successo sia l’errore;
• sai indicare dove viene chiamato il dominio e dove viene chiamata l’infrastruttura;
• hai verificato che le importazioni di registraPrestito non includono nulla da presentation/;
• sai rispondere alla domanda “e se lo strumento è guasto?”.

Risultato atteso

Alla fine lo studente deve saper dire:

registraPrestito è il caso d'uso che coordina l'apertura di un prestito.
Riceve idStrumento e nomeStudente dalla UI.
Cerca lo strumento nell'archivio, chiede al dominio se può essere prestato,
costruisce il record del prestito, aggiorna lo stato dello strumento e salva.
Non sa di localStorage né di HTML: lo sa solo chi lo chiama e chi lo serve.

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