Azioni principali: registrare, cercare, prestare, restituire, segnalare

Ora che abbiamo individuato gli utenti, dobbiamo chiarire quali azioni compiono nel Registro del laboratorio.

Un corso di architettura del software non parte da pattern complicati. Parte da frasi come queste:

Il docente registra uno strumento.
Il docente cerca strumenti disponibili.
Il docente registra un prestito.
Il docente chiude un prestito.
Il tecnico apre una segnalazione di guasto.

Queste frasi sono il ponte tra problema e codice.

Obiettivo

Alla fine devi produrre una lista di azioni principali, scritte in modo chiaro e verificabile.

Ogni azione deve indicare:

• chi la compie;
• che cosa vuole ottenere;
• quali dati servono;
• quale risultato produce;
• quali errori possono accadere.

Questa lista prepara i futuri casi d’uso.

Azione, bottone e funzione non sono la stessa cosa

Questo punto è importante.

Una azione del sistema non è per forza un bottone.

Esempio:

Registrare un prestito

Può essere avviata da:

• un bottone in una pagina web;
• un comando in una CLI;
• una chiamata da un test;
• una chiamata futura da una API.

Se confondiamo azione e bottone, finiamo con codice come:

buttonPresta.addEventListener("click", () => {
  // tutta la logica del prestito qui dentro
});

Il corso vuole portarci verso una forma più chiara:

registraPrestito({ strumentoId, studente, data });

La UI raccoglie input. Il caso d’uso coordina l’azione.

Questa distinzione evita nomi come:

onClickPresta()
handleSubmit()
gestisciForm()

Questi nomi descrivono un evento dell’interfaccia, non il comportamento del sistema. In un progetto piccolo possono bastare. In un percorso di architettura vogliamo nomi che restino comprensibili anche se domani cambiamo UI.

Azioni di dominio e azioni tecniche

Non tutte le azioni hanno lo stesso valore.

Azioni tecniche:

• cliccare un bottone;
• aprire una modale;
• salvare in localStorage;
• aggiornare il render della lista.

Azioni del problema:

• registrare uno strumento;
• cercare strumenti;
• registrare un prestito;
• chiudere un prestito;
• aprire una segnalazione di guasto.

Le azioni del problema devono guidare i nomi importanti del progetto. Le azioni tecniche sono dettagli di UI o infrastruttura.

Esempio:

Azione del problema:
  Registrare un prestito

Dettaglio UI:
  click sul bottone "Presta"

Dettaglio infrastruttura:
  aggiornamento del dato salvato in localStorage

Se confondiamo questi livelli, il progetto diventa un insieme di event listener. Se li distinguiamo, iniziamo a vedere i futuri casi d’uso.

Le cinque azioni fondamentali

Per il percorso base usiamo cinque azioni centrali.

Non sono le uniche possibili, ma bastano per costruire un progetto ricco.

1. Registrare uno strumento

Scopo:

Aggiungere al registro uno strumento o dispositivo presente nel laboratorio.

Dati richiesti:

• nome;
• categoria;
• stato iniziale;
• eventuale codice inventario;
• eventuale posizione.

Esempio:

Nome: Arduino Uno
Categoria: microcontrollore
Stato: disponibile
Codice inventario: LAB-ARD-001
Posizione: armadio 2

Risultato atteso:

• lo strumento compare nella lista;
• ha un identificativo;
• può essere cercato;
• ha uno stato valido.

Errori possibili:

• nome mancante;
• categoria mancante;
• stato non valido;
• codice inventario duplicato, se decidiamo di usarlo.

Domande utili:

• chi può registrare uno strumento?
• lo stato iniziale può essere diverso da disponibile?
• il codice inventario è obbligatorio o facoltativo?
• due strumenti possono avere lo stesso nome?

Queste domande non sono ancora codice, ma evitano scelte casuali.

2. Cercare strumenti

Scopo:

Trovare rapidamente strumenti per nome, categoria o stato.

Dati richiesti:

• testo di ricerca opzionale;
• categoria opzionale;
• stato opzionale.

Esempi di ricerca:

arduino
categoria = robotica
stato = disponibile
categoria = audio, stato = guasto

Risultato atteso:

• il sistema restituisce una lista;
• se non ci sono risultati, mostra un messaggio comprensibile;
• la ricerca non modifica i dati.

Errori possibili:

• filtri non riconosciuti;
• dati salvati in formato incoerente;
• ricerca troppo rigida che non trova nomi simili.

Una regola importante:

Cercare strumenti non deve cambiare lo stato del registro.

Questa sembra ovvia, ma è utile. La ricerca dovrebbe essere una lettura, non una modifica.

3. Registrare un prestito

Scopo:

Associare uno strumento disponibile a una persona per un periodo di tempo.

Dati richiesti:

• id dello strumento;
• nome dello studente o gruppo;
• data di inizio;
• eventuale data prevista di restituzione;
• eventuali note.

Risultato atteso:

• nasce un prestito aperto;
• lo strumento passa allo stato in_prestito;
• il sistema impedisce prestiti non validi.

Regole importanti:

• 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;
• il prestito deve riferirsi a uno strumento esistente.

Questa azione è la più ricca del progetto perché tocca molti concetti:

• strumento;
• stato;
• studente o gruppo;
• prestito aperto;
• regole di validità;
• messaggi di errore.

Per questo diventerà uno dei casi d’uso principali del corso.

4. Chiudere un prestito

Scopo:

Registrare la restituzione di uno strumento.

Dati richiesti:

• id del prestito;
• data di chiusura;
• eventuali note di restituzione;
• eventuale stato finale dello strumento.

Risultato atteso:

• il prestito diventa chiuso;
• lo strumento torna disponibile oppure viene segnato come guasto;
• il prestito non può essere chiuso due volte.

Esempio:

Il kit sensori torna in laboratorio, ma manca un cavo.
Il prestito viene chiuso e lo strumento viene segnato come in manutenzione.

Questo esempio mostra che chiudere un prestito non significa sempre “tutto ok”.

Domande utili:

• chi decide lo stato finale dello strumento?
• se lo strumento torna danneggiato, si apre anche una segnalazione?
• la data di chiusura è automatica o inserita dall’utente?
• cosa succede se il prestito è già chiuso?

5. Aprire una segnalazione di guasto

Scopo:

Registrare che uno strumento ha un problema.

Dati richiesti:

• id dello strumento;
• descrizione del problema;
• persona che segnala;
• data;
• eventuale priorità.

Risultato atteso:

• viene registrata una segnalazione;
• lo strumento cambia stato, per esempio guasto;
• il sistema mostra un messaggio chiaro.

Errori possibili:

• strumento non trovato;
• descrizione vuota;
• segnalazione duplicata;
• stato dello strumento non aggiornato.

Questa azione introduce una scelta interessante: aprire una segnalazione deve sempre mettere lo strumento in stato guasto? Oppure può esistere una segnalazione lieve che non blocca il prestito?

Per il percorso base scegliamo una regola semplice:

Aprire una segnalazione di guasto rende lo strumento non prestabile.

Più avanti potremo raffinarla.

Tabella riassuntiva

Usa questa tabella per vedere la struttura complessiva:

| Azione | Attore principale | Dati minimi | Risultato | Modifica dati? |
| --- | --- | --- | --- | --- |
| Registrare strumento | Docente/Tecnico | nome, categoria | nuovo strumento | sì |
| Cercare strumenti | Docente/Tecnico/Referente | filtri | lista risultati | no |
| Registrare prestito | Docente | strumento, studente | prestito aperto | sì |
| Chiudere prestito | Docente/Tecnico | prestito | prestito chiuso | sì |
| Segnalare guasto | Docente/Tecnico | strumento, descrizione | segnalazione aperta | sì |

La colonna “Modifica dati?” è importante. Aiuta a distinguere operazioni di lettura e operazioni che cambiano lo stato del sistema.

Scheda azione

Per ogni azione compila una scheda come questa:

## Nome azione

Chi la compie:

Scopo:

Dati richiesti:
- ...

Risultato prodotto:
- ...

Regole coinvolte:
- ...

Errori possibili:
- ...

Messaggio utente in caso di successo:

Messaggio utente in caso di errore:

Questa scheda non è ancora codice, ma deve essere abbastanza concreta da guidare il codice.

Esempio compilato

## Registrare un prestito

Chi la compie:
Docente.

Scopo:
Associare uno strumento disponibile a uno studente.

Dati richiesti:
- id dello strumento
- nome dello studente
- data di inizio

Risultato prodotto:
- prestito aperto
- strumento in stato in_prestito

Regole coinvolte:
- lo strumento deve esistere
- lo strumento deve essere disponibile
- lo studente deve essere indicato

Errori possibili:
- strumento non trovato
- strumento guasto
- strumento già in prestito
- nome studente mancante

Messaggio utente in caso di successo:
Prestito registrato.

Messaggio utente in caso di errore:
Lo strumento non può essere prestato perché non è disponibile.

Da questa scheda possono nascere nomi di codice:

RegistraPrestito
trovaStrumentoPerId
puoEsserePrestato
creaPrestito
chiudiPrestito

Non tutti questi nomi saranno definitivi. Ma sono già più chiari di gestisciClick.

Attenzione ai verbi

I verbi aiutano a progettare.

Verbi utili:

• registra;
• cerca;
• aggiorna;
• chiudi;
• apri;
• assegna;
• verifica;
• salva.

Verbi deboli:

• gestisci;
• fai;
• sistema;
• controlla tutto;
• modifica cose.

Una funzione chiamata gestisciStrumento può nascondere molte responsabilità. Una funzione chiamata registraPrestito è più precisa.

Un buon verbo dice che cosa cambia nel sistema:

registra -> crea una nuova informazione
cerca -> legge senza modificare
chiudi -> conclude qualcosa che era aperto
segnala -> crea un avviso o un problema
assegna -> collega una cosa a una persona

Quando non sai che verbo usare, probabilmente non hai ancora capito bene l’azione.

Dalle azioni ai futuri casi d’uso

In questo modulo stiamo ancora descrivendo. Nel modulo sui casi d’uso useremo queste stesse azioni per scrivere codice applicativo.

Mappa iniziale:

| Frase del problema | Futuro caso d'uso |
| --- | --- |
| Il docente registra uno strumento | RegistraStrumento |
| Il docente cerca strumenti | CercaStrumenti |
| Il docente registra un prestito | RegistraPrestito |
| Il docente chiude un prestito | ChiudiPrestito |
| Il tecnico segnala un guasto | ApriSegnalazioneGuasto |

Un caso d’uso non è la UI. Non è il database. È il coordinamento dell’azione.

Cosa produrre

Alla fine della lezione devi avere:

• una lista delle azioni principali;
• una scheda per ogni azione;
• almeno tre regole emerse dalle azioni;
• almeno cinque errori possibili scritti in linguaggio comprensibile;
• una prima lista di nomi che potrebbero diventare casi d’uso.

Esercizio guidato

Scegli una delle cinque azioni e completa questa trasformazione:

Frase utente:

Azione del sistema:

Non è:
- bottone:
- funzione di render:
- salvataggio:

Dati in ingresso:
- ...

Risultato:
- ...

Regole:
- ...

Possibile nome del caso d'uso:

Esempio:

Frase utente:
Il docente deve chiudere il prestito quando lo studente restituisce il kit.

Azione del sistema:
Chiudere un prestito.

Non è:
- bottone: "Restituisci"
- funzione di render: aggiornaListaPrestiti
- salvataggio: localStorage.setItem(...)

Dati in ingresso:
- id prestito
- stato finale dello strumento
- note eventuali

Risultato:
- prestito chiuso
- strumento disponibile o in manutenzione

Regole:
- un prestito già chiuso non può essere chiuso di nuovo

Possibile nome del caso d'uso:
ChiudiPrestito

Domande di comprensione

Rispondi per iscritto:

• Perché un’azione del sistema non coincide con un bottone?
• Quale delle cinque azioni non modifica i dati?
• Quale azione contiene più regole di dominio?
• Quale errore utente deve essere espresso con un messaggio comprensibile?
• Quali nomi potrebbero diventare casi d’uso applicativi?

Controllo finale

La lezione è completata quando puoi rispondere sì:

• ho distinto azione di sistema e bottone della UI;
• ogni azione ha uno scopo chiaro;
• ogni azione ha input e risultato;
• ho scritto errori possibili;
• ho evitato verbi generici come “gestisci”;
• posso già immaginare alcuni casi d’uso applicativi.

Nella prossima lezione separiamo regole esplicite e regole implicite.