Vincoli pratici del laboratorio scolastico

Un requisito dice che cosa il sistema deve fare.

Un vincolo dice entro quali limiti deve farlo.

Nel Registro del laboratorio i vincoli sono concreti:

• la lezione dura poco;
• il docente non può perdere tempo con messaggi tecnici;
• il browser può essere chiuso;
• i dati non devono sparire;
• alcuni studenti usano lo stesso computer;
• gli strumenti hanno nomi simili;
• non sempre c’è una connessione stabile;
• il progetto deve restare comprensibile a una classe.

Questi vincoli guidano scelte architetturali. Non sono dettagli secondari.

Obiettivo

Alla fine devi produrre una lista di vincoli pratici del progetto, con una conseguenza tecnica per ciascuno.

Esempio:

Vincolo:
Il docente deve registrare un prestito durante la lezione, senza perdere troppo tempo.

Conseguenza tecnica:
La UI deve chiedere pochi dati obbligatori e mostrare errori chiari.

Requisito e vincolo

Un requisito descrive un comportamento:

Il docente deve poter registrare un prestito.

Un vincolo limita il modo in cui quel comportamento deve essere realizzato:

Il docente deve poterlo fare durante la lezione, in pochi passaggi.

Il requisito ci dice che cosa costruire. Il vincolo ci aiuta a decidere come costruirlo.

Se ignoriamo i vincoli, possiamo creare un sistema formalmente corretto ma inutilizzabile:

• registra prestiti, ma chiede troppi campi;
• salva dati, ma li perde alla chiusura del browser;
• gestisce errori, ma mostra messaggi tecnici;
• ha molte funzioni, ma è troppo complesso per una classe.

Vincoli di tempo

Il registro viene usato mentre succedono altre cose.

Un docente potrebbe dover:

• cercare uno strumento;
• registrare un prestito;
• rispondere a una domanda;
• controllare una classe;
• chiudere il laboratorio.

Quindi il sistema deve evitare passaggi inutili.

Impatto sul progetto:

• input essenziali;
• azioni chiare;
• messaggi brevi;
• ricerca rapida;
• niente schermate complicate nella versione base.

Questo non significa fare una UI povera. Significa non mettere ostacoli tra utente e azione.

Esempio di scelta:

Nella prima versione del prestito chiediamo solo:
- strumento
- studente o gruppo
- eventuale nota

Rimandiamo:

• storico dettagliato delle modifiche;
• firma digitale;
• approvazioni multiple;
• notifiche automatiche.

Queste funzioni possono essere interessanti, ma non servono al primo obiettivo didattico.

Vincoli sui dati

Il Registro del laboratorio gestisce dati piccoli, ma importanti.

Dati principali:

• strumenti;
• stati;
• prestiti;
• segnalazioni;
• persone collegate ai prestiti.

Domande utili:

• quali dati sono obbligatori?
• quali dati sono facoltativi?
• quali dati non dobbiamo salvare?
• quali dati servono solo per mostrare una schermata?
• quali dati devono restare anche dopo la chiusura del browser?

Esempio:

Il nome dello strumento è obbligatorio.
La posizione può essere facoltativa.
Il colore della riga nella UI non va salvato come dato di dominio.

Conseguenze tecniche:

• il dominio deve rifiutare strumenti senza nome;
• i campi facoltativi devono essere gestiti senza errori;
• i dati di presentazione non devono finire nel modello del dominio;
• i dati salvati devono essere abbastanza stabili da poter essere riletti.

Esempio di dato di dominio:

{
  id: "str-1",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile"
}

Esempio di dettaglio UI da non salvare nel dominio:

{
  coloreCard: "verde",
  animazioneApertura: true
}

Vincoli di persistenza

Nelle prime lezioni abbiamo usato dati in memoria.

Poi passeremo a localStorage o JSON.

Più avanti, nella versione estesa, potremo usare database o API.

Il vincolo didattico è questo:

La persistenza deve poter cambiare senza riscrivere dominio e casi d'uso.

Conseguenza:

• le regole non devono dipendere da localStorage;
• i casi d’uso non devono conoscere dettagli inutili del browser;
• l’infrastruttura deve restare sostituibile.

Questo vincolo anticipa il concetto di interfaccia che useremo più avanti.

Esempio di scelta sbagliata:

function puoEsserePrestato(strumentoId) {
  const strumenti = JSON.parse(localStorage.getItem("strumenti"));
  const strumento = strumenti.find((item) => item.id === strumentoId);

  return strumento.stato === "disponibile";
}

La regola dipende dal browser e dal formato di salvataggio.

Direzione migliore:

function puoEsserePrestato(strumento) {
  return strumento.stato === "disponibile";
}

Poi un altro pezzo del sistema si occuperà di leggere lo strumento.

Vincoli di ambiente

Il corso usa JavaScript modulare o TypeScript leggero nel browser.

Quindi dobbiamo tenere conto di:

• browser diversi;
• file locali;
• localStorage;
• strumenti di sviluppo semplici;
• assenza di backend nella prima parte;
• test eseguibili senza configurazioni pesanti.

Conseguenza:

• niente framework complessi;
• pochi strumenti;
• codice leggibile;
• cartelle esplicite;
• esempi riproducibili.

Il vincolo non è “fare meno”. È fare scelte adatte al laboratorio.

Scelta didattica:

Usiamo JavaScript modulare o TypeScript leggero.
Non introduciamo framework complessi nella prima versione.

Motivo:

• lo studente deve vedere i confini architetturali;
• il progetto deve restare ispezionabile;
• gli errori devono essere comprensibili;
• la configurazione non deve occupare metà del corso.

Vincoli sugli errori

Un errore tecnico non deve arrivare così all’utente:

Cannot read properties of undefined

Nel Registro del laboratorio l’utente deve leggere:

Strumento non trovato.

Oppure:

Questo strumento non può essere prestato perché è guasto.

Conseguenza:

• distingueremo errori tecnici e messaggi utente;
• eviteremo di mostrare dettagli interni;
• mapperemo gli errori in messaggi comprensibili.

Questo diventa un tema architetturale: dove si trasformano gli errori? Non dentro il dominio in modo casuale, non sparsi in ogni bottone.

Esempio:

errore interno:
  STRUMENTO_NON_TROVATO

messaggio utente:
  Strumento non trovato.

Il dominio può segnalare il problema. La Presentation decide come comunicarlo.

Vincoli di privacy e dati personali

Anche in un progetto didattico bisogna abituarsi a fare domande sane.

Per registrare un prestito serve davvero salvare:

• nome e cognome completo?
• email?
• numero di telefono?
• codice fiscale?

Probabilmente no.

Per il laboratorio basta spesso:

• nome o iniziali;
• classe o gruppo;
• eventuale riferimento interno deciso dalla scuola.

Conseguenza tecnica:

• salviamo solo dati necessari;
• evitiamo dati sensibili;
• separiamo esempi didattici e dati reali;
• non usiamo dati personali veri se non serve;
• documentiamo quali dati vengono salvati.

Esempio:

Accettabile nel laboratorio:
Giulia R., 3B

Da evitare se non serve:
email personale, numero di telefono, codice fiscale

Vincoli di manutenzione

Il progetto non finisce quando funziona una volta.

Durante il corso dovrà cambiare:

• aggiungeremo stati;
• aggiungeremo test;
• cambieremo persistenza;
• separeremo livelli;
• miglioreremo errori;
• aggiungeremo documentazione.

Conseguenza:

• non scriviamo tutto in un unico file per sempre;
• diamo nomi chiari;
• facciamo refactoring a piccoli passi;
• proteggiamo le regole con test.

Un progetto didattico deve essere modificabile, non solo dimostrabile.

Conseguenza architetturale:

Le regole importanti devono essere isolate.
La persistenza deve essere sostituibile.
I nomi devono raccontare il problema.
I test devono proteggere i refactoring.

Questo vincolo spiega perché non ci accontentiamo del programma fragile: non basta che funzioni oggi, deve poter cambiare durante il corso.

Vincoli di classe

C’è anche un vincolo didattico: il progetto deve essere spiegabile a studenti principianti o intermedi.

Conseguenze:

• evitare pattern avanzati se non servono;
• introdurre un concetto alla volta;
• usare nomi italiani o comunque coerenti con il dominio;
• mantenere esempi brevi ma realistici;
• documentare le decisioni più importanti.

Questo vincolo è reale quanto localStorage. Se il codice è “professionale” ma nessuno in classe lo capisce, non è adatto al laboratorio.

Scheda vincoli

Compila questa scheda:

# Vincoli del Registro del laboratorio

## Tempo e uso in classe

Vincolo:
Conseguenza tecnica:

## Dati

Vincolo:
Conseguenza tecnica:

## Persistenza

Vincolo:
Conseguenza tecnica:

## Ambiente

Vincolo:
Conseguenza tecnica:

## Errori

Vincolo:
Conseguenza tecnica:

## Privacy

Vincolo:
Conseguenza tecnica:

## Manutenzione

Vincolo:
Conseguenza tecnica:

## Didattica

Vincolo:
Conseguenza tecnica:

Esempio compilato:

## Persistenza

Vincolo:
Nella prima versione usiamo localStorage, ma nella versione estesa potremmo usare API o database.

Conseguenza tecnica:
Le regole del dominio non devono leggere direttamente da localStorage.

## Errori

Vincolo:
Il docente non deve vedere errori tecnici durante una lezione.

Conseguenza tecnica:
Gli errori interni devono essere trasformati in messaggi utente comprensibili.

Esercizio

Per ciascuna frase scrivi la conseguenza tecnica.

1. Il docente deve usare il registro durante la lezione.
2. Il browser può essere chiuso e riaperto.
3. Uno strumento può essere guasto, ma restare nel catalogo.
4. I messaggi tecnici non devono essere mostrati all'utente.
5. In futuro potremmo usare una API al posto di localStorage.

Possibili risposte:

1. La UI deve essere rapida e con pochi campi obbligatori.
2. I dati devono essere salvati in una persistenza, non solo in memoria.
3. Lo stato dello strumento deve essere modellato, non eliminato dalla lista.
4. Gli errori tecnici devono essere convertiti in messaggi comprensibili.
5. I casi d'uso non devono dipendere direttamente da localStorage.

Completa con due frasi tue, prese dal contesto della tua classe o del tuo laboratorio.

Esempio:

6. La classe lavora su computer condivisi.
7. Alcuni strumenti hanno nomi molto simili.

Possibili conseguenze:

6. Non salviamo dati personali non necessari nel browser.
7. La ricerca deve mostrare anche categoria e stato, non solo il nome.

Cosa produrre

Alla fine della lezione devi avere:

• una lista di vincoli pratici;
• una conseguenza tecnica per ogni vincolo;
• almeno un vincolo su dati, tempo, errori, persistenza e manutenzione;
• almeno una scelta che hai deciso di non fare nella versione base.

Esempio di scelta rimandata:

Non introduciamo login e ruoli completi nella prima versione.
Annotiamo il bisogno, ma lo affrontiamo nella parte sulla sicurezza di base.

Domande di comprensione

Rispondi per iscritto:

• Qual è la differenza tra requisito e vincolo?
• Quale vincolo spiega perché non basta salvare tutto in memoria?
• Quale vincolo spiega perché gli errori tecnici non vanno mostrati all’utente?
• Quale scelta rimandi perché sarebbe troppo grande per la versione base?
• Quale vincolo influenza direttamente la separazione tra dominio e infrastruttura?

Controllo finale

La lezione è completata quando puoi rispondere sì:

• ho distinto requisiti e vincoli;
• ho collegato ogni vincolo a una scelta tecnica;
• ho evitato soluzioni troppo grandi per il laboratorio;
• ho scritto cosa viene rimandato;
• ho capito che i vincoli influenzano l’architettura.

Nella prossima lezione costruiremo il glossario del dominio.