Descrivere cartelle, livelli e punto di avvio

Questa lezione appartiene al Modulo 15 — Documentazione.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione impari a descrivere la struttura del progetto in modo chiaro — nel README e a voce — in modo che chiunque possa orientarsi senza doverti chiedere spiegazioni.

Obiettivo della lezione

Scrivere nel README la descrizione delle quattro cartelle del Registro, con il ruolo di ognuna e almeno un esempio di file per livello. Essere in grado di spiegare verbalmente la struttura in meno di 2 minuti.

Alla fine devi avere: la sezione “Struttura del progetto” nel README completa e la spiegazione verbale preparata.

La struttura del Registro

Il Registro ha questa struttura di cartelle:

src/
  domain/
    strumento.js
    prestito.js
  application/
    apriPrestito.js
    chiudiPrestito.js
    segnalaGuasto.js
    cercaStrumenti.js
    registraStrumento.js
  infrastructure/
    archivioStrumentiLocalStorage.js
    archivioPrestitiLocalStorage.js
  presentation/
    azioni.js
main.js
index.html

Ogni cartella ha un ruolo preciso e dipendenze precise tra loro.

Il ruolo di ogni livello

domain/ — le regole del laboratorio. Contiene i modelli Strumento e Prestito con le loro regole (es. uno strumento guasto non può essere prestato). Non importa nulla dagli altri livelli. È il nucleo del sistema.

application/ — i casi d’uso. Contiene le operazioni che l’utente può fare: aprire un prestito, cercare strumenti, segnalare un guasto. Coordina domain e infrastructure senza contenere logica di business. Importa da domain e riceve gli archivi come parametri.

infrastructure/ — la persistenza. Contiene gli adapter che leggono e scrivono localStorage. Sa come trasformare gli oggetti del dominio in JSON e viceversa. Importa da domain per usare i modelli.

presentation/ — l’interfaccia utente. Contiene i gestori degli eventi (click sui pulsanti, submit dei form). Legge l’input, chiama i casi d’uso, mostra i risultati. Importa da application. Non tocca mai localStorage direttamente.

main.js — il punto di composizione. Importa da tutti i livelli e collega le parti. È l’unico file che “conosce” tutta la struttura. È piccolo — fa solo import e wiring.

Procedura guidata

1. Apri il README del Registro.
2. Scrivi la sezione “Struttura del progetto” con la descrizione di ogni cartella.
3. Per ogni livello, indica almeno un file e il suo ruolo.
4. Descrivi il flusso delle dipendenze in una riga.
5. Spiega il ruolo di main.js come punto di composizione.
6. Prova a spiegare verbalmente la struttura a un compagno in meno di 2 minuti.

Attività in classe

Completa questa bozza di sezione README:

## Struttura del progetto

src/
  domain/         — [scrivi il ruolo]
    strumento.js  — [scrivi cosa contiene]
    prestito.js   — [scrivi cosa contiene]
  application/    — [scrivi il ruolo]
    apriPrestito.js — [scrivi cosa fa]
    [altri file]
  infrastructure/ — [scrivi il ruolo]
    archivioStrumentiLocalStorage.js — [scrivi cosa fa]
  presentation/   — [scrivi il ruolo]
    azioni.js     — [scrivi cosa contiene]
main.js           — [scrivi il ruolo]

Flusso delle dipendenze: [una frase]

Spiegazione guidata per studiare

Descrivere la struttura del progetto non è un esercizio di scrittura — è un test di comprensione. Se non sai spiegare perché apriPrestito.js sta in application/ e non in domain/, non hai ancora capito la separazione dei livelli.

La spiegazione verbale è particolarmente importante: durante la presentazione il docente potrebbe chiederti “perché hai messo questa cosa qui?”. Se sai rispondere in modo preciso, dimostri di aver fatto scelte consapevoli. Se rispondi “è sembrato il posto giusto”, dimostri di aver seguito uno schema senza capirlo.

Passo per passo nel progetto

1. Scrivi la sezione “Struttura del progetto” nel README. Versione completa:

## Struttura del progetto

src/
  domain/         — regole e modelli del laboratorio
    strumento.js  — modello Strumento con gli stati validi (disponibile, in-prestito, guasto)
    prestito.js   — modello Prestito con apertura e chiusura
  application/    — casi d'uso: operazioni che l'utente può eseguire
    apriPrestito.js     — apre un prestito se lo strumento è disponibile
    chiudiPrestito.js   — chiude un prestito e riporta lo strumento a disponibile
    segnalaGuasto.js    — cambia lo stato dello strumento a guasto
    cercaStrumenti.js   — filtra gli strumenti per nome, categoria o stato
    registraStrumento.js — aggiunge un nuovo strumento al catalogo
  infrastructure/ — adapter per la persistenza in localStorage
    archivioStrumentiLocalStorage.js — legge e scrive gli strumenti in localStorage
    archivioPrestitiLocalStorage.js  — legge e scrive i prestiti in localStorage
  presentation/   — gestori degli eventi dell'interfaccia utente
    azioni.js     — collega i pulsanti ai casi d'uso, mostra messaggi all'utente
main.js           — punto di composizione: importa tutto, collega presentation e application

Flusso delle dipendenze:
presentation → application → domain
infrastructure → domain (usa i modelli per la mappatura)
main.js conosce tutti i livelli e li connette

1. Scrivi la spiegazione verbale. Prova a dirla ad alta voce in 2 minuti:

Il Registro è diviso in quattro livelli.

Il dominio contiene le regole: uno strumento può essere disponibile, in prestito o guasto.
Queste regole non cambiano mai — non dipendono dal browser, da localStorage, da nulla di tecnico.

L'application contiene i casi d'uso: aprire un prestito, cercare uno strumento, segnalare un guasto.
Ogni caso d'uso fa una sola cosa e coordina dominio e infrastruttura.

L'infrastruttura salva e carica i dati da localStorage.
È l'unica parte del sistema che tocca localStorage.
Se domani sostituiamo localStorage con un database, cambia solo questa cartella.

La presentation gestisce i pulsanti e i form.
Quando l'utente clicca Presta, la presentation chiama il caso d'uso apriPrestito e mostra il risultato.
Non contiene logica di business.

Main.js è il punto di composizione: importa da tutti i livelli e li collega.
È piccolo — fa solo wiring, non logica.

1. Aggiungi nel README un diagramma semplice delle dipendenze:

## Dipendenze tra livelli

presentation → application → domain
infrastructure → domain

main.js connette tutti i livelli all'avvio

Esempio JS — main.js come punto di composizione

// main.js — il file più piccolo, ma il più importante per capire la struttura

// importa l'infrastruttura
import * as archivioStrumenti from "./src/infrastructure/archivioStrumentiLocalStorage.js";
import * as archivioPrestiti from "./src/infrastructure/archivioPrestitiLocalStorage.js";

// importa i casi d'uso
import { apriPrestito } from "./src/application/apriPrestito.js";
import { chiudiPrestito } from "./src/application/chiudiPrestito.js";
import { segnalaGuasto } from "./src/application/segnalaGuasto.js";
import { cercaStrumenti } from "./src/application/cercaStrumenti.js";

// importa la presentation
import { inizializzaUI } from "./src/presentation/azioni.js";

// composizione: passa gli archivi e i casi d'uso alla UI
inizializzaUI({
  archivioStrumenti,
  archivioPrestiti,
  apriPrestito,
  chiudiPrestito,
  segnalaGuasto,
  cercaStrumenti
});

Questo file mostra la struttura del progetto in poche righe: chi dipende da chi, cosa viene importato da dove.

Prova di comprensione

Rispondi per iscritto:

• Perché main.js importa da tutti i livelli ma gli altri file non lo fanno?
• Cosa succederebbe se archivioStrumentiLocalStorage.js importasse da presentation/?
• Come spiegheresti a voce la differenza tra domain e application a qualcuno che non ha mai sentito parlare di architettura del software?
• Qual è il vantaggio di avere un file main.js piccolo invece di mettere tutto il wiring in azioni.js?

Errori da evitare

• non avere una sezione “Struttura del progetto” nel README;
• descrivere le cartelle in modo generico (“contiene i file di logica”) invece di specifico;
• non citare le dipendenze tra livelli — la struttura senza le dipendenze non spiega l’architettura;
• non aver mai provato a spiegare verbalmente la struttura prima della presentazione.

Prodotto da consegnare

La sezione “Struttura del progetto” nel README completa, con descrizione di ogni livello e almeno un file di esempio per livello. Come verifica: chiedi a un compagno di leggere la sezione e di spiegarti come è strutturato il progetto — se riesce senza aiuto, la sezione è ben scritta.

Checklist di chiusura

• la sezione “Struttura del progetto” è nel README;
• ogni livello ha una descrizione di una riga e almeno un file di esempio;
• le dipendenze tra livelli sono indicate esplicitamente;
• il ruolo di main.js come punto di composizione è descritto;
• ho provato la spiegazione verbale e dura meno di 2 minuti.

Risultato atteso

Ho scritto la sezione "Struttura del progetto" nel README con 4 livelli descritti.
Il compagno ha letto la sezione e ha capito la struttura senza domande.
La spiegazione verbale dura 1 minuto e 40 secondi.
main.js è descritto come punto di composizione con il suo ruolo di wiring.