Preparazione del laboratorio

Questa prima lezione non parte subito dall’architettura. Parte dal banco di lavoro.

Prima di parlare di dominio, casi d’uso, interfaccia e persistenza, serve un progetto piccolo, avviabile e comprensibile. Se il progetto non parte, se i file non sono chiari o se nessuno sa dove mettere le prime modifiche, ogni discorso sull’architettura diventa astratto.

L’obiettivo di questa lezione è semplice: creare il primo punto stabile del Registro del laboratorio scolastico. Non deve essere completo. Non deve essere elegante. Deve però essere abbastanza ordinato da poter crescere nelle lezioni successive.

Perché iniziamo da qui

Molti progetti diventano confusi non perché partono male dal punto di vista tecnico, ma perché partono senza una forma condivisa.

All’inizio sembra tutto facile:

• mettiamo i dati in un array;
• scriviamo un po’ di HTML;
• aggiungiamo un pulsante;
• salviamo qualcosa nel browser;
• sistemiamo dopo.

Il problema è proprio quel “sistemiamo dopo”. Se non abbiamo un minimo di struttura, dopo non sappiamo più dove intervenire. Una regola finisce dentro un click, un messaggio utente viene copiato in tre punti, il salvataggio viene mescolato alla logica, e il progetto diventa fragile molto prima di essere grande.

In questa lezione prepariamo quindi un terreno pulito: pochi file, nomi chiari, dati realistici, un README iniziale e alcune regole che ancora non implementiamo ma che useremo come guida.

Obiettivo della lezione

Alla fine della lezione devi avere:

• una cartella o repository dedicato al progetto;
• un file README.md con spiegazione minima;
• una struttura iniziale di file;
• alcuni dati di esempio sugli strumenti del laboratorio;
• una pagina HTML avviabile nel browser;
• un file JavaScript collegato come modulo;
• una prima lista di regole da verificare nelle lezioni successive;
• una verifica manuale che dimostra che tutto parte.

Il progetto può essere molto semplice. Deve però essere leggibile da una persona che non era accanto a te mentre lo scrivevi.

Che cosa non facciamo ancora

In questa lezione non introduciamo ancora:

• database;
• API;
• localStorage;
• framework frontend;
• sistema di autenticazione;
• test automatici;
• cartelle architetturali definitive.

Questa scelta è intenzionale. Prima costruiamo una base minima. Poi, nelle prossime lezioni, faremo crescere il progetto e vedremo perché serve separare responsabilità diverse.

Il progetto guida

Il Registro del laboratorio scolastico serve a gestire strumenti e dispositivi presenti in un laboratorio o in un’aula tecnica.

Esempi concreti:

• notebook;
• tablet;
• kit Arduino;
• sensori;
• alimentatori;
• cavi;
• adattatori;
• strumenti guasti;
• strumenti in manutenzione.

Nel corso il Registro dovrà permettere di:

• registrare strumenti;
• cercarli per nome, categoria o stato;
• segnare se sono disponibili, in prestito, guasti o in manutenzione;
• registrare prestiti;
• chiudere prestiti;
• aprire segnalazioni di guasto;
• salvare i dati;
• mostrare messaggi comprensibili;
• verificare le regole principali.

Oggi non implementiamo tutto questo. Oggi prepariamo il posto in cui tutto questo potrà essere costruito.

Crea la cartella progetto

Scegli un nome chiaro:

registro-laboratorio

Dentro la cartella crea questa struttura:

registro-laboratorio/
  README.md
  index.html
  src/
    main.js
    datiIniziali.js

Questa non è ancora l’architettura finale del corso. Non stiamo ancora dividendo in domain, application, infrastructure e presentation.

Per ora ci basta una struttura minima:

• README.md spiega il progetto;
• index.html è la pagina di ingresso;
• src/main.js contiene il primo codice JavaScript;
• src/datiIniziali.js contiene dati finti ma realistici.

Questa scelta ci permette di partire senza introdurre troppi concetti insieme.

Scrivi il README iniziale

Il README è il primo documento tecnico del progetto. Non deve essere lungo, ma deve rispondere subito a tre domande:

1. Che cosa stiamo costruendo?
2. Come si avvia?
3. Quali funzionalità vogliamo costruire?

Scrivi questo contenuto iniziale:

# Registro del laboratorio scolastico

Piccola applicazione didattica per registrare strumenti del laboratorio,
cercarli, gestire prestiti e segnalare guasti.

## Come si avvia

Aprire `index.html` nel browser.

## Funzionalità previste

- registrare uno strumento;
- cercare strumenti per nome, categoria o stato;
- registrare un prestito;
- chiudere un prestito;
- segnalare un guasto;
- salvare i dati.

Non scrivere nel README cose che il progetto non fa ancora. Va bene dire “funzionalità previste”, perché sono obiettivi del percorso. Non va bene dire “il progetto salva i dati in modo permanente” se ancora non lo fa.

Una buona documentazione non gonfia il progetto. Lo descrive con precisione.

Prepara i dati iniziali

Nel file src/datiIniziali.js crea una piccola lista di strumenti:

export const strumentiIniziali = [
  {
    id: "str-001",
    nome: "Notebook Lenovo 01",
    categoria: "notebook",
    stato: "disponibile",
  },
  {
    id: "str-002",
    nome: "Kit Arduino Base",
    categoria: "elettronica",
    stato: "disponibile",
  },
  {
    id: "str-003",
    nome: "Tablet laboratorio 03",
    categoria: "tablet",
    stato: "guasto",
  },
];

Questi dati non sono ancora un modello di dominio completo. Sono dati di partenza.

Sono però già utili perché introducono parole che useremo per tutto il corso:

• id: identifica uno strumento;
• nome: descrive lo strumento in modo leggibile;
• categoria: permette di raggruppare strumenti simili;
• stato: dice se lo strumento è utilizzabile, guasto o impegnato.

Usare dati realistici è importante. Se gli esempi sono troppo finti, anche le regole sembrano finte. Se invece usiamo oggetti che potrebbero stare davvero in un laboratorio scolastico, diventa più facile capire perché certe decisioni contano.

Crea una pagina minima

Nel file index.html prepara una pagina essenziale:

<!doctype html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Registro del laboratorio</title>
  </head>
  <body>
    <h1>Registro del laboratorio scolastico</h1>
    <main id="app"></main>

    <script type="module" src="./src/main.js"></script>
  </body>
</html>

La riga più importante, per il nostro percorso, è questa:

<script type="module" src="./src/main.js"></script>

type="module" ci permette di usare import ed export, cioè di dividere il codice in file diversi. Per ora lo facciamo solo con i dati iniziali. Più avanti questa possibilità ci servirà per separare responsabilità molto più importanti.

Mostra gli strumenti nella pagina

Nel file src/main.js importa i dati e mostrali nella pagina:

import { strumentiIniziali } from "./datiIniziali.js";

const app = document.querySelector("#app");

function creaRigaStrumento(strumento) {
  return `
    <li>
      <strong>${strumento.nome}</strong>
      <span>${strumento.categoria}</span>
      <em>${strumento.stato}</em>
    </li>
  `;
}

function mostraStrumenti(strumenti) {
  app.innerHTML = `
    <section>
      <h2>Strumenti registrati</h2>
      <ul>
        ${strumenti.map(creaRigaStrumento).join("")}
      </ul>
    </section>
  `;
}

mostraStrumenti(strumentiIniziali);

Questo codice è ancora molto semplice. Contiene già, però, alcune scelte utili:

• i dati stanno in un file separato;
• la funzione creaRigaStrumento ha un compito piccolo;
• la funzione mostraStrumenti si occupa della visualizzazione;
• il codice di avvio è leggibile.

Non stiamo ancora facendo architettura “grande”. Stiamo creando buone abitudini piccole.

Verifica manuale

Apri index.html nel browser.

Controlla che:

• la pagina si apra senza errori;
• il titolo sia visibile;
• gli strumenti siano mostrati;
• per ogni strumento compaiano nome, categoria e stato.

Poi apri gli strumenti per sviluppatori del browser e controlla la console. Non devono comparire errori rossi.

Se vedi un errore del tipo:

Cannot use import statement outside a module

controlla che nel file HTML ci sia:

<script type="module" src="./src/main.js"></script>

Se vedi un errore sul percorso del file, controlla che main.js e datiIniziali.js siano davvero dentro src/.

Prime convenzioni di lavoro

Prima di aggiungere funzionalità, il gruppo deve condividere alcune convenzioni:

• nomi di file in minuscolo;
• nomi chiari per funzioni e variabili;
• messaggi utente in italiano;
• dati di esempio piccoli e leggibili;
• niente framework per ora;
• niente database per ora;
• niente localStorage per ora;
• ogni modifica deve lasciare il progetto avviabile;
• se una scelta non è chiara, si annota nel README.

Queste convenzioni non sono burocrazia. Sono il primo modo con cui riduciamo il caos.

Prima lista di regole

Nel README aggiungi una sezione chiamata “Regole da verificare”:

## Regole da verificare

- uno strumento guasto non può essere prestato;
- uno strumento già in prestito non può essere prestato di nuovo;
- un prestito chiuso non può essere chiuso di nuovo;
- uno strumento deve avere nome, categoria e stato;
- gli stati ammessi sono: disponibile, in prestito, guasto, in manutenzione.

Non devi implementare queste regole adesso.

Per ora le scriviamo perché ci servono come bussola. Nelle prossime lezioni torneremo su queste frasi e ci chiederemo:

• dove deve stare questa regola?
• chi deve applicarla?
• come la testiamo?
• quale messaggio deve vedere l’utente?
• che cosa succede se cambiamo il modo di salvare i dati?

Queste domande sono già architettura, anche se il codice è ancora piccolo.

Spiegazione guidata per studiare

Questa lezione va studiata su due piani.

Il primo piano è pratico: creare file, scrivere dati, aprire una pagina, vedere qualcosa nel browser.

Il secondo piano è progettuale: iniziare a distinguere ciò che il progetto fa da come è organizzato. Anche se oggi abbiamo pochi file, stiamo già prendendo decisioni che renderanno più facile o più difficile lavorare domani.

Il punto centrale è questo: un progetto didattico deve essere piccolo, ma non casuale.

Se mettiamo tutto in un unico file fin dall’inizio, all’inizio andiamo veloci. Però perdiamo subito la possibilità di dire “questo file contiene dati”, “questo file avvia la pagina”, “questo documento spiega il progetto”. In architettura, dare un posto alle cose è già una forma di ragionamento.

Il README, in particolare, non è un riassunto decorativo. È il primo contratto con chi leggerà il progetto. Dice che cosa stiamo costruendo, come si apre e quali funzionalità vogliamo raggiungere. Se il README è falso, vago o assente, il progetto diventa più difficile da riprendere dopo una settimana.

Esempio di ragionamento

Prendiamo questa riga dei dati iniziali:

stato: "guasto"

Oggi è solo una stringa dentro un oggetto. Più avanti diventerà una regola:

uno strumento guasto non può essere prestato

Questa trasformazione è importante. All’inizio vediamo solo un dato. Poi capiamo che quel dato ha conseguenze sul comportamento del programma. Quando un’informazione ha conseguenze, probabilmente appartiene al dominio del problema.

Per ora non serve creare classi, tipi complessi o pattern. Serve osservare bene il materiale che abbiamo davanti.

Errori frequenti

Evita questi errori:

• creare file con nomi poco chiari, come script.js, prova.js, nuovo.js;
• scrivere un README copiato da un altro progetto;
• aggiungere subito framework o librerie non necessarie;
• usare dati troppo generici, come Oggetto 1, Oggetto 2;
• introdurre localStorage prima di avere capito come sono fatti i dati;
• implementare già tutte le regole senza averle discusse;
• ignorare gli errori in console.

Il criterio è semplice: dopo la lezione, un compagno deve poter aprire la cartella e capire da dove partire.

Micro-sfida

Scegli tre strumenti reali presenti nel tuo laboratorio o nella tua aula e aggiungili ai dati iniziali.

Vincoli:

• ogni strumento deve avere id, nome, categoria, stato;
• usa solo stati coerenti con il progetto;
• non aggiungere più di 6 strumenti totali;
• non introdurre ancora localStorage;
• non aggiungere ancora form o pulsanti.

Risultato atteso: la pagina mostra una lista realistica di strumenti del tuo contesto.

Prodotto da consegnare

Qui “consegnare” significa mostrare al docente o al gruppo un risultato verificabile.

Alla fine della lezione devi poter mostrare:

• la cartella registro-laboratorio;
• il file README.md;
• il file index.html;
• i file src/main.js e src/datiIniziali.js;
• la pagina aperta nel browser;
• la lista degli strumenti visibile;
• la sezione “Regole da verificare” nel README.

Non basta dire “l’ho fatto”. Devi poter aprire il progetto e far vedere che funziona.

Domande di comprensione

Rispondi per iscritto, anche in modo breve:

• Perché non introduciamo subito localStorage?
• Perché i dati iniziali stanno in un file separato?
• Quale informazione degli strumenti potrebbe diventare una regola?
• Che cosa deve spiegare il README a una persona esterna?
• Quale errore in console bloccherebbe il progetto?

Le risposte devono usare parole concrete del progetto: strumento, stato, pagina, file, README, regola.

Controllo finale

La lezione è completata quando puoi dire sì a queste domande:

• il progetto si apre nel browser;
• la console non mostra errori bloccanti;
• il README spiega che cosa stai costruendo;
• esiste una lista di strumenti iniziali;
• la pagina mostra almeno 3 strumenti;
• ogni strumento ha id, nome, categoria, stato;
• hai scritto le prime regole da verificare;
• non hai ancora introdotto framework, database, API o localStorage.

Nel prossimo passo costruiremo apposta una versione fragile del Registro. Farà poche cose, ma con responsabilità mescolate: servirà a capire perché l’architettura diventa necessaria.