Presentare il problema e il progetto Registro

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

La struttura dell’apertura

I primi tre minuti di una presentazione tecnica determinano se il pubblico capirà il resto. Una buona apertura risponde a tre domande nell’ordine giusto:

1. Il problema: cosa non funzionava prima del Registro?
2. La soluzione: cosa fa il Registro per risolvere quel problema?
3. L’architettura: perché il Registro è costruito in quel modo?

L’ordine conta. Chi ascolta deve capire il problema prima di poter apprezzare la soluzione.

Parte 1: il problema

Descrivi il problema del laboratorio scolastico in termini concreti, senza codice.

Script per l'apertura della presentazione — Parte 1:

"Il laboratorio scolastico ha decine di strumenti — trapani, multimetri, saldatori.
 Senza un sistema di registrazione, non si sa chi ha preso cosa, quali strumenti
 sono guasti, quanti prestiti sono aperti.

 Si usava un foglio di carta, ma si perdeva. O un foglio Excel, ma non era sempre
 aggiornato. L'obiettivo era costruire qualcosa di digitale che potesse funzionare
 sul browser dell'aula, senza server, senza account."

Cosa include un problema ben descritto:

• chi è colpito (tecnico, docente, studente)
• cosa succede senza il sistema (disordine, perdita di informazioni)
• i vincoli pratici (solo browser, nessun server, laboratorio scolastico)

Parte 2: la soluzione — cosa fa il Registro

Descrivi le funzioni principali con esempi concreti, non elenchi astratti.

Script — Parte 2:

"Il Registro del laboratorio permette di:
 - registrare ogni strumento con nome, categoria e stato iniziale;
 - aprire un prestito quando uno studente prende uno strumento;
 - chiudere il prestito quando lo restituisce;
 - segnalare uno strumento guasto, che rimane bloccato finché non viene riparato;
 - cercare strumenti per nome, categoria o stato.

 I dati vengono salvati nel browser con localStorage — nessun server necessario."

Dopo questa descrizione, mostra la UI funzionante per 60 secondi: registra uno strumento, aprì un prestito, chiudi il prestito. Non descrivere — mostra.

Parte 3: l’architettura — perché è costruito così

Questa è la parte più tecnica. Presenta l’architettura come la risposta a un problema concreto di manutenibilità.

Script — Parte 3:

"Il progetto è diviso in quattro livelli: dominio, applicazione, infrastruttura e presentazione.

 Il dominio contiene le regole del laboratorio — per esempio, uno strumento guasto
 non può essere prestato. Questa regola sta in una funzione che non conosce localStorage,
 non conosce la UI, non conosce fetch. Si può testare con un oggetto in memoria.

 I casi d'uso coordinano le operazioni — registraPrestito, chiudiPrestito, cercaStrumenti.
 Ricevono l'archivio come dipendenza, quindi si possono testare senza browser.

 L'infrastruttura salva e legge i dati. Oggi usa localStorage. Se domani usassimo
 un database, cambieremmo solo questo livello — il dominio e i casi d'uso restano intatti.

 La UI legge l'input, chiama i casi d'uso e mostra i risultati. Non decide le regole."

Come dimostrare l’architettura durante la presentazione

Non basta dirlo — mostralo nel codice. Prepara questi tre punti:

Punto 1 — il dominio non importa nulla di esterno:

Apri domain/strumento.js.
Mostra che non c'è nessun import da localStorage o da altri moduli.
"Questo è il dominio. Non conosce localStorage. Non conosce la UI."

Punto 2 — il caso d’uso riceve l’archivio come parametro:

Apri application/registraPrestito.js.
Mostra creaRegistraPrestito({ archivioStrumenti, archivioPrestiti }).
"Questo è il caso d'uso. Riceve l'archivio come dipendenza.
 Nei test usiamo un archivio in memoria — non serve avviare il browser."

Punto 3 — un test che funziona senza browser:

Apri il file di test.
Mostra il test su puoEsserePrestato o su registraPrestito con archivio in memoria.
"Questo test verifica che uno strumento guasto non possa essere prestato.
 Gira senza browser, senza localStorage, in meno di un secondo."

Prepara le risposte alle domande frequenti

Durante la presentazione, queste domande sono comuni:

Domanda	Risposta preparata
”Perché non hai usato React/Vue?"	"Per questo progetto bastava JavaScript modulare. Framework grandi aggiungono complessità senza beneficio per questa scala."
"Come gestisci i dati se si chiude il browser?"	"Con localStorage i dati persistono tra sessioni. Si perdono se si cancella la cache del browser — è un limite accettabile per un laboratorio scolastico."
"Cosa cambieresti in una versione reale?"	"Aggiungerei autenticazione e un database reale con transazioni — per garantire la coerenza dei dati tra strumenti e prestiti.”

Procedura guidata

1. Scrivi lo script dell’apertura in tre parti (problema, soluzione, architettura) — 5-7 minuti totali.
2. Prepara i tre punti dimostrativi nel codice (dominio senza import, caso d’uso con dipendenza, test senza browser).
3. Prova la presentazione a voce — cronometra le tre parti.
4. Chiedi feedback su: “hai capito subito il problema?” e “hai capito perché l’architettura è utile?”.

Attività in classe

## Preparazione presentazione — apertura

Bozza Parte 1 (il problema):

Bozza Parte 2 (cosa fa il Registro):

Bozza Parte 3 (perché questa architettura):

Punto dimostrativo 1 — dominio senza import: [file:riga]
Punto dimostrativo 2 — caso d'uso con dipendenza: [file:riga]
Punto dimostrativo 3 — test senza browser: [file:riga]

Tempo totale dell'apertura: [X minuti]
Feedback ricevuto: 

Spiegazione guidata per studiare

Presentare l’architettura a un pubblico tecnico (altri studenti, docenti) richiede un equilibrio: abbastanza concretezza da essere credibili, abbastanza sintesi da non perdere chi ascolta.

Il punto centrale è: ogni affermazione sull’architettura deve avere una prova nel codice. “Il dominio è separato dall’infrastruttura” è un’affermazione. La prova è: apri domain/strumento.js e mostra che non c’è nessun import esterno.

Il rischio tipico è descrivere l’architettura come si vorrebbe che fosse, non come è. Prima della presentazione, verifica che le tre prove dimostrative siano nel codice e funzionino.

Passo per passo nel progetto

1. Scrivi lo script dell’apertura (problema, soluzione, architettura).
2. Verifica i tre punti dimostrativi nel codice — sono ancora validi? Il dominio è davvero pulito?
3. Prova la presentazione da solo, cronometrando.
4. Prova con un compagno — chiedi se il problema era chiaro prima della soluzione.
5. Aggiusta l’ordine o le parole in base al feedback.

Esempio da leggere lentamente

Apertura efficace — 4 minuti:

[1 minuto] Il problema:
"Nel laboratorio, chi ha preso il trapano? È guasto o funziona?
 Senza un registro, non si sa. Usavamo carta e penna, ma si perdeva."

[1 minuto] La soluzione:
"Abbiamo costruito un Registro digitale che gira nel browser.
 [demo live: registra uno strumento, apri un prestito, chiudi il prestito]"

[2 minuti] L'architettura:
"Il progetto è diviso in quattro livelli. Il dominio contiene le regole
 — [apri domain/strumento.js] — vedi che non importa nulla.
 I casi d'uso ricevono l'archivio come dipendenza — [apri registraPrestito.js].
 I test funzionano senza browser — [mostra il test con archivio in memoria]."

Prova di comprensione

• Riesci a descrivere il problema in 60 secondi senza menzionare codice?
• I tre punti dimostrativi sono nel codice e funzionano?
• Se qualcuno chiede “cosa cambieresti?”, hai una risposta pronta?

Errori da evitare

• iniziare dalla soluzione senza spiegare il problema — il pubblico non capisce il valore;
• descrivere l’architettura senza aprire il codice — le affermazioni non sono verificabili;
• superare i 7 minuti di apertura — il pubblico si perde nei dettagli prima di vedere la demo;
• non provare la presentazione almeno una volta prima del giorno della valutazione.

Prodotto da consegnare

Può essere:

• lo script scritto delle tre parti dell’apertura;
• i tre punti dimostrativi identificati con file e riga;
• una registrazione audio/video della prova da 5 minuti.

Checklist di chiusura

• Il problema è descritto in 60 secondi senza codice
• La soluzione include una demo live di 60 secondi
• L’architettura è dimostrata con tre punti nel codice
• Ho preparato risposte per le domande frequenti
• Ho provato l’apertura con un compagno e ricevuto feedback

Domande per la revisione

• Il compagno ha capito il problema prima di vedere il codice?
• I tre punti dimostrativi erano nel codice o li hai dovuti sistemare?
• Quanto tempo è durata l’apertura? Era dentro i 7 minuti?

Risultato atteso

Alla fine lo studente deve saper dire:

Il problema che il mio Registro risolve è: [frase].
Le funzioni principali sono: [lista breve].
L'architettura ha quattro livelli perché: [motivazione].
Lo dimostro aprendo: [file 1], [file 2], [file 3].

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