Scrivere requisiti verificabili senza burocratese

In questa fase del percorso abbiamo già nominato utenti, azioni, regole e parole del dominio. Ora dobbiamo fare un passaggio decisivo: trasformare quelle osservazioni in requisiti che aiutano davvero a costruire il software.

Un requisito non è una frase elegante. Non serve a sembrare professionali, non serve a riempire una relazione e non deve trasformare il progetto in un documento amministrativo. Un requisito utile deve aiutare tre persone:

• chi sviluppa, perché capisce che cosa deve costruire;
• chi testa, perché capisce che cosa deve verificare;
• chi valuta, perché capisce se il comportamento richiesto esiste davvero.

La frase seguente sembra seria, ma non aiuta quasi per niente:

Il sistema deve gestire in modo efficiente e intuitivo il laboratorio.

Il problema è che contiene parole larghe: “gestire”, “efficiente”, “intuitivo”. Non dice quale utente compie quale azione, su quale dato, con quale risultato visibile. Se la usiamo come guida, due gruppi di studenti potrebbero costruire due programmi molto diversi e dire entrambi di aver rispettato il requisito.

Una frase migliore è questa:

Il docente può cercare strumenti per nome, categoria o stato.

Qui sappiamo chi agisce, che cosa fa, su quale parte del sistema lavora e come potremo verificare il comportamento. Non è ancora tutto il progetto, ma è un pezzo chiaro.

Obiettivo della lezione

Alla fine della lezione devi produrre una prima lista di requisiti del Registro del laboratorio scolastico. La lista deve essere breve, ordinata e verificabile.

Non stiamo ancora progettando tutte le classi o tutti i file. Stiamo preparando il terreno per il dominio e per i casi d’uso. Se i requisiti sono scritti male, il codice tenderà a diventare confuso: una parte finirà nella UI, una parte nel salvataggio dati, una parte in funzioni senza confine.

Il risultato atteso è un file di appunti, per esempio docs/requisiti.md, diviso in quattro sezioni:

• requisiti funzionali;
• regole di dominio;
• vincoli pratici;
• requisiti rimandati.

Ogni frase deve poter essere controllata con un esempio, una prova manuale o un test.

Prima distinzione: comportamento, regola, vincolo

Nel Registro del laboratorio incontreremo frasi di tipo diverso. Mescolarle è uno dei modi più rapidi per rendere il progetto difficile da leggere.

Un requisito funzionale descrive un comportamento offerto dal sistema:

Il docente può registrare un nuovo strumento indicando nome, categoria e stato iniziale.

Una regola di dominio descrive una condizione che deve valere nel laboratorio, indipendentemente dalla schermata usata:

Uno strumento guasto non può essere prestato.

Un vincolo pratico descrive un limite o una scelta del progetto:

Nella versione completa i dati devono restare disponibili dopo il refresh della pagina usando localStorage.

Un requisito rimandato descrive qualcosa che potrebbe servire in futuro, ma che non entra nel percorso corrente:

Il sistema potrà avere login e permessi completi per docente, tecnico e studente.

Questa distinzione non è burocrazia. Serve a decidere dove andrà il codice.

• Un comportamento diventerà spesso un caso d’uso.
• Una regola importante andrà nel dominio.
• Un vincolo di salvataggio riguarderà l’infrastruttura.
• Un requisito rimandato non deve complicare il codice di oggi.

La formula base per i requisiti funzionali

Per scrivere un requisito funzionale usa questa forma:

[Ruolo] può [azione] [oggetto] [condizione o dettaglio].

Esempi:

Il docente può registrare uno strumento indicando nome, categoria e stato iniziale.
Il docente può cercare strumenti per nome, categoria o stato.
Il docente può registrare un prestito per uno strumento disponibile.
Il docente può chiudere un prestito aperto.
Il tecnico può aprire una segnalazione di guasto per uno strumento esistente.

Questa formula obbliga a fare chiarezza. Se non riesci a indicare il ruolo, forse non hai capito chi userà quella funzione. Se non riesci a indicare l’azione, forse stai scrivendo una frase troppo vaga. Se non riesci a indicare l’oggetto, forse stai confondendo più comportamenti in una sola frase.

Confronta queste due versioni:

Il sistema gestisce i prestiti.

Il docente può registrare un prestito per uno strumento disponibile indicando studente e data di inizio.
Il docente può chiudere un prestito aperto indicando la data di restituzione.
Il docente può vedere l'elenco dei prestiti ancora aperti.

La prima frase nasconde molte decisioni. Le altre tre fanno emergere azioni diverse. Probabilmente diventeranno tre pezzi di lavoro distinti.

Scrivere regole di dominio

Per le regole di dominio usa una forma più vicina a questa:

[Oggetto] deve/non deve [comportamento] [condizione].

Esempi:

Uno strumento guasto non può essere prestato.
Uno strumento in manutenzione 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 un nome non vuoto.

Una regola di dominio non nasce dalla pagina web. Nasce dal problema reale. Se domani togliessimo la pagina web e usassimo una CLI, la regola resterebbe vera. Se domani sostituissimo localStorage con un database, la regola resterebbe vera.

Questo è un criterio molto utile:

Se la frase rimane vera cambiando interfaccia o sistema di salvataggio, probabilmente appartiene al dominio.

Per esempio:

Uno strumento guasto non può essere prestato.

Non dipende da HTML, pulsanti, form, localStorage o JSON. Deve valere sempre. Per questo non deve essere controllata solo disabilitando un pulsante nella UI. La UI può aiutare, ma la regola deve essere protetta nel codice del dominio o nel caso d’uso che coordina l’operazione.

Requisiti verificabili

Un requisito è verificabile quando puoi immaginare una prova concreta.

Requisito:

Il docente può cercare strumenti per stato.

Prova:

Dati tre strumenti con stati diversi, quando cerco lo stato "disponibile", vedo solo gli strumenti disponibili.

Requisito:

Uno strumento guasto non può essere prestato.

Prova:

Dato uno strumento guasto, quando provo a registrare un prestito, il sistema rifiuta l'operazione.

Requisito:

Gli strumenti restano salvati dopo il refresh della pagina.

Prova:

Dato uno strumento registrato, quando aggiorno la pagina e riapro il registro, lo strumento è ancora presente.

Se non riesci a immaginare una prova, il requisito è probabilmente troppo vago. Non significa che sia inutile, ma va riscritto.

Parole da evitare o da precisare

Alcune parole compaiono spesso nei requisiti, ma da sole non bastano:

• semplice;
• intuitivo;
• efficiente;
• completo;
• sicuro;
• moderno;
• flessibile;
• gestire;
• migliorare;
• ottimizzare.

Non sono parole vietate. Il problema è usarle senza dire come si riconosce il risultato.

Frase vaga:

Il registro deve essere semplice da usare.

Versione più utile:

La registrazione di un prestito richiede solo strumento, studente e data di inizio.

Frase vaga:

Il sistema deve gestire i guasti.

Versione più utile:

Il tecnico può aprire una segnalazione di guasto indicando strumento, descrizione e data.
Quando viene aperta una segnalazione di guasto, lo strumento passa allo stato "guasto".

Frase vaga:

I dati devono essere salvati bene.

Versione più utile:

Gli strumenti registrati restano disponibili dopo il refresh della pagina usando localStorage.

Frase vaga:

Il sistema deve essere sicuro.

Versione più utile per questo corso:

Il sistema non deve mostrare all'utente dettagli tecnici degli errori, come stack trace o messaggi interni del browser.

Nel percorso esteso parleremo meglio di sicurezza. Per ora ci basta evitare frasi enormi che sembrano dire tutto e non guidano nessuna scelta.

Requisiti e livelli architetturali

I requisiti non sono separati dall’architettura. Sono uno degli strumenti che ci aiutano a vedere i confini.

Guarda questi esempi:

Il docente può cercare strumenti per nome, categoria o stato.

Questo comportamento attraversa più livelli:

• la Presentation raccoglie il testo o il filtro scelto dall’utente;
• l’Application coordina la ricerca;
• il Domain definisce che cos’è uno strumento e quali stati sono validi;
• l’Infrastructure fornisce gli strumenti salvati.

Altro esempio:

Uno strumento guasto non può essere prestato.

Qui il centro è il Domain. La UI può mostrare un messaggio e il caso d’uso può coordinare l’operazione, ma la regola non deve dipendere dal pulsante “Presta”.

Altro esempio:

Gli strumenti restano salvati dopo il refresh della pagina.

Qui il centro è l’Infrastructure. Il dominio non deve sapere che esiste localStorage. Per il dominio uno strumento è uno strumento, non una stringa JSON.

Scrivere bene i requisiti ci evita di mettere tutto nello stesso file solo perché “funziona”.

Criteri di accettazione semplici

Per i requisiti più importanti aggiungi criteri di accettazione. Non serve un formato complicato: basta scrivere quando il requisito può essere considerato soddisfatto.

Esempio:

### Requisito

Il docente può registrare un prestito per uno strumento disponibile.

### Criteri di accettazione

- dato uno strumento disponibile, il prestito viene creato;
- dopo la creazione del prestito, lo strumento risulta in prestito;
- dato uno strumento guasto, il prestito viene rifiutato;
- dato uno strumento inesistente, viene mostrato un messaggio comprensibile.

Questi criteri preparano i test. Non sono ancora codice, ma dicono che cosa dovrà essere vero.

Un altro esempio:

### Requisito

Il docente può cercare strumenti per nome, categoria o stato.

### Criteri di accettazione

- cercando una parte del nome, vengono mostrati gli strumenti corrispondenti;
- filtrando per categoria, vengono esclusi gli strumenti di categorie diverse;
- filtrando per stato, vengono mostrati solo gli strumenti con quello stato;
- se non ci sono risultati, la UI mostra un messaggio chiaro.

Nota una cosa importante: l’ultimo criterio parla di UI, mentre i primi tre parlano del comportamento della ricerca. Questo ci ricorda che non tutti i dettagli finiranno nello stesso punto del codice.

Bozza iniziale per il Registro

Puoi usare questa bozza come punto di partenza. Non va copiata senza pensarci: va discussa, adattata e collegata al progetto reale della classe.

# Requisiti del Registro del laboratorio

## Requisiti funzionali

- Il docente può registrare uno strumento indicando nome, categoria e stato iniziale.
- Il docente può modificare nome, categoria o stato di uno strumento esistente.
- Il docente può cercare strumenti per nome, categoria o stato.
- Il docente può registrare un prestito per uno strumento disponibile.
- Il docente può chiudere un prestito aperto.
- Il docente può vedere l'elenco dei prestiti aperti.
- Il tecnico può aprire una segnalazione di guasto per uno strumento esistente.
- Il tecnico può segnare uno strumento guasto come in manutenzione.
- Il tecnico può segnare uno strumento in manutenzione come disponibile.

## Regole di dominio

- Uno strumento deve avere un nome non vuoto.
- Uno strumento deve avere uno stato valido.
- Uno strumento guasto non può essere prestato.
- Uno strumento in manutenzione non può essere prestato.
- Uno strumento già in prestito non può essere prestato di nuovo.
- Un prestito deve riferirsi a uno strumento esistente.
- Un prestito chiuso non può essere chiuso di nuovo.

## Vincoli pratici

- Il progetto deve funzionare nel browser senza framework complessi.
- Nella prima versione i dati possono essere salvati in memoria.
- Nella versione completa i dati devono essere salvati in localStorage o JSON.
- I messaggi mostrati all'utente devono essere comprensibili.
- La struttura del progetto deve separare Presentation, Application, Domain e Infrastructure.

## Requisiti rimandati

- Login utenti.
- Permessi completi per ruolo.
- Database remoto obbligatorio.
- Storico dettagliato di tutte le manutenzioni.
- Notifiche automatiche per prestiti scaduti.

Questa bozza contiene già una scelta didattica: non tutto entra subito. Il percorso non deve diventare grande per sembrare importante. Deve crescere in modo controllato.

Attività pratica

Crea o aggiorna il file docs/requisiti.md. Se nel tuo progetto non esiste ancora la cartella docs, puoi crearla ora.

Lavora in tre passaggi.

Passaggio 1: riscrivi le frasi vaghe

Parti da queste frasi:

Il registro deve gestire gli strumenti.
Il sistema deve gestire i prestiti.
Il tecnico deve poter gestire i guasti.
I dati devono essere salvati bene.
L'interfaccia deve essere semplice.

Riscrivile in almeno dieci frasi verificabili. Ogni frase deve contenere una sola idea principale.

Passaggio 2: classifica

Per ogni frase chiediti:

Descrive un comportamento?
Descrive una regola sempre vera?
Descrive un vincolo tecnico o pratico?
Descrive qualcosa da rimandare?

Poi spostala nella sezione corretta.

Passaggio 3: aggiungi criteri di accettazione

Scegli tre requisiti importanti e aggiungi criteri di accettazione. Almeno uno deve riguardare i prestiti e almeno uno deve riguardare la ricerca.

Esempio di struttura:

## Requisito con criteri di accettazione

### Il docente può chiudere un prestito aperto

- dato un prestito aperto, quando lo chiudo, il prestito passa a chiuso;
- quando il prestito viene chiuso, lo strumento torna disponibile;
- dato un prestito già chiuso, il sistema rifiuta una seconda chiusura;
- dato un prestito inesistente, viene mostrato un messaggio comprensibile.

Micro-sfida

Titolo: un requisito, una prova.

Obiettivo: capire se una frase è davvero utile per progettare e testare.

Consegna: scegli cinque requisiti dal tuo file docs/requisiti.md e, sotto ciascuno, scrivi una prova manuale in forma “dato, quando, allora”.

Vincolo: non puoi usare parole come “semplice”, “intuitivo”, “efficiente” o “gestire” senza spiegare che cosa significano nel comportamento del Registro.

Risultato atteso: cinque requisiti verificabili con cinque prove manuali. Se una prova non si riesce a scrivere, il requisito va riscritto.

Errori frequenti

Il primo errore è scrivere requisiti troppo grandi:

Il sistema gestisce tutto il ciclo di vita degli strumenti.

Meglio separare registrazione, cambio stato, prestito, restituzione e guasto.

Il secondo errore è confondere regola e messaggio:

La pagina mostra un errore quando lo strumento è guasto.

Questa frase parla della UI. La regola vera è:

Uno strumento guasto non può essere prestato.

Poi potremo aggiungere:

Quando l'utente prova a prestare uno strumento guasto, la UI mostra il messaggio "Lo strumento è guasto e non può essere prestato".

Il terzo errore è anticipare soluzioni tecniche non necessarie:

Il sistema deve usare un database relazionale con autenticazione completa.

Forse nella versione estesa useremo database o API, ma non serve imporlo nella prima fase. Prima dobbiamo capire regole e casi d’uso.

Controllo finale

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

• ho almeno otto requisiti funzionali;
• ho almeno cinque regole di dominio;
• ho almeno quattro vincoli pratici;
• ho almeno quattro requisiti rimandati;
• ogni requisito contiene una sola idea principale;
• almeno tre requisiti hanno criteri di accettazione;
• posso immaginare una prova per ogni requisito importante;
• ho evitato frasi generiche che non aiutano a costruire il progetto.

Nella prossima lezione useremo richieste volutamente vaghe e le trasformeremo in casi concreti. È un passaggio importante perché allena lo studente a non accettare la prima formulazione del problema: prima si chiarisce, poi si scrive codice.