Spiegare come viene salvato il dato

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

Durante la presentazione finale uno dei momenti più importanti è questo: mostrare come un dato percorre il sistema dall’interfaccia fino alla memoria. Non basta dire “salviamo in localStorage” — devi saper tracciare ogni passaggio e spiegarlo con parole semplici.

Obiettivo della lezione

In questa lezione impari a raccontare in modo chiaro e ordinato il flusso di salvataggio di un dato nel Registro, dal momento in cui l’utente preme un pulsante fino al JSON che appare in localStorage. Impari anche a mostrare il codice rilevante durante la presentazione senza perderti.

Alla fine devi avere un risultato verificabile: uno script parlato per il flusso di salvataggio e la capacità di aprire DevTools e mostrare il dato salvato in diretta.

Il flusso visuale da presentare

Quando l’utente preme “Registra strumento” nel Registro, questo è ciò che accade nei quattro livelli:

UI (Presentation)
  ↓ raccoglie { nome, categoria, stato }
  ↓ chiama registraStrumento(input)

Application (caso d'uso)
  ↓ valida che nome non sia vuoto
  ↓ costruisce l'oggetto Strumento con ID generato
  ↓ chiama archivio.salva(strumento)

Infrastructure (localStorage)
  ↓ serializza in JSON
  ↓ scrive in localStorage["registro_strumenti"]

Domain
  (non tocca localStorage: conosce solo le regole)

Questo flusso è il cuore della tua presentazione. Devi saperlo tracciare a voce e mostrarlo nel codice.

Script parlato per la presentazione

Prepara queste quattro frasi da dire mentre mostri il codice:

Presentation: “L’utente compila il form e preme il pulsante. La pagina raccoglie nome, categoria e stato iniziale, poi chiama il caso d’uso senza sapere nulla di come viene salvato.”

Application: “Il caso d’uso registraStrumento riceve i dati, verifica che il nome non sia vuoto, costruisce l’oggetto Strumento con un ID univoco e passa l’oggetto all’archivio.”

Infrastructure: “L’archivio prende l’oggetto, lo trasforma in JSON con JSON.stringify e lo scrive in localStorage. Se apriamo DevTools vediamo esattamente questa struttura.”

Domain: “Le regole di dominio — per esempio che uno strumento nasce sempre come disponibile — sono rispettate prima ancora di arrivare all’archivio. Il dominio non sa nulla di localStorage.”

Procedura guidata

1. Apri il file application/registraStrumento.js e individua la funzione principale.
2. Apri il file infrastructure/archivioStrumentiLocale.js e trova il metodo salva.
3. Prepara un tab del browser con DevTools aperto su Application → localStorage.
4. Durante la presentazione esegui la registrazione di uno strumento reale (“Trapano Bosch”, categoria “elettrico”, stato “disponibile”).
5. Mostra il JSON risultante in localStorage e commenta la struttura chiave per chiave.
6. Spiega perché registraStrumento.js non contiene mai la parola localStorage.
7. Rispondi alla domanda: “cosa succede se domani vogliamo salvare su un server?” — la risposta è: cambiamo solo l’archivio, il caso d’uso non si tocca.

Attività in classe

Compila questa scheda prima della presentazione:

## Il flusso di salvataggio nel Registro

Dato salvato:
  nome dello strumento: _______________
  categoria: _______________
  stato iniziale: _______________

Funzione di Application chiamata dalla UI:
  _______________

Metodo di Infrastructure che scrive in localStorage:
  _______________

Chiave localStorage usata:
  _______________

Struttura JSON del dato salvato (scrivi l'oggetto a mano):
  {
    id: "_______________",
    nome: "_______________",
    categoria: "_______________",
    stato: "_______________"
  }

Frase che spieghi perché il domain non tocca localStorage:
  _______________

Se lavori in gruppo, una persona fa la demo e un’altra descrive il livello che sta vedendo sullo schermo.

Spiegazione guidata per studiare

Il flusso di salvataggio è l’esempio più concreto di come l’architettura a livelli funziona davvero. Quando lo spieghi, non stai elencando regole astratte: stai mostrando una decisione reale con un effetto misurabile.

Il punto centrale è la separazione: il caso d’uso registraStrumento non sa dove viene salvato il dato. Sa solo che esiste qualcosa che si comporta come un archivio — riceve uno strumento e lo conserva. Questa ignoranza è voluta. Significa che se domani localStorage smette di bastare e usi un database, il caso d’uso non cambia di una virgola.

Quando studi, traccia il flusso su carta. Scrivi i nomi delle funzioni reali, non solo i livelli. Poi apri i file corrispondenti e verifica che il flusso che hai disegnato corrisponda al codice. Se non corrisponde, il tuo modello mentale ha un errore da correggere prima della presentazione.

La cosa che i docenti verificano di solito è questa: lo studente sa indicare un punto preciso nel codice per ognuno dei quattro livelli? Se sai rispondere a quella domanda con la mano sul file, sei pronto.

Passo per passo nel progetto

1. Apri src/presentation/formRegistraStrumento.js (o equivalente) e identifica dove viene chiamato il caso d’uso.
2. Apri src/application/registraStrumento.js e leggi dall’inizio alla fine: dove valida, dove costruisce, dove chiama l’archivio.
3. Apri src/infrastructure/archivioStrumentiLocale.js e trova il metodo salva: dove fa JSON.stringify, dove fa localStorage.setItem.
4. Apri il browser, vai in DevTools → Application → Local Storage e osserva la chiave registro_strumenti.
5. Fai una registrazione di test e osserva il JSON aggiornarsi in tempo reale.
6. Nota la struttura del singolo oggetto: id, nome, categoria, stato. Questi campi vengono dal dominio, non dall’infrastruttura.
7. Scrivi nel tuo script: “il dato passa da UI ad Application ad Infrastructure. Il Domain definisce la struttura ma non salva nulla.”

Esempio da leggere lentamente

Questo è il codice minimo che mostra il flusso completo. Leggilo un livello alla volta:

// presentation/formRegistraStrumento.js
function onClickRegistra() {
  const input = {
    nome: document.getElementById('nome').value,
    categoria: document.getElementById('categoria').value
  };
  registraStrumento(input);          // chiama Application, non sa di localStorage
}

// application/registraStrumento.js
function registraStrumento(input) {
  if (!input.nome || input.nome.trim() === '') {
    throw new Error('Il nome dello strumento è obbligatorio');
  }
  const strumento = {
    id: crypto.randomUUID(),
    nome: input.nome.trim(),
    categoria: input.categoria,
    stato: 'disponibile'             // regola di dominio: nasce disponibile
  };
  archivioStrumenti.salva(strumento); // chiama Infrastructure, non sa come salva
}

// infrastructure/archivioStrumentiLocale.js
const archivioStrumenti = {
  salva(strumento) {
    const tutti = this._leggiTutti();
    tutti.push(strumento);
    localStorage.setItem(            // solo qui appare localStorage
      'registro_strumenti',
      JSON.stringify(tutti)
    );
  },
  _leggiTutti() {
    const raw = localStorage.getItem('registro_strumenti');
    return raw ? JSON.parse(raw) : [];
  }
};

Nota: localStorage appare una sola volta, nell’archivio. Né la UI né il caso d’uso lo toccano. Se devi spiegarlo in presentazione, questo è il punto da mostrare.

Prova di comprensione

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

• Quale funzione chiama la UI per avviare il salvataggio?
• Dove viene generato l’ID dello strumento — in quale livello e in quale file?
• Perché registraStrumento.js non contiene localStorage.setItem?
• Se apri DevTools dopo la registrazione, quale chiave trovi in localStorage e come è strutturato il valore?
• Come risponderesti alla domanda: “e se domani vogliamo salvare su un server?”

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

Errori da evitare

• mostrare solo il codice Infrastructure senza spiegare chi lo chiama e perché;
• confondere “dove salviamo” con “come decidiamo cosa salvare” — sono due livelli diversi;
• fare la demo senza DevTools aperti: il JSON in localStorage è la prova visiva più convincente;
• dire “salviamo in localStorage” senza spiegare che quella scelta è isolata nell’archivio;
• leggere il codice riga per riga invece di raccontare il flusso con parole proprie.

Prodotto da consegnare

Prepara una demo di due minuti che includa:

• compilazione del form con dati reali;
• apertura di DevTools mentre il dato viene salvato;
• lettura del JSON risultante con spiegazione di ogni campo;
• risposta alla domanda: “chi sa di localStorage in questo progetto?”.

La demo deve funzionare senza connessione di rete (è browser-only).

Checklist di chiusura

Prima di chiudere la lezione, controlla:

• sai nominare le quattro funzioni/metodi coinvolti nel flusso di salvataggio;
• hai aperto DevTools e visto il JSON in localStorage;
• sai spiegare perché il caso d’uso non importa localStorage direttamente;
• hai preparato la frase “se cambiassimo la persistenza, cambieremmo solo…”;
• la demo funziona senza connessione.

Risultato atteso

Alla fine lo studente deve saper dire:

Quando l'utente preme "Registra strumento", la UI chiama registraStrumento().
Il caso d'uso valida il nome, genera l'ID e chiama archivioStrumenti.salva().
L'archivio serializza l'oggetto in JSON e lo scrive in localStorage["registro_strumenti"].
Il domain non tocca mai localStorage: definisce la struttura e le regole, non persiste.
In DevTools posso mostrare la chiave e il JSON corrispondente.

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