Modellare Strumento: id, nome, categoria e stato

Il primo concetto centrale del Registro del laboratorio è lo Strumento.

Uno strumento può essere un dispositivo, un kit, un accessorio o una macchina presente nel laboratorio:

• Arduino Uno;
• kit sensori;
• multimetro;
• proiettore;
• notebook;
• stampante 3D;
• microscopio;
• oscilloscopio;
• cuffie;
• router didattico.

Nel programma fragile potremmo rappresentarlo come capita, aggiungendo proprietà al volo. In un punto del codice potremmo usare nome, in un altro name, in un altro ancora titolo. All’inizio sembra innocuo, poi la ricerca non trova risultati, il prestito punta allo strumento sbagliato e ogni modifica diventa un inseguimento.

In questa lezione diamo a Strumento una forma stabile. Non per fare teoria, ma per evitare dati inutilizzabili.

Obiettivo della lezione

Alla fine devi avere un primo modello Strumento con:

• id;
• nome;
• categoria;
• stato;
• validazioni minime;
• esempi validi;
• esempi non validi;
• una breve scheda che spiega le scelte.

Il modello non deve essere perfetto. Deve essere abbastanza chiaro da sostenere le prossime operazioni: ricerca, prestito, cambio stato e segnalazione di guasto.

Il modello minimo

Un primo strumento può essere rappresentato così:

const strumento = {
  id: "str-001",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile",
};

Questi quattro campi bastano per molte funzioni del Registro:

• registrare lo strumento;
• mostrarlo in elenco;
• cercarlo per nome;
• filtrarlo per categoria;
• capire se può essere prestato;
• cambiarne lo stato;
• collegarlo a un prestito.

La tentazione sarà aggiungere subito molti altri campi:

• codice inventario;
• posizione fisica;
• marca;
• modello;
• foto;
• data di acquisto;
• responsabile;
• note;
• storico manutenzioni.

Sono informazioni plausibili, ma non tutte servono adesso. In questa fase partiamo dai campi che sostengono le regole principali. Aggiungeremo altro solo quando il percorso ne avrà bisogno.

Campo id: identità stabile

L’id identifica lo strumento.

Il nome può cambiare. La categoria può cambiare. Lo stato cambia spesso. L’id deve rimanere stabile perché il resto del sistema possa riferirsi sempre allo stesso strumento.

Esempio:

const strumento = {
  id: "str-001",
  nome: "Kit Arduino base",
  categoria: "robotica",
  stato: "disponibile",
};

Evita di usare il nome come identificativo:

// Fragile: due strumenti possono avere lo stesso nome.
const strumento = strumenti.find((item) => item.nome === "Arduino Uno");

Se nel laboratorio ci sono cinque Arduino Uno, il nome non basta. Meglio usare l’id:

const strumento = strumenti.find((item) => item.id === strumentoId);

Regola minima:

Uno strumento deve avere un id non vuoto.

Domanda da segnare negli appunti:

L'id viene scritto a mano, generato dal programma o preso da un codice inventario?

Per ora possiamo generarlo nel caso d’uso o prepararlo nei dati di esempio. Il dominio deve solo rifiutare un id mancante.

Campo nome: etichetta comprensibile

Il nome è ciò che l’utente legge. Deve essere comprensibile a chi usa il laboratorio.

Esempi buoni:

Arduino Uno
Multimetro digitale
Microscopio ottico
Kit sensori temperatura
Router didattico

Esempi deboli:

coso
strumento 1
kit
varie
?

Non sempre possiamo impedire nomi poco descrittivi, ma possiamo impedire almeno il caso peggiore: nome vuoto.

Regola minima:

Uno strumento deve avere un nome non vuoto.

Strumento non valido:

{
  id: "str-002",
  nome: "",
  categoria: "audio",
  stato: "disponibile",
}

Perché è un problema? Perché la lista sarebbe illeggibile, la ricerca non aiuterebbe e un prestito collegato a uno strumento senza nome sarebbe difficile da spiegare.

Campo categoria: organizzazione per gruppi

La categoria aiuta a cercare e raggruppare gli strumenti.

Esempi:

robotica
elettronica
audio
video
reti
misura
ottica
stampa 3D

Nella versione base possiamo trattarla come testo. Questo riduce la complessità iniziale.

Regola minima:

Uno strumento deve avere una categoria non vuota.

Più avanti potremmo decidere che la categoria deve appartenere a una lista chiusa. Per esempio:

const categorieAmmesse = ["robotica", "elettronica", "audio", "video", "reti", "misura"];

Ma non è necessario introdurre questa regola subito. Nel corso stiamo imparando a costruire il modello per passi, non a bloccare ogni possibilità dall’inizio.

Una buona domanda da tenere aperta:

La categoria serve solo per cercare, oppure produce regole diverse?

Se serve solo per cercare, può restare un testo controllato in modo leggero. Se invece alcune categorie hanno regole speciali, allora diventerà una parte più importante del dominio.

Campo stato: informazione che guida le regole

Lo stato indica la condizione corrente dello strumento.

Per il Registro useremo questi stati:

disponibile
in_prestito
guasto
in_manutenzione

Lo stato non è solo una parola da mostrare con un colore. È un dato che cambia il comportamento del sistema.

Esempi:

• uno strumento disponibile può essere prestato;
• uno strumento in prestito non può essere prestato di nuovo;
• uno strumento guasto non può essere prestato;
• uno strumento in manutenzione non può essere prestato.

Per questo stato appartiene al dominio.

Esempio fragile:

const strumento = {
  id: "str-003",
  nome: "Multimetro",
  categoria: "misura",
  stato: "rotto",
};

Se nel resto del programma usiamo guasto, lo stato rotto potrebbe non essere riconosciuto. Magari la UI lo mostra, ma la regola di prestito non lo blocca.

Regola minima:

Uno strumento deve avere uno stato valido.

Nella prossima lezione renderemo StatoStrumento più preciso. Qui ci basta capire che lo stato non può essere una stringa qualunque.

Prima funzione: creaStrumento

Creiamo una funzione di dominio che costruisce strumenti validi.

File:

src/domain/strumento.js

Codice:

import { StatoStrumento } from "./statoStrumento.js";

export function creaStrumento({ id, nome, categoria, stato = StatoStrumento.DISPONIBILE }) {
  if (!id || id.trim() === "") {
    throw new Error("ID_STRUMENTO_OBBLIGATORIO");
  }

  if (!nome || nome.trim() === "") {
    throw new Error("NOME_STRUMENTO_OBBLIGATORIO");
  }

  if (!categoria || categoria.trim() === "") {
    throw new Error("CATEGORIA_STRUMENTO_OBBLIGATORIA");
  }

  if (!Object.values(StatoStrumento).includes(stato)) {
    throw new Error("STATO_STRUMENTO_NON_VALIDO");
  }

  return {
    id: id.trim(),
    nome: nome.trim(),
    categoria: categoria.trim(),
    stato,
  };
}

Questa funzione fa una cosa precisa: impedisce di creare strumenti privi dei dati minimi.

Non legge campi HTML. Non salva in localStorage. Non mostra messaggi. Non decide come appare la card dello strumento. Per questo può stare nel dominio.

Perché usiamo errori tecnici brevi

Gli errori come NOME_STRUMENTO_OBBLIGATORIO non sono messaggi finali per l’utente.

Non vogliamo mostrare necessariamente questo testo nella pagina:

NOME_STRUMENTO_OBBLIGATORIO

Più avanti la Presentation potrà tradurlo in:

Inserisci il nome dello strumento.

Per ora l’errore breve ci aiuta a distinguere le regole violate. È stabile, facile da testare e non dipende dal tono della UI.

Questa distinzione sarà importante nel modulo sugli errori:

• il dominio segnala quale regola è stata violata;
• la UI trasforma l’errore in un messaggio comprensibile.

Validare poco, ma bene

Potremmo aggiungere molte regole:

• lunghezza massima del nome;
• categorie predefinite;
• codice inventario obbligatorio;
• posizione fisica;
• data di acquisto;
• responsabile;
• foto obbligatoria;
• marca e modello;
• storico manutenzioni.

Non ora.

In questa fase vogliamo un modello abbastanza forte da evitare dati inutilizzabili, ma non così grande da rallentare il laboratorio. Il principio pratico è:

Validare ciò che serve alle regole principali.

Per il momento servono:

• id, perché prestiti e ricerche interne devono riferirsi allo strumento giusto;
• nome, perché utenti e ricerca devono riconoscere lo strumento;
• categoria, perché serve per filtrare;
• stato, perché determina se lo strumento può essere prestato.

Tutto il resto può aspettare.

Esempi validi

Esempio 1:

creaStrumento({
  id: "str-001",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile",
});

Esempio 2:

creaStrumento({
  id: "str-002",
  nome: "Multimetro digitale",
  categoria: "misura",
  stato: "in_manutenzione",
});

Esempio 3, con spazi da ripulire:

creaStrumento({
  id: " str-003 ",
  nome: "  Microscopio ottico  ",
  categoria: " ottica ",
  stato: "disponibile",
});

Risultato atteso:

{
  id: "str-003",
  nome: "Microscopio ottico",
  categoria: "ottica",
  stato: "disponibile",
}

Ripulire gli spazi è una scelta utile perché evita differenze inutili nei dati. Non è una regola complicata, ma migliora subito la qualità del modello.

Esempi non validi

Nome mancante:

creaStrumento({
  id: "str-004",
  nome: "",
  categoria: "audio",
  stato: "disponibile",
});

Errore atteso:

NOME_STRUMENTO_OBBLIGATORIO

Id mancante:

creaStrumento({
  id: "",
  nome: "Proiettore",
  categoria: "video",
  stato: "disponibile",
});

Errore atteso:

ID_STRUMENTO_OBBLIGATORIO

Categoria mancante:

creaStrumento({
  id: "str-005",
  nome: "Router didattico",
  categoria: "   ",
  stato: "disponibile",
});

Errore atteso:

CATEGORIA_STRUMENTO_OBBLIGATORIA

Stato non valido:

creaStrumento({
  id: "str-006",
  nome: "Stampante 3D",
  categoria: "stampa 3D",
  stato: "rotta",
});

Errore atteso:

STATO_STRUMENTO_NON_VALIDO

Mini-test manuale

Anche senza introdurre ancora un framework di test, puoi verificare la funzione con piccoli esempi.

import { creaStrumento } from "./src/domain/strumento.js";

console.log(
  creaStrumento({
    id: "str-001",
    nome: "Arduino Uno",
    categoria: "microcontrollori",
    stato: "disponibile",
  })
);

Poi prova un caso non valido:

try {
  creaStrumento({
    id: "str-002",
    nome: "",
    categoria: "misura",
    stato: "disponibile",
  });
} catch (errore) {
  console.log(errore.message);
}

Risultato atteso:

NOME_STRUMENTO_OBBLIGATORIO

Questo non sostituisce i test automatici, ma prepara lo studente a pensare per esempi: dato un input, quale risultato mi aspetto?

Scheda del modello

Aggiorna il README o crea un file docs/modello-dominio.md con questa scheda:

# Modello Strumento

## Scopo

Rappresenta un oggetto o dispositivo del laboratorio che può essere cercato, prestato, restituito o segnalato come guasto.

## Campi

- id: identificativo stabile dello strumento.
- nome: nome leggibile per utenti e docenti.
- categoria: gruppo utile per ricerca e organizzazione.
- stato: condizione corrente dello strumento.

## Regole minime

- id obbligatorio.
- nome obbligatorio.
- categoria obbligatoria.
- stato valido.

## Domande rimaste aperte

- Serve un codice inventario separato dall'id?
- Serve registrare la posizione fisica?
- Le categorie devono diventare una lista chiusa?
- Serve distinguere guasto da incompleto?

Le domande aperte non sono debolezze. Sono confini consapevoli: non stiamo ignorando quei temi, li stiamo rimandando al momento giusto.

Attività pratica

Scrivi cinque strumenti realistici del tuo laboratorio. Per ciascuno indica:

• id;
• nome;
• categoria;
• stato.

Poi prova a creare quattro strumenti non validi:

• senza id;
• senza nome;
• senza categoria;
• con stato non valido.

Per ogni caso non valido annota:

• input usato;
• errore atteso;
• perché l’errore protegge il dominio.

Esempio:

## Caso non valido

Input: strumento con nome vuoto.
Errore atteso: NOME_STRUMENTO_OBBLIGATORIO.
Perché serve: evita strumenti impossibili da riconoscere nella lista, nella ricerca e nei prestiti.

Cosa produrre

Alla fine della lezione devi avere:

• file src/domain/strumento.js;
• funzione creaStrumento;
• almeno cinque esempi validi;
• almeno quattro esempi non validi;
• scheda del modello Strumento aggiornata nel README o in docs/modello-dominio.md;
• una nota sulle domande aperte, senza trasformarle subito in codice.

Controllo finale

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

• so quali campi minimi descrivono uno strumento;
• uso id per identificare lo strumento;
• non creo strumenti senza nome;
• non creo strumenti senza categoria;
• non accetto stati casuali;
• non confondo categoria e stato;
• il modello non dipende da HTML o localStorage;
• posso verificare creaStrumento senza aprire il browser.

Nella prossima lezione rendiamo più preciso StatoStrumento, perché gli stati non sono solo parole: decidono quali operazioni sono permesse.