Checkpoint 20 ore: revisione della versione essenziale

Questo checkpoint chiude la prima parte del percorso.

Non e la fine del corso.

E il primo punto in cui il progetto deve avere una forma riconoscibile.

Lo studente deve poter dire:

Il registro funziona in modo essenziale e il codice ha i primi confini chiari.

Obiettivo

Verificare che la versione essenziale sia pronta.

La versione essenziale non deve essere perfetta.

Deve pero mostrare:

• progetto avviato;
• dominio minimo;
• casi d’uso principali;
• separazione base dei livelli;
• archivio in memoria;
• alcuni test o scenari sulle regole;
• README iniziale.

Cosa deve essere pronto

Progetto avviato

Deve esistere un progetto apribile e verificabile.

Minimo:

• file HTML o punto di avvio;
• codice JavaScript modulare o TypeScript leggero;
• struttura chiara;
• nessun file unico che contiene tutto.

Dominio minimo

Devono essere presenti almeno:

• Strumento;
• StatoStrumento;
• Prestito;
• regole principali;
• errori di dominio.

Regole minime:

• uno strumento deve avere un nome;
• solo uno strumento disponibile puo essere prestato;
• uno strumento guasto non puo essere prestato;
• uno strumento in manutenzione non puo essere prestato;
• un prestito chiuso non puo essere chiuso di nuovo.

Casi d’uso principali

Devono essere presenti almeno alcuni casi d’uso:

• RegistraStrumento;
• CercaStrumenti;
• RegistraPrestito;
• ChiudiPrestito;
• ApriSegnalazioneGuasto, se gia affrontato nel progetto.

Ogni caso d’uso deve poter essere spiegato con:

input -> operazione -> output

Separazione base dei livelli

Deve esserci una separazione visibile:

domain/
application/
infrastructure/
presentation/

Oppure una struttura equivalente, se il progetto usa nomi leggermente diversi.

La cosa importante e che:

• le regole non stiano nella UI;
• i casi d’uso non siano event listener;
• il salvataggio non sia mescolato al dominio;
• la UI chiami i casi d’uso.

Persistenza in memoria

In questa versione basta un archivio in memoria.

Non e richiesto che i dati restino dopo il refresh.

Deve pero essere chiaro dove si leggono e salvano dati.

Esempio:

archivioStrumentiInMemoria
archivioPrestitiInMemoria

Test minimi o scenari

Devono esserci almeno alcuni test o scenari.

Minimo consigliato:

• strumento senza nome;
• strumento guasto non prestabile;
• strumento in manutenzione non prestabile;
• prestito chiuso non richiudibile;
• registrazione prestito valida.

Se non hai ancora test automatici, devono esserci scenari manuali scritti bene.

README iniziale

Il README deve spiegare:

• obiettivo del progetto;
• funzionalita essenziali;
• struttura delle cartelle;
• livelli architetturali;
• regole principali;
• come avviare o verificare;
• limiti della versione essenziale.

Cosa non e ancora richiesto

Al checkpoint 20 ore non sono richiesti:

• database;
• API;
• login;
• ruoli completi;
• sicurezza avanzata;
• diagrammi dettagliati;
• UML complesso;
• framework pesanti;
• persistenza definitiva;
• test completi di tutta la UI.

Se mancano queste cose, non e un problema.

Non fanno parte della versione essenziale.

Scheda di revisione

Compila:

# Checkpoint 20 ore

## Funzionalita presenti

- [ ] registrare strumenti
- [ ] cercare strumenti
- [ ] registrare prestiti
- [ ] chiudere prestiti
- [ ] segnalare guasti

## Architettura

- [ ] domain separato
- [ ] application separato
- [ ] infrastructure separato
- [ ] presentation separato
- [ ] UI senza regole principali
- [ ] casi d'uso fuori dagli event listener

## Regole

- [ ] strumento senza nome rifiutato
- [ ] strumento guasto non prestabile
- [ ] strumento in manutenzione non prestabile
- [ ] prestito chiuso non richiudibile

## Verifica

- [ ] test automatici minimi
- [ ] oppure scenari manuali scritti
- [ ] README aggiornato
- [ ] limiti dichiarati

Revisione in coppia

Uno studente presenta il progetto a un compagno.

Il compagno deve trovare:

• una cosa chiara;
• una responsabilita ancora confusa;
• una regola forse nel posto sbagliato;
• un test mancante;
• una domanda sul README.

Poi si scambiano i ruoli.

Uso controllato di Codex

Puoi usare questo prompt:

Analizza questa struttura di progetto per il Registro del laboratorio.
Non riscrivere il codice.
Dimmi solo:
- se i confini tra domain, application, infrastructure e presentation sono chiari;
- se vedi regole di dominio nella UI;
- se vedi casi d'uso dentro event listener;
- quali test minimi mancano;
- quale primo refactoring consigli.

La risposta va verificata.

Codex non sostituisce la revisione dello studente.

Cosa consegnare

Alla fine del checkpoint consegna:

• repository o cartella progetto;
• README;
• codice separato nei livelli principali;
• test o scenari;
• breve scheda di revisione;
• elenco dei limiti e dei prossimi passi.

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 checkpoint 20 ore: revisione della versione essenziale, il punto centrale è questo: Refactoring significa cambiare la struttura senza cambiare il comportamento visibile. È un lavoro lento, controllato e protetto da verifiche.

Il rischio tipico è riscrivere tutto perché il codice non piace. Nel laboratorio il refactoring deve insegnare disciplina: piccoli passi, programma funzionante, verifica dopo ogni passo. 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 è breve: non provare a fare tutto, punta a capire il concetto e produrre un risultato piccolo. 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. Scegli un solo problema di struttura.
4. Scrivi o esegui una verifica prima di modificare.
5. Estrai una responsabilità alla volta.
6. Rileggi il diff e controlla che il comportamento sia invariato.
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:

// Prima: una funzione fa tutto.
// Dopo: il flusso diventa leggibile.
const comando = leggiInput();
const esito = eseguiCasoUso(comando);
salvaSeNecessario(esito);
mostraEsito(esito);

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.

Risultato atteso

La versione essenziale e pronta quando:

Il progetto funziona nelle operazioni principali.
Le regole piu importanti sono nel dominio.
I casi d'uso coordinano le operazioni.
La UI chiama i casi d'uso.
I dati sono salvati in memoria.
Il README spiega la struttura.
Esistono test o scenari sulle regole principali.

Prossimo passo

Dopo questo checkpoint il corso continua.

La seconda parte rendera il progetto piu solido:

• interfacce;
• inversione delle dipendenze;
• localStorage o JSON;
• DTO e mapping;
• gestione errori piu chiara;
• test piu strutturati;
• documentazione e diagrammi minimi.

Hai completato la versione essenziale. Ora il progetto non e solo un programma che funziona: ha una prima struttura che puo essere mantenuta.