Checklist: il caso d’uso conosce solo cio che deve conoscere

Questa checklist chiude il modulo sui casi d’uso.

Serve a controllare se stiamo davvero separando Application, Domain, Presentation e Infrastructure.

La domanda guida e:

Il caso d'uso conosce solo cio che gli serve per coordinare l'operazione?

Obiettivo

Revisionare i casi d’uso scritti finora:

• RegistraStrumento;
• CercaStrumenti;
• RegistraPrestito;
• ChiudiPrestito;
• ApriSegnalazioneGuasto.

Per ciascuno devi individuare:

• dipendenze corrette;
• dipendenze sospette;
• regole duplicate;
• dettagli UI entrati per errore;
• dettagli infrastrutturali troppo concreti.

Spiegazione guidata per studiare

Questa lezione va studiata su due piani. Il primo è il comportamento visibile del Registro del laboratorio: che cosa vede o fa l’utente quando registra uno strumento, cerca un dispositivo, apre un prestito o segnala un guasto. Il secondo è il confine architetturale: dove deve stare il codice che rende possibile quel comportamento.

Per checklist: il caso d’uso conosce solo cio che deve conoscere, il punto centrale è questo: Un caso d’uso coordina un’operazione completa: riceve un comando, legge ciò che serve, applica regole, salva il risultato e restituisce un esito.

Il rischio tipico è far diventare il caso d’uso una seconda UI o un secondo database. Deve coordinare, non mostrare HTML e non conoscere dettagli tecnici di salvataggio. Per evitarlo, non partire dal file che hai già aperto nell’editor. Parti dalla domanda: “quale responsabilità sto modificando?”. Se la risposta riguarda una regola del laboratorio, guarda il dominio. Se riguarda una sequenza di operazioni, guarda i casi d’uso. Se riguarda salvataggio, file, localStorage, API o database, guarda l’infrastruttura. Se riguarda input, pulsanti, form e messaggi, guarda la Presentation.

Il tempo è breve: non provare a fare tutto, punta a capire il concetto e produrre un risultato piccolo. Alla fine della lezione lo studente non deve ricordare una definizione a memoria: deve saper indicare un punto del progetto, spiegare perché quel codice sta lì e mostrare una verifica del comportamento.

Passo per passo nel progetto

1. Rileggi il titolo della lezione e riscrivilo come domanda pratica. Per esempio: “dove deve stare questa regola?”, “chi deve salvare questo dato?”, “come verifico questo errore?”.
2. Apri solo i file necessari. Se devi toccare più di tre file, fermati e scrivi prima una mini-mappa.
3. Definisci input e output del caso d’uso.
4. Leggi i dati attraverso un archivio o una dipendenza esplicita.
5. Chiama le regole del dominio.
6. Salva il risultato senza sapere come funziona la persistenza concreta.
7. Aggiorna una nota breve nel README o negli appunti se hai cambiato un confine del progetto.

Esempio da leggere lentamente

Questo esempio serve a ragionare, non a incollare codice senza capire:

function registraPrestito(comando, archivioStrumenti, archivioPrestiti) {
  const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);
  verificaStrumentoPrestabile(strumento);
  const prestito = apriPrestito(strumento.id, comando.nomePersona);
  archivioPrestiti.salva(prestito);
  archivioStrumenti.salva({ ...strumento, stato: "in_prestito" });
  return prestito;
}

Leggilo chiedendoti che cosa cambierebbe se domani sostituissimo la pagina web con una CLI, oppure localStorage con un’API. Se l’esempio continua ad avere senso senza riscrivere tutto, il confine è probabilmente buono. Se invece un dettaglio tecnico si propaga in molti file, il progetto sta tornando fragile.

Prova di comprensione

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

• Qual è la responsabilità principale trattata in questa lezione?
• In quale livello del progetto dovrebbe stare?
• Quale errore faresti se cercassi la soluzione più veloce?
• Quale piccolo test, controllo manuale o esempio dimostra che hai capito?
• Che cosa deve restare facile da cambiare dopo questa lezione?

Una risposta accettabile non deve essere lunga. Deve però usare parole concrete del Registro: strumento, prestito, stato, archivio, caso d’uso, messaggio, test.

Checklist generale

Per ogni caso d’uso rispondi.

## Nome caso d'uso

Riceve un comando chiaro?
- [ ] si
- [ ] no

Non legge direttamente input HTML?
- [ ] si
- [ ] no

Non mostra messaggi nella pagina?
- [ ] si
- [ ] no

Non usa direttamente localStorage?
- [ ] si
- [ ] no

Chiama funzioni del dominio per le regole?
- [ ] si
- [ ] no

Non duplica regole gia presenti nel dominio?
- [ ] si
- [ ] no

Usa archivi o funzioni dedicate per leggere e salvare?
- [ ] si
- [ ] no

Restituisce un risultato chiaro?
- [ ] si
- [ ] no

E testabile senza browser?
- [ ] si
- [ ] no

Se una risposta e “no”, non e una colpa. E una indicazione precisa per il prossimo refactoring.

Cose che un caso d’uso puo conoscere

Un caso d’uso puo conoscere:

• il comando ricevuto;
• funzioni del dominio;
• archivi passati come dipendenze;
• errori di dominio o applicativi;
• oggetti restituiti dall’operazione.

Esempio:

verificaStrumentoPrestabile(strumento);
archivioStrumenti.trovaPerId(id);
archivioPrestiti.salva(prestito);

Queste dipendenze sono coerenti con Application.

Cose che un caso d’uso non dovrebbe conoscere

Segnali di problema:

document.querySelector("#nome")
button.addEventListener(...)
messaggioElement.textContent = ...
localStorage.setItem(...)
JSON.parse(localStorage.getItem(...))
document.createElement(...)

Questi dettagli appartengono ad altri livelli.

Non significa che siano sbagliati in assoluto. Significa che non devono stare nel caso d’uso.

Cattivo odore: dati globali

Esempio fragile:

export function registraPrestito(comando) {
  const strumento = strumenti.find((item) => item.id === comando.strumentoId);
  prestiti.push(nuovoPrestito);
}

Da dove arrivano strumenti e prestiti?

Se sono variabili globali, il caso d’uso e piu difficile da testare.

Meglio ricevere archivi:

export function creaRegistraPrestito({ archivioStrumenti, archivioPrestiti }) {
  return function registraPrestito(comando) {
    const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);
  };
}

Cattivo odore: regole duplicate

Se trovi lo stesso controllo in piu casi d’uso:

if (strumento.stato !== "disponibile") {
  throw new Error("STRUMENTO_NON_PRESTABILE");
}

chiediti:

Questa regola deve stare nel dominio?

Se la risposta e si, estraila in una funzione come:

verificaStrumentoPrestabile(strumento);

Cattivo odore: messaggi utente nel caso d’uso

Esempio sospetto:

return {
  messaggio: "Prestito registrato con successo!",
};

Non e sempre vietato, ma in questo corso preferiamo tenere i messaggi nella presentation.

Il caso d’uso puo restituire:

return { prestito, strumento };

La UI decide:

Prestito registrato.

Scheda di revisione

Compila per almeno due casi d’uso:

# Revisione caso d'uso

Caso d'uso:

Scopo:

Dipendenze corrette:
- ...

Dipendenze sospette:
- ...

Regole duplicate:
- ...

Dettagli UI presenti:
- ...

Dettagli infrastrutturali presenti:
- ...

Primo refactoring proposto:

Mini revisione con Codex

Puoi usare questo prompt:

Analizza questo caso d'uso. Non riscrivere il codice.
Indica solo:
- cosa appartiene al coordinamento applicativo;
- eventuali regole di dominio duplicate;
- eventuali dipendenze da UI;
- eventuali dipendenze da persistenza concreta;
- un primo refactoring piccolo.

Ricorda: Codex aiuta a vedere problemi, ma devi verificare tu le proposte.

Cosa produrre

Alla fine della lezione devi avere:

• checklist compilata per almeno due casi d’uso;
• una lista di dipendenze sospette;
• almeno un refactoring piccolo da fare;
• almeno uno scenario di test candidato;
• una nota su cosa spostare nel prossimo modulo.

Controllo finale del modulo

Il Modulo 7 e completato quando puoi rispondere si:

• so spiegare cosa fa un caso d’uso;
• ho distinto regole di dominio e coordinamento applicativo;
• ho casi d’uso chiamabili senza UI;
• i casi d’uso non leggono direttamente dal DOM;
• i casi d’uso non salvano direttamente in localStorage;
• le regole principali restano nel dominio;
• so quali dipendenze dovremo rendere piu sostituibili.

Nel prossimo modulo faremo il primo taglio architetturale completo: Domain, Application, Infrastructure e Presentation nella struttura del progetto.