Obiettivo del percorso e progetto guida

Questo percorso non serve a imparare una formula da copiare. Serve a costruire un modo di ragionare sul codice quando un programma cresce.

Un programma piccolo può funzionare anche se è disordinato. Una pagina con qualche bottone, un array di dati e due funzioni può sembrare sufficiente. Il problema arriva quando bisogna aggiungere una nuova regola, cambiare il modo di salvare i dati, correggere un errore o spiegare il progetto a un compagno.

In quel momento il codice che “funziona” può diventare fragile.

Il corso parte proprio da questa situazione reale: il codice fa qualcosa, ma ogni modifica rischia di rompere altro.

Obiettivo della lezione

Alla fine di questa lezione devi saper spiegare:

• che cosa costruiremo durante il corso;
• perché il progetto guida è un Registro del laboratorio scolastico;
• quali problemi architetturali emergeranno;
• come leggere il percorso come una sequenza unica;
• che cosa significano, in modo iniziale, Presentation, Application, Domain e Infrastructure;
• perché non useremo subito framework o soluzioni complesse.

Non devi ancora saper progettare tutta l’applicazione. Devi però capire la direzione del lavoro.

Che cosa imparerai davvero

La domanda centrale del corso non è:

Quale architettura devo copiare?

La domanda centrale è:

Dove metto questo pezzo di codice, e perché?

Durante il percorso torneremo spesso su domande pratiche:

• dove metto una regola importante?
• quando una funzione sta facendo troppe cose?
• come separo interfaccia, regole e salvataggio?
• come scrivo un caso d’uso che non dipende dal browser?
• come cambio archivio dati senza riscrivere tutto?
• come testo una regola senza aprire la pagina web?
• come trasformo un errore tecnico in un messaggio comprensibile?
• come spiego una scelta tecnica in modo chiaro?

Queste domande sono più importanti dei nomi dei pattern. Useremo parole come dominio, caso d’uso, adapter e DTO, ma solo quando serviranno a risolvere un problema concreto.

Il progetto guida

Il progetto del corso è un Registro del laboratorio scolastico.

Il Registro serve a gestire strumenti e dispositivi presenti in un laboratorio:

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

È un buon progetto guida perché è abbastanza piccolo da essere affrontabile in classe, ma abbastanza ricco da far emergere problemi veri.

In questo progetto ci sono:

• dati da registrare;
• dati da cercare;
• stati da modellare;
• regole da rispettare;
• prestiti da aprire e chiudere;
• errori da spiegare all’utente;
• dati da salvare;
• test da scrivere;
• scelte tecniche da documentare.

Non è un esempio astratto. È una situazione che uno studente o un docente può riconoscere.

Le funzionalità che cresceranno nel tempo

All’inizio il Registro farà pochissimo. Poi verrà esteso passo dopo passo.

Le funzionalità principali saranno:

• registrare uno strumento;
• cercare strumenti per nome, categoria o stato;
• cambiare lo stato di uno strumento;
• registrare un prestito;
• chiudere un prestito;
• aprire una segnalazione di guasto;
• salvare i dati prima in memoria, poi in localStorage o JSON;
• eventualmente collegare una variante database o API;
• mostrare messaggi comprensibili;
• testare le regole principali.

Non costruiremo tutto subito. Questa è una scelta didattica importante.

Se si parte già da una struttura perfetta, non si capisce perché serve. Prima faremo nascere il problema. Poi introdurremo l’architettura come risposta.

Il percorso è unico

Il corso non è una raccolta di lezioni sparse e non è diviso in corsi separati.

È un unico percorso progressivo:

si parte da un registro semplice
si incontra il disordine
si separano le responsabilità
si introducono regole e casi d'uso
si cambia la persistenza
si aggiungono test, errori e documentazione
si arriva alla revisione e alla presentazione finale

I checkpoint non sono corsi diversi. Sono momenti in cui ci fermiamo a verificare che il progetto sia arrivato a un certo livello.

Un checkpoint risponde a domande come:

• il progetto parte?
• le regole principali sono nel posto giusto?
• i casi d’uso sono separati dalla UI?
• il salvataggio è sostituibile?
• ci sono test sulle regole importanti?
• lo studente sa spiegare le scelte fatte?

Quindi non devi leggere il percorso come “tre blocchi separati”. Devi leggerlo come una strada unica con tappe di controllo.

La mappa mentale del corso

Useremo quattro livelli:

Presentation / UI
  mostra dati, riceve input, chiama i casi d'uso

Application
  coordina le operazioni del sistema

Domain
  contiene regole, concetti e invarianti

Infrastructure
  salva dati, legge file, usa localStorage, database, API o strumenti esterni

All’inizio questi nomi possono sembrare astratti. Li useremo in modo molto pratico.

Esempio:

uno strumento guasto non può essere prestato

Questa è una regola del laboratorio. Non deve stare dentro il click di un bottone. Deve stare nel dominio, perché deve valere sempre:

• quando l’utente usa la pagina web;
• quando un test verifica il comportamento;
• quando in futuro useremo un’altra interfaccia;
• quando cambieremo il modo di salvare i dati.

Altro esempio:

salva la lista degli strumenti in localStorage

Questo non è dominio. È infrastruttura. È un dettaglio tecnico di salvataggio. Se domani passiamo da localStorage a un file JSON o a un’API, non dovremmo riscrivere le regole del laboratorio.

Che cosa significa codice mantenibile

In questo corso un codice è mantenibile quando:

• una regola importante si trova facilmente;
• una funzione ha una responsabilità chiara;
• una modifica non costringe a riscrivere mezza applicazione;
• un errore viene spiegato all’utente in modo comprensibile;
• il salvataggio dei dati può cambiare senza cambiare le regole;
• il progetto può essere capito da una persona che non lo ha scritto;
• i test proteggono almeno i comportamenti principali.

Codice mantenibile non significa:

• scrivere tanto codice;
• usare parole difficili;
• creare molte cartelle inutili;
• applicare pattern perché sembrano professionali;
• trasformare un progetto scolastico in un sistema enorme.

Significa organizzare il codice in modo che il prossimo cambiamento sia meno pericoloso.

Cosa non faremo subito

Per ora eviteremo:

• framework frontend complessi;
• backend completo;
• database obbligatorio;
• autenticazione avanzata;
• diagrammi UML pesanti;
• pattern introdotti prima di avere un problema reale.

Questi argomenti possono essere interessanti, ma qui l’obiettivo è un altro: capire bene i confini interni di una piccola applicazione.

Attività guidata

Apri il README creato nella lezione precedente e aggiungi una sezione:

## Obiettivo del progetto

Dentro la sezione rispondi in 5-8 righe:

• che problema risolve il Registro del laboratorio;
• chi potrebbe usarlo;
• quali strumenti gestisce;
• quali operazioni saranno importanti;
• perché il progetto può diventare fragile se tutto resta nello stesso file.

Esempio:

## Obiettivo del progetto

Il Registro del laboratorio scolastico serve a tenere traccia degli strumenti
disponibili, in prestito, guasti o in manutenzione. Il progetto sarà usato da
docenti e tecnici di laboratorio per cercare strumenti, registrare prestiti e
segnalare problemi. Useremo questo progetto per imparare a separare interfaccia,
regole, casi d'uso e salvataggio dati, evitando che tutta la logica finisca
nella pagina web.

Questo testo non deve essere perfetto. Deve essere chiaro e vero.

Spiegazione guidata per studiare

Questa lezione va studiata come una mappa.

Non stai ancora imparando a scrivere un caso d’uso completo o un adapter. Stai imparando a riconoscere il tipo di problemi che incontrerai.

Il punto più importante è questo: l’architettura non arriva prima del problema. Arriva quando il progetto inizia ad avere responsabilità diverse.

Nel Registro del laboratorio queste responsabilità compaiono subito:

• l’utente vuole vedere e inserire dati;
• il sistema deve rispettare regole;
• i dati devono essere salvati;
• gli errori devono essere spiegati;
• il progetto deve poter essere modificato.

Se tutte queste cose finiscono nello stesso file, il progetto può ancora funzionare. Però diventa difficile da leggere, da testare e da cambiare.

Esempio di ragionamento

Immagina questa richiesta:

Quando uno strumento è guasto, non deve comparire tra quelli prestabili.

Potresti risolverla velocemente filtrando gli strumenti direttamente nella pagina:

const prestabili = strumenti.filter((strumento) => strumento.stato !== "guasto");

Questa soluzione può andare bene come primo esperimento. Però apre una domanda:

La regola "guasto non prestabile" appartiene davvero alla pagina?

La risposta è no. La pagina può scegliere come mostrare gli strumenti, ma la regola deve valere anche se:

• domani cambia l’interfaccia;
• scriviamo un test;
• aggiungiamo una CLI;
• salviamo i dati in un altro modo.

Quindi questa richiesta ci prepara a una distinzione importante:

• la UI mostra e raccoglie input;
• il dominio custodisce le regole;
• il caso d’uso coordina l’operazione;
• l’infrastruttura salva e legge dati.

Micro-sfida

Prendi un oggetto reale presente nel tuo laboratorio e descrivilo come se dovesse entrare nel Registro.

Esempio:

Nome: Kit Arduino Base
Categoria: elettronica
Stato: disponibile
Uso tipico: prestito a gruppi di studenti durante esercitazioni
Problema possibile: componenti mancanti o danneggiati

Poi scrivi una regola che riguarda quell’oggetto.

Esempio:

Un kit Arduino con componenti mancanti non può essere prestato a un nuovo gruppo.

Infine indica dove pensi che questa regola dovrebbe stare:

UI, Application, Domain o Infrastructure?

Non è grave se la risposta non è perfetta. L’importante è iniziare a ragionare sul posto delle responsabilità.

Prodotto da consegnare

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

Alla fine della lezione devi mostrare:

• la sezione Obiettivo del progetto nel README;
• la descrizione di almeno uno strumento reale;
• una regola collegata a quello strumento;
• una breve ipotesi su dove dovrebbe stare quella regola;
• una frase che spieghi perché il percorso è unico e progressivo.

Domande di comprensione

Rispondi per iscritto:

• Perché il Registro del laboratorio è un buon progetto per studiare architettura?
• Perché non costruiamo subito tutto il progetto finale?
• Che differenza c’è tra una regola del laboratorio e un dettaglio di salvataggio?
• Perché i checkpoint non sono corsi separati?
• Che cosa rende un programma fragile anche se funziona?

Le risposte devono usare esempi del Registro, non definizioni imparate a memoria.

Controllo finale

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

• so spiegare qual è il progetto guida;
• so dire perché il Registro è adatto a studiare architettura;
• ho scritto l’obiettivo del progetto nel README;
• ho individuato almeno una regola reale del laboratorio;
• ho capito che il corso è un percorso unico, non una raccolta di pagine sparse;
• so distinguere, almeno a parole, UI, casi d’uso, dominio e infrastruttura.

Nel prossimo passo sceglieremo lo stack tecnico. La scelta sarà volutamente semplice: useremo strumenti piccoli per vedere meglio le responsabilità del codice.