Cartelle minime: domain, application, infrastructure, presentation

Ora trasformiamo la mappa in struttura del progetto.

Non servono molte cartelle.

Servono cartelle con un significato chiaro.

src/
  domain/
  application/
  infrastructure/
  presentation/

Questa e la prima forma leggibile del Registro del laboratorio.

Obiettivo

Alla fine devi avere:

• quattro cartelle principali;
• file spostati nel posto giusto;
• un punto di avvio riconoscibile;
• una struttura che un compagno riesce a leggere senza spiegazioni lunghe.

Struttura proposta

Una struttura minima puo essere:

registro-laboratorio/
  index.html
  src/
    main.js
    domain/
      strumento.js
      statoStrumento.js
      prestito.js
      erroriDominio.js
    application/
      registraStrumento.js
      cercaStrumenti.js
      registraPrestito.js
      chiudiPrestito.js
      apriSegnalazioneGuasto.js
    infrastructure/
      archivioStrumentiInMemoria.js
      archivioPrestitiInMemoria.js
      archivioSegnalazioniGuastoInMemoria.js
    presentation/
      uiRegistro.js
      messaggiErrore.js

Non devi avere per forza tutti questi file subito.

La struttura indica la direzione.

Domain

Qui mettiamo:

• modelli;
• stati;
• regole;
• invarianti;
• errori di dominio.

Esempi:

domain/strumento.js
domain/statoStrumento.js
domain/prestito.js
domain/segnalazioneGuasto.js
domain/erroriDominio.js

Non mettere qui:

• codice HTML;
• document.querySelector;
• localStorage;
• fetch;
• messaggi utente lunghi;
• funzioni di rendering.

Application

Qui mettiamo i casi d’uso.

Esempi:

application/registraStrumento.js
application/cercaStrumenti.js
application/registraPrestito.js
application/chiudiPrestito.js
application/apriSegnalazioneGuasto.js

Ogni file deve rispondere a una domanda:

Quale operazione del sistema coordina?

Se la risposta e “gestisce un po’ tutto”, il file e troppo generico.

Infrastructure

Qui mettiamo i dettagli di salvataggio.

Per ora:

infrastructure/archivioStrumentiInMemoria.js
infrastructure/archivioPrestitiInMemoria.js

Piu avanti:

infrastructure/archivioStrumentiLocalStorage.js
infrastructure/archivioPrestitiLocalStorage.js

La parola importante e archivio: ci aiuta a non legare il caso d’uso a un dettaglio specifico.

Presentation

Qui mettiamo codice che parla con l’utente.

Esempi:

presentation/uiRegistro.js
presentation/messaggiErrore.js

Responsabilita:

• leggere input;
• costruire comandi;
• chiamare casi d’uso;
• aggiornare la pagina;
• mostrare messaggi.

Non mettere qui regole come:

uno strumento guasto non puo essere prestato

La UI puo mostrare o nascondere elementi, ma la regola deve restare nel dominio.

Main come punto di composizione

Il file main.js puo diventare il punto in cui colleghiamo tutto:

const archivioStrumenti = creaArchivioStrumentiInMemoria();

const registraStrumento = creaRegistraStrumento({
  archivioStrumenti,
});

avviaUIRegistro({
  registraStrumento,
});

main.js non deve contenere tutte le regole.

Deve comporre i pezzi.

Spostare a piccoli passi

Non spostare tutto insieme.

Procedi cosi:

1. crea le cartelle;
2. sposta un file o una funzione di dominio;
3. correggi gli import;
4. verifica che il progetto funzioni;
5. sposta un caso d’uso;
6. verifica di nuovo;
7. sposta infrastruttura e UI.

Il refactoring deve restare controllabile.

Esercizio

Parti dalla tua struttura attuale.

Disegna:

Prima:

Dopo:

Esempio:

Prima:
src/
  main.js

Dopo:
src/
  main.js
  domain/
  application/
  infrastructure/
  presentation/

Poi scegli tre funzioni da spostare e indica dove andranno.

Cosa produrre

Alla fine della lezione devi avere:

• cartelle domain, application, infrastructure, presentation;
• almeno un file per domain;
• almeno un file per application;
• almeno un file per infrastructure;
• almeno un file o sezione per presentation;
• una nota nel README sulla struttura.

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 cartelle minime: domain, application, infrastructure, presentation, il punto centrale è questo: La Presentation è il livello che parla con la persona: riceve input, mostra risultati e traduce errori in messaggi comprensibili. Non deve decidere le regole importanti.

Il rischio tipico è scrivere una condizione nel gestore del click perché sembra più veloce. Quel codice funziona oggi, ma domani viene copiato in un altro pulsante e la regola si sdoppia. 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. Individua quale input arriva dall’utente.
4. Trasformalo in un comando con nomi chiari.
5. Chiama un caso d’uso senza leggere direttamente archivi o localStorage.
6. Mostra il risultato senza ricreare le regole nella UI.
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:

// Bordo della UI: prepara un comando, non decide la regola.
const comando = {
  strumentoId: inputStrumento.value,
  nomePersona: inputPersona.value
};

const esito = registraPrestito(comando);
mostraMessaggio(esito.messaggio);

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:

• le cartelle hanno nomi chiari;
• ogni cartella ha una responsabilita;
• main.js non e piu il contenitore di tutto;
• so dove aggiungere un nuovo caso d’uso;
• so dove aggiungere un nuovo archivio;
• so dove sta il codice della UI.

Nella prossima lezione spostiamo il dominio fuori dalla UI.