Infrastructure come dettaglio sostituibile

Nel modulo precedente abbiamo preparato i casi d’uso a ricevere archivi dall’esterno.

Ora costruiamo davvero un archivio diverso.

Il punto di partenza e questo:

Infrastructure e il livello dei dettagli tecnici.

Nel Registro del laboratorio, infrastructure puo usare:

• memoria;
• localStorage;
• file JSON;
• database;
• API.

Il dominio e i casi d’uso non devono cambiare ogni volta che cambiamo uno di questi dettagli.

Obiettivo

Alla fine devi saper spiegare:

• che cosa mettiamo in Infrastructure;
• perche localStorage non deve stare nel dominio;
• perche JSON non deve invadere i casi d’uso;
• che cosa resta stabile quando cambia la persistenza.

Che cosa fa Infrastructure

Infrastructure si occupa di parlare con il mondo esterno al dominio.

Nel nostro progetto significa:

• salvare dati;
• leggere dati;
• serializzare e deserializzare JSON;
• gestire errori tecnici di lettura e scrittura;
• adattare formati esterni al modello interno;
• nascondere dettagli di browser, file, API o database.

Non decide le regole del laboratorio.

Cosa non deve fare

Infrastructure non deve decidere:

• se uno strumento guasto puo essere prestato;
• se un prestito chiuso puo essere chiuso di nuovo;
• se uno strumento senza nome e valido;
• quale messaggio mostrare all’utente;
• quali bottoni compaiono nella pagina.

Queste responsabilita stanno altrove.

Esempio sbagliato

export function salvaPrestito(prestito) {
  if (prestito.strumento.stato === "guasto") {
    throw new Error("STRUMENTO_NON_PRESTABILE");
  }

  localStorage.setItem("prestito", JSON.stringify(prestito));
}

Qui infrastructure sta controllando una regola di dominio.

Non va bene.

Il controllo deve essere gia avvenuto prima, nel dominio e nel caso d’uso.

Esempio migliore

export function salva(prestito) {
  const prestiti = leggiPrestiti();
  const aggiornati = aggiornaLista(prestiti, prestito);
  localStorage.setItem("prestiti", JSON.stringify(aggiornati));

  return prestito;
}

Qui infrastructure salva.

Non decide se il prestito e valido.

Dettaglio sostituibile

Se il caso d’uso usa il contratto:

archivioStrumenti.salva(strumento);
archivioStrumenti.trovaPerId(id);
archivioStrumenti.tutti();

allora possiamo avere implementazioni diverse:

creaArchivioStrumentiInMemoria()
creaArchivioStrumentiLocalStorage()
creaArchivioStrumentiJson()
creaArchivioStrumentiApi()

Il caso d’uso resta stabile.

Questo e il risultato pratico del modulo.

localStorage non e il dominio

localStorage e una tecnologia del browser.

Permette di salvare stringhe associate a chiavi:

localStorage.setItem("strumenti", "...json...");
localStorage.getItem("strumenti");

Il dominio non deve sapere che i dati sono stringhe nel browser.

Il dominio deve sapere:

che cosa e uno strumento valido

non:

quale chiave localStorage contiene gli strumenti

Cosa resta stabile

Quando passiamo da memoria a localStorage, dovrebbero restare stabili:

• Strumento;
• Prestito;
• StatoStrumento;
• regole del dominio;
• casi d’uso;
• contratti degli archivi;
• UI, se riceve gli stessi risultati.

Dovrebbero cambiare:

• file in infrastructure;
• composizione in main.js;
• test specifici sull’archivio;
• gestione di errori tecnici.

Esercizio

Classifica:

1. JSON.parse(localStorage.getItem("strumenti"))
2. Uno strumento guasto non puo essere prestato
3. archivioStrumenti.salva(strumento)
4. button.addEventListener("click", ...)
5. mapping da DTO a Strumento
6. mostrare "Strumento non trovato"

Soluzione possibile:

1. Infrastructure
2. Domain
3. Application usa un contratto
4. Presentation
5. Infrastructure
6. Presentation

Cosa produrre

Alla fine della lezione devi avere:

• una lista dei dettagli infrastrutturali del progetto;
• una lista di cose che non devono stare in infrastructure;
• una nota su cosa cambiera passando a localStorage;
• una nota su cosa deve restare stabile.

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 infrastructure come dettaglio sostituibile, il punto centrale è questo: L’infrastruttura è il bordo tecnico: salva, legge, chiama API, usa localStorage o file JSON. È importante, ma deve restare sostituibile.

Il rischio tipico è far entrare il formato salvato dentro il dominio. Un oggetto comodo per localStorage non è automaticamente il modello con cui ragiona il progetto. 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 è sufficiente per alternare spiegazione, modifica guidata e revisione. 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. Distingui modello di dominio e formato salvato.
4. Crea una funzione di mapping leggibile.
5. Gestisci dati mancanti o non validi.
6. Verifica che i casi d’uso non cambino quando cambi archivio.
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 strumentoToDTO(strumento) {
  return {
    id: strumento.id,
    name: strumento.nome,
    category: strumento.categoria,
    status: strumento.stato
  };
}

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.

Controllo finale

La lezione e completata quando puoi rispondere si:

• so cosa fa Infrastructure;
• so perche localStorage e un dettaglio tecnico;
• so perche le regole non stanno nell’archivio;
• so quali file cambieranno nella nuova persistenza;
• so cosa deve restare uguale.

Nella prossima lezione distinguiamo oggetti di dominio e dati serializzabili.