Esercizio: trasformare richieste vaghe in casi concreti

Questa lezione chiude il modulo su requisiti, utenti e linguaggio del problema. Finora abbiamo raccolto parole, ruoli, azioni, vincoli e requisiti. Adesso facciamo il lavoro che spesso manca nei progetti degli studenti: prendere una richiesta confusa e trasformarla in materiale utilizzabile.

Non scriviamo ancora il dominio completo. Non creiamo classi, repository o interfacce. Prepariamo una base abbastanza chiara da poter dire, nella prossima lezione: “queste sono le regole che devono entrare nel dominio”.

Il punto non è indovinare tutto al primo colpo. Il punto è imparare a non partire subito dal codice quando il problema è ancora sfocato.

Obiettivo della lezione

Dato un testo iniziale vago, devi produrre una scheda di analisi del problema. La scheda deve contenere:

• utenti coinvolti;
• azioni principali;
• regole esplicite;
• regole implicite;
• regole da chiarire;
• vincoli pratici;
• requisiti verificabili;
• parole da inserire nel glossario.

Alla fine, una persona esterna deve poter leggere la scheda e capire che cosa il Registro del laboratorio deve fare nella prima versione.

Scenario di partenza

Usa questo scenario. È volutamente scritto come arriverebbe spesso da una conversazione informale:

Nel laboratorio ci sono molti strumenti e spesso non si sa dove siano.
Quando un docente presta qualcosa a uno studente, vorrebbe segnarlo velocemente.
A volte gli strumenti tornano rotti o incompleti.
Il tecnico vorrebbe sapere cosa deve controllare.
Sarebbe utile cercare gli strumenti e capire quali sono disponibili.
I dati non devono sparire ogni volta che si ricarica la pagina.

Il testo è realistico, ma non è ancora pronto per guidare il codice. Contiene bisogni veri, ma anche parole imprecise:

• “molti strumenti” non dice quanti;
• “non si sa dove siano” può riferirsi allo stato, al prestito o alla posizione fisica;
• “qualcosa” non è un concetto utile nel codice;
• “velocemente” è un vincolo da precisare;
• “rotti o incompleti” possono essere due stati diversi oppure due dettagli di una segnalazione;
• “cosa deve controllare” va trasformato in una lista o una vista concreta;
• “i dati non devono sparire” indica un vincolo di persistenza.

La prima abilità architetturale è fermarsi qui, prima di aprire l’editor.

Output da produrre

Crea o aggiorna il file:

docs/requisiti.md

Se il progetto non ha ancora una cartella docs, puoi crearla. In questa lezione il file deve contenere questa struttura:

# Analisi del problema: Registro del laboratorio

## Scenario riscritto

## Utenti

## Azioni principali

## Regole esplicite

## Regole implicite

## Regole da chiarire

## Vincoli pratici

## Requisiti verificabili

## Criteri di accettazione

## Glossario aggiornato

Non serve scrivere un documento lungo. Serve scrivere un documento che separa le idee. Se una frase non sai dove metterla, probabilmente va discussa meglio.

Passo 1: riscrivi lo scenario

La prima cosa da fare è riscrivere il testo in modo più pulito, senza cambiare ancora il significato.

Esempio:

## Scenario riscritto

Il laboratorio scolastico contiene strumenti e dispositivi usati durante le attività didattiche.
I docenti devono poter sapere quali strumenti sono disponibili e quali sono in prestito.
Quando uno strumento viene prestato a uno studente, il prestito deve essere registrato.
Quando lo strumento torna, il prestito deve essere chiuso.
Se lo strumento torna guasto o incompleto, deve essere possibile aprire una segnalazione.
Il tecnico deve poter vedere quali strumenti richiedono controllo o manutenzione.
I dati principali devono restare disponibili dopo il refresh della pagina.

Questa riscrittura non è ancora una lista di requisiti. È una versione più leggibile del problema. Serve a eliminare ambiguità grossolane.

Attenzione: non aggiungere soluzioni tecniche non richieste. Non scrivere subito “database”, “login”, “dashboard avanzata” o “notifiche automatiche” se lo scenario non le richiede.

Passo 2: individua gli utenti

Dal testo emergono almeno tre ruoli:

• docente;
• studente;
• tecnico.

Puoi aggiungere altri ruoli solo se servono davvero. Un ruolo non è un nome da mettere in lista: deve avere un motivo per esistere nel sistema.

Esempio:

## Utenti

- Docente: registra strumenti, cerca disponibilità, apre e chiude prestiti.
- Studente: riceve uno strumento in prestito, ma nella prima versione non usa direttamente il sistema.
- Tecnico: controlla strumenti guasti o in manutenzione e aggiorna lo stato degli strumenti.
- Referente di laboratorio: può essere considerato un docente con responsabilità organizzative, da chiarire se serve un ruolo separato.

Nota importante: lo studente può essere coinvolto nel dominio anche se non accede alla UI. Per esempio, un prestito può contenere il nome dello studente. Questo non significa che dobbiamo creare subito un’area studente.

Passo 3: estrai le azioni principali

Ora cerca i verbi. I verbi sono preziosi perché spesso diventeranno casi d’uso.

Dal testo possiamo ricavare:

• registrare strumenti;
• cercare strumenti;
• filtrare strumenti per stato;
• registrare un prestito;
• chiudere un prestito;
• segnalare un guasto;
• vedere strumenti da controllare;
• salvare dati;
• recuperare dati dopo il refresh.

Scrivi le azioni con un verbo preciso. Evita formule come:

gestire strumenti
gestire prestiti
fare controlli
tenere tutto aggiornato

Sono comode, ma non aiutano a progettare. Meglio:

registrare uno strumento
cercare strumenti disponibili
registrare un prestito
chiudere un prestito
segnare uno strumento come guasto
mostrare strumenti in manutenzione

Esempio di sezione:

## Azioni principali

- Registrare uno strumento.
- Cercare strumenti per nome.
- Filtrare strumenti per categoria.
- Filtrare strumenti per stato.
- Registrare un prestito.
- Chiudere un prestito.
- Aprire una segnalazione di guasto.
- Mostrare gli strumenti da controllare.
- Salvare gli strumenti.
- Caricare gli strumenti salvati.

Non tutte queste azioni avranno subito la stessa importanza. Alcune entrano nella versione minima, altre nella versione completa.

Passo 4: separa regole esplicite, implicite e da chiarire

Le regole esplicite sono quelle che il testo dice quasi direttamente.

Dal testo:

I dati non devono sparire ogni volta che si ricarica la pagina.

Possibile regola o vincolo:

Gli strumenti registrati devono essere ricaricabili dopo il refresh della pagina.

Le regole implicite sono quelle che il testo suggerisce, ma non dichiara completamente.

Dal testo:

A volte gli strumenti tornano rotti o incompleti.

Possibili regole implicite:

• uno strumento restituito guasto non deve tornare automaticamente disponibile;
• uno strumento incompleto potrebbe richiedere manutenzione;
• una segnalazione di guasto deve riferirsi a uno strumento esistente.

Le regole da chiarire sono quelle su cui non possiamo decidere da soli.

Esempi:

• “Incompleto” è uno stato dello strumento o una nota dentro la segnalazione?
• Uno strumento in manutenzione può essere prestato?
• Chi può cambiare uno strumento da guasto a disponibile?
• Serve registrare la posizione fisica dello strumento, per esempio armadio o aula?
• Serve conservare lo storico di tutti i guasti?

Questa sezione è importantissima: non tutto ciò che è ambiguo deve essere risolto inventando. A volte la scelta corretta è segnare una domanda.

Esempio di sezione:

## Regole esplicite

- I prestiti devono essere registrati.
- Gli strumenti disponibili devono essere distinguibili da quelli non disponibili.
- I dati principali non devono sparire al refresh della pagina.

## Regole implicite

- Uno strumento già in prestito non dovrebbe essere prestato di nuovo.
- Uno strumento guasto non dovrebbe essere prestato.
- Se uno strumento torna guasto, non dovrebbe tornare disponibile automaticamente.
- Una segnalazione di guasto deve riferirsi a uno strumento esistente.

## Regole da chiarire

- Lo stato "incompleto" è diverso da "guasto"?
- La posizione fisica dello strumento deve essere tracciata?
- Chi può segnare uno strumento come riparato?

Passo 5: riconosci i vincoli pratici

Un vincolo pratico non dice solo che cosa fa il sistema, ma entro quali condizioni deve farlo.

Dal testo:

vorrebbe segnarlo velocemente

Possibile vincolo:

La registrazione di un prestito deve richiedere pochi dati obbligatori: strumento, studente e data di inizio.

Dal testo:

I dati non devono sparire ogni volta che si ricarica la pagina.

Possibile vincolo:

Nella versione completa i dati devono essere salvati in localStorage o in un file JSON.

Altri vincoli coerenti con il corso:

## Vincoli pratici

- Il progetto deve funzionare nel browser senza framework complessi.
- La prima versione può usare un archivio in memoria.
- La versione successiva deve permettere il salvataggio in localStorage o JSON.
- I messaggi mostrati all'utente devono essere comprensibili.
- Le regole principali non devono stare solo nella UI.
- Il progetto deve essere organizzato in file separati.

I vincoli pratici ci impediscono di costruire una soluzione troppo grande. Per questo sono utili quanto i requisiti.

Passo 6: scrivi requisiti verificabili

Ora puoi trasformare azioni e regole in requisiti.

Esempi:

## Requisiti verificabili

- 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 indicando strumento, studente e data di inizio.
- Il docente può chiudere un prestito aperto.
- Il tecnico può aprire una segnalazione di guasto per uno strumento esistente.
- Il tecnico può visualizzare gli strumenti guasti o in manutenzione.
- Il sistema conserva gli strumenti registrati dopo il refresh della pagina nella versione con persistenza browser.

Ogni requisito deve superare questa prova:

Posso descrivere uno scenario che dimostra se funziona oppure no?

Se la risposta è no, il requisito va riscritto.

Passo 7: aggiungi criteri di accettazione

Scegli almeno tre requisiti importanti. Per ciascuno scrivi criteri di accettazione.

Esempio sui prestiti:

### Il docente può registrare un prestito

- dato uno strumento disponibile, quando il docente registra un prestito, il prestito viene creato;
- dopo la registrazione del prestito, lo strumento risulta in prestito;
- dato uno strumento guasto, il sistema rifiuta il prestito;
- dato uno strumento già in prestito, il sistema rifiuta un secondo prestito.

Esempio sulla ricerca:

### Il docente può cercare strumenti

- 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, viene mostrato un messaggio comprensibile.

Esempio sui guasti:

### Il tecnico può aprire una segnalazione di guasto

- dato uno strumento esistente, la segnalazione viene registrata;
- dopo la segnalazione, lo strumento risulta guasto o in manutenzione secondo la regola scelta;
- dato uno strumento inesistente, l'operazione viene rifiutata;
- la segnalazione contiene almeno data e descrizione del problema.

Questi criteri saranno utili nei moduli successivi quando scriveremo test e casi d’uso.

Passo 8: aggiorna il glossario

Dal testo possiamo estrarre parole importanti:

• strumento;
• prestito;
• docente;
• studente;
• tecnico;
• disponibile;
• in prestito;
• guasto;
• incompleto;
• manutenzione;
• segnalazione;
• persistenza.

Per ogni parola chiediti:

Questa parola diventerà un nome nel codice?
Indica un dato, un'azione, una regola o uno stato?
Ci sono sinonimi che dobbiamo evitare?

Esempio:

## Glossario aggiornato

- Strumento: oggetto o dispositivo del laboratorio che può essere registrato, cercato, prestato o segnalato come guasto.
- Prestito: periodo in cui uno strumento viene assegnato a uno studente e non è disponibile per altri.
- Segnalazione di guasto: nota che descrive un problema rilevato su uno strumento.
- Stato strumento: condizione corrente dello strumento, per esempio disponibile, in prestito, guasto o in manutenzione.
- Persistenza: modo in cui il sistema conserva i dati oltre l'esecuzione corrente.

Il glossario non è un dizionario scolastico. È una difesa contro il caos dei sinonimi. Se in un file scriviamo “device”, in un altro “strumento” e in un altro “attrezzatura”, il progetto diventa più difficile da seguire.

Variante in gruppo

Se lavorate in classe, dividetevi in gruppi di due o tre persone.

Ogni gruppo riceve lo stesso scenario e produce la propria scheda. Dopo 15 minuti confrontate:

• quali utenti avete trovato;
• quali azioni avete nominato;
• quali regole implicite sono emerse;
• quali domande avete messo tra le regole da chiarire;
• quali requisiti sono davvero verificabili;
• quali parole del glossario avete scelto.

Il confronto serve a mostrare una cosa importante: il problema non è solo scrivere codice. Prima bisogna accordarsi sul significato. Due gruppi possono avere codice diverso perché hanno capito il problema in modo diverso.

Errore da evitare

Non trasformare ogni frase in una feature.

Dal testo:

spesso non si sa dove siano

Potresti interpretarlo in modi diversi:

• non si sa se lo strumento è disponibile;
• non si sa chi lo ha preso;
• non si sa in quale aula si trova;
• non si sa se è guasto;
• non si sa se è stato restituito.

Non scegliere automaticamente l’interpretazione più grande. Per la prima versione può bastare sapere se lo strumento è disponibile, in prestito, guasto o in manutenzione. La posizione fisica può essere una domanda da chiarire o un requisito rimandato.

Questa è una scelta architetturale piccola ma reale: ridurre il problema per costruire una base solida.

Consegna

Completa il file docs/requisiti.md con:

• uno scenario riscritto in modo chiaro;
• almeno tre utenti;
• almeno otto azioni principali;
• almeno tre regole esplicite;
• almeno quattro regole implicite;
• almeno tre regole da chiarire;
• almeno quattro vincoli pratici;
• almeno sei requisiti verificabili;
• almeno tre requisiti con criteri di accettazione;
• almeno dieci parole nel glossario.

La consegna non deve essere perfetta. Deve però essere abbastanza chiara da poter iniziare il modulo sul dominio.

Controllo finale del modulo

Il Modulo 5 è completato quando puoi rispondere sì a queste domande:

• so chi usa o riguarda il Registro del laboratorio;
• so quali azioni principali il sistema deve supportare;
• ho distinto comportamenti, regole e vincoli;
• ho segnato le ambiguità invece di inventare risposte non richieste;
• ho scritto requisiti verificabili;
• ho aggiornato il glossario con parole coerenti;
• ho evitato frasi vaghe come “gestire bene”;
• posso usare questo materiale per modellare Strumento, Prestito e StatoStrumento.

Nel prossimo modulo useremo questa analisi per costruire il dominio. Passeremo dalle frasi ai concetti centrali del progetto: strumenti, prestiti, stati, regole e invarianti.