Mappa del sistema Registro del laboratorio

Una mappa non è il sistema.

È uno strumento per capirlo, parlarne e cambiarlo senza andare a tentativi.

In questa lezione disegneremo una mappa semplice del Registro del laboratorio scolastico. Non useremo UML complesso. Useremo nomi chiari, caselle e frecce.

L’idea da rendere visibile è questa:

il programma non è solo la pagina web.

Ci sono persone, operazioni, regole, dati e confini.

Se non li vediamo, finiamo per mettere tutto nello stesso file.

Obiettivo della lezione

Alla fine devi avere:

• una vista esterna del sistema;
• una lista degli attori coinvolti;
• una lista delle funzionalità principali;
• una mappa dei quattro livelli didattici;
• una mappa del flusso RegistraPrestito;
• una mini-mappa di un secondo flusso a tua scelta.

Il prodotto può stare in diagrammi.md, nel README o negli appunti del laboratorio.

Perché fare una mappa

Una mappa serve a rispondere a domande che il codice da solo spesso nasconde:

• chi usa il sistema?
• per fare cosa?
• quali operazioni esistono?
• quali regole devono valere sempre?
• quali dati vengono salvati?
• dove entra l’utente?
• dove finisce la UI?
• dove inizia il dominio?

Se uno studente nuovo apre il progetto e vede solo main.js, deve ricostruire tutto mentalmente.

Una mappa riduce quel lavoro.

Vista esterna

La prima mappa guarda il sistema da fuori.

Docente / Tecnico di laboratorio
  usa
Registro del laboratorio scolastico
  per
registrare strumenti, cercare dispositivi, gestire prestiti e segnalare guasti

Questa mappa è volutamente semplice.

Serve a chiarire tre cose:

Domanda	Risposta
Chi usa il sistema?	docente o tecnico di laboratorio
Qual è il sistema?	Registro del laboratorio scolastico
A cosa serve?	gestire strumenti, stati, prestiti e guasti

Se non sai scrivere questa vista, rischi di progettare funzioni senza sapere a quale problema servono.

Attori principali

Nel progetto possiamo distinguere più persone coinvolte.

Attore	Ruolo nel progetto
Docente	registra prestiti, cerca strumenti, controlla disponibilità
Tecnico di laboratorio	aggiorna stati, segnala guasti, gestisce manutenzione
Studente	riceve uno strumento, ma non necessariamente usa la UI
Docente valutatore	legge codice, README, test e scelte tecniche

Non tutti gli attori sono utenti diretti.

Lo studente, per esempio, può comparire come destinatario di un prestito senza avere accesso al sistema.

Questa distinzione evita un errore frequente: confondere “persona presente nel dominio” con “utente che clicca nella UI”.

Funzionalità principali

Ora elenchiamo cosa deve fare il Registro.

Funzionalità	Descrizione pratica	Possibile caso d’uso
Registrare uno strumento	inserire nome, categoria e stato iniziale	RegistraStrumento
Cercare strumenti	filtrare per nome, categoria o stato	CercaStrumenti
Registrare un prestito	collegare uno strumento a una persona	RegistraPrestito
Chiudere un prestito	segnare che lo strumento è rientrato	ChiudiPrestito
Segnalare un guasto	cambiare stato e registrare motivo	ApriSegnalazioneGuasto
Cambiare stato	aggiornare disponibilità, guasto o manutenzione	operazione controllata dal dominio

Questa tabella non è ancora implementazione.

È un indice delle operazioni che il progetto dovrà sostenere.

Vista interna a livelli

La seconda mappa guarda dentro il sistema.

Presentation / UI
  form, pulsanti, lista strumenti, messaggi

Application
  casi d'uso: RegistraStrumento, CercaStrumenti, RegistraPrestito

Domain
  Strumento, Prestito, StatoStrumento, regole e invarianti

Infrastructure
  archivio in memoria, localStorage, JSON, database o API

Questa è la struttura didattica del corso.

Nel codice fragile non è ancora rispettata.

La mappa serve proprio a mostrare la distanza tra il punto di partenza e il punto di arrivo.

Regole da mettere nel dominio

Le regole candidate del dominio sono:

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 uno stato valido
un prestito aperto deve riferirsi a uno strumento esistente

Queste regole non sono dettagli della pagina.

Devono valere anche se domani sostituiamo la pagina web con una CLI o con una API.

Per questo nella mappa stanno nel dominio.

Dati salvati

All’inizio possiamo avere solo:

strumenti
prestiti

Poi potremmo aggiungere:

segnalazioniGuasto
utenti
log

Non serve salvare tutto subito.

Però è utile nominare i dati principali, perché ogni dato salvato ha bisogno di una responsabilità:

Dato	A cosa serve	Dove viene gestito
strumenti	elenco degli strumenti del laboratorio	archivio strumenti
prestiti	prestiti aperti e chiusi	archivio prestiti
segnalazioniGuasto	motivi e date dei guasti	archivio segnalazioni
log	traccia tecnica di eventi importanti	infrastruttura o logging

La parola “archivio” è intenzionale.

Non dice ancora se useremo memoria, localStorage, JSON o database. Dice che quella responsabilità esiste.

Flusso: RegistraPrestito

Ora mappiamo un flusso completo.

Docente
  inserisce id strumento e nome studente
    |
    v
Presentation / UI
  legge input e prepara il comando
    |
    v
Application / RegistraPrestito
  cerca lo strumento
  verifica le condizioni
  crea il prestito
  chiede il salvataggio
    |
    v
Domain
  controlla se lo strumento può essere prestato
  decide il nuovo stato dello strumento
    |
    v
Infrastructure
  legge e salva strumenti e prestiti
    |
    v
Presentation / UI
  mostra esito o errore comprensibile

Questa mappa separa il “cosa succede” dal “dove è scritto oggi”.

Oggi il programma fragile può avere quasi tutto dentro il click.

La mappa ci dice come spezzare quel blocco nei moduli successivi.

Flusso: ApriSegnalazioneGuasto

Secondo esempio:

Tecnico
  sceglie uno strumento e scrive il motivo del guasto
    |
    v
Presentation / UI
  legge strumentoId e descrizione
    |
    v
Application / ApriSegnalazioneGuasto
  cerca lo strumento
  verifica che esista
  registra la segnalazione
  cambia lo stato in guasto
  salva le modifiche
    |
    v
Domain
  verifica che lo stato guasto sia valido
  impedisce transizioni non permesse, se previste
    |
    v
Infrastructure
  salva strumento aggiornato e segnalazione

Questo flusso mostra una cosa importante: non tutte le funzionalità sono solo “cambia un campo”.

Aprire una segnalazione può creare un dato nuovo e cambiare lo stato dello strumento. Per questo conviene nominarla come operazione.

Mappa del codice fragile

Accanto alla mappa desiderata, scrivi anche la mappa attuale.

Esempio:

main.js
  gestisce click
  legge input
  contiene array strumenti
  contiene array prestiti
  applica regole
  salva localStorage
  aggiorna HTML

Questa mappa non deve essere bella.

Deve essere onesta.

Serve a capire quali responsabilità sono concentrate nello stesso punto.

Mappa desiderata minima

Una prima destinazione realistica può essere:

src/
  presentation/
    main.js
  application/
    registraPrestito.js
    cercaStrumenti.js
  domain/
    strumento.js
    prestito.js
    statoStrumento.js
  infrastructure/
    archivioInMemoria.js

Non è la struttura definitiva obbligatoria.

È una possibile mappa minima per separare i primi confini.

La cosa importante non è il nome esatto delle cartelle. È che ogni file abbia una responsabilità leggibile.

Attività guidata

Crea un file diagrammi.md o una sezione nel README con quattro blocchi:

## Vista esterna

## Attori

## Vista interna a livelli

## Flusso RegistraPrestito

Vincoli:

• usa nomi del Registro, non parole generiche;
• non usare UML complesso;
• ogni freccia deve rappresentare una relazione reale;
• se non sai dove mettere una cosa, segnala il dubbio invece di nasconderlo.

Micro-sfida

Disegna il flusso di ApriSegnalazioneGuasto.

Devi indicare:

• chi avvia l’azione;
• quali dati servono;
• quale stato cambia;
• quale regola deve essere rispettata;
• quali dati vanno salvati;
• quale messaggio vede l’utente.

Risultato atteso: una mappa con almeno sei passaggi.

Prodotto da ottenere

Alla fine della lezione devi avere:

• vista esterna del sistema;
• tabella degli attori;
• tabella funzionalità / caso d’uso;
• elenco delle regole candidate del dominio;
• elenco dei dati salvati;
• flusso RegistraPrestito;
• flusso ApriSegnalazioneGuasto o altro flusso scelto.

Domande di comprensione

Rispondi per iscritto:

• Perché la mappa non è solo decorazione?
• Quale attore usa direttamente la UI?
• Quale persona può comparire nel dominio senza usare il sistema?
• Perché RegistraPrestito è un caso d’uso e non solo un click?
• Quale dato salvato sarà più importante proteggere quando cambieremo persistenza?

Controllo finale

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

• ho disegnato una vista esterna del sistema;
• ho individuato gli attori principali;
• ho collegato funzionalità e casi d’uso candidati;
• ho separato regole e dati salvati;
• ho disegnato il flusso di RegistraPrestito;
• ho capito che la mappa serve a guidare il refactoring, non a decorare il README.

Nel prossimo passo useremo la mappa per ragionare su un cambiamento concreto: cosa succede quando vogliamo cambiare la persistenza?