Micro-sfida: aggiungi lo stato in manutenzione

Questa micro-sfida chiude il modulo sul dominio.

Devi aggiungere, o verificare, lo stato:

in_manutenzione

Lo stato deve avere un significato preciso:

Uno strumento in manutenzione non puo essere prestato.

Non basta aggiungere una opzione in una select.

Devi controllare dominio, regole, messaggi e scenari.

Obiettivo

Applicare in piccolo tutto il modulo:

• modello Strumento;
• StatoStrumento;
• regole di prestabilita;
• errori di dominio;
• scenari di test;
• documentazione minima.

Contesto

Nel laboratorio uno strumento puo non essere guasto in modo definitivo, ma essere comunque fuori uso.

Esempi:

• il tecnico lo sta controllando;
• manca un cavo;
• deve essere aggiornato;
• va pulito o calibrato;
• e temporaneamente ritirato.

In questi casi guasto puo essere troppo forte.

Usiamo:

in_manutenzione

Prodotto da consegnare

Qui “consegnare” significa mostrare al docente o al gruppo un risultato verificabile: un file modificato, una scheda compilata, un test, una demo o una nota tecnica.

Aggiorna il dominio in modo che:

• in_manutenzione sia uno stato valido;
• uno strumento in manutenzione non possa essere prestato;
• lo stato sia documentato;
• esista almeno uno scenario di verifica;
• la UI, se presente, possa mostrare un messaggio comprensibile.

Passo 1: aggiorna StatoStrumento

Nel file:

src/domain/statoStrumento.js

controlla che ci sia:

export const StatoStrumento = {
  DISPONIBILE: "disponibile",
  IN_PRESTITO: "in_prestito",
  GUASTO: "guasto",
  IN_MANUTENZIONE: "in_manutenzione",
};

Se manca, aggiungilo.

Poi verifica che isStatoStrumentoValido lo riconosca.

Passo 2: aggiorna la regola di prestabilita

Se la tua regola controlla solo il guasto:

if (strumento.stato === StatoStrumento.GUASTO) {
  throw new Error("STRUMENTO_GUASTO_NON_PRESTABILE");
}

devi ampliarla.

Forma consigliata:

export function verificaStrumentoPrestabile(strumento) {
  if (strumento.stato !== StatoStrumento.DISPONIBILE) {
    throw new Error("STRUMENTO_NON_PRESTABILE");
  }

  return true;
}

Questa regola e piu semplice:

Solo disponibile significa prestabile.

Tutto il resto viene rifiutato.

Passo 3: aggiorna i messaggi

Se usi un messaggio generico:

Questo strumento non puo essere prestato.

va bene.

Se vuoi essere piu specifico, puoi distinguere:

Questo strumento e in manutenzione e non puo essere prestato.

Ma attenzione: la distinzione specifica non deve farti copiare regole in UI.

La UI puo scegliere un messaggio in base al codice errore o allo stato ricevuto, ma la decisione di bloccare il prestito resta nel dominio.

Passo 4: scrivi lo scenario

Scrivi:

## Scenario

Dato uno strumento con stato in_manutenzione,
quando provo a prestarlo,
allora il dominio rifiuta l'operazione con STRUMENTO_NON_PRESTABILE.

Se stai gia scrivendo test, aggiungi:

test("uno strumento in manutenzione non puo essere prestato", () => {
  const strumento = {
    id: "s-001",
    nome: "Stampante 3D",
    categoria: "stampa 3D",
    stato: StatoStrumento.IN_MANUTENZIONE,
  };

  expect(() => verificaStrumentoPrestabile(strumento)).toThrow(
    "STRUMENTO_NON_PRESTABILE"
  );
});

Passo 5: aggiorna la documentazione

Nel glossario o nel README aggiungi:

## Stato: in_manutenzione

Significa che lo strumento e temporaneamente fuori uso per controllo, riparazione o verifica.

Regole:
- non puo essere prestato;
- puo tornare disponibile dopo controllo;
- non va confuso con guasto definitivo.

Vincoli

Durante la micro-sfida:

• non riscrivere tutto il progetto;
• non introdurre framework;
• non cambiare il nome degli stati gia usati senza motivo;
• non mettere la regola solo nella UI;
• non usare stringhe sparse se hai gia StatoStrumento;
• fai modifiche piccole e verificabili.

Spiegazione guidata per studiare

Questa lezione va studiata su due piani. Il primo è il comportamento visibile del Registro del laboratorio: che cosa vede o fa l’utente quando registra uno strumento, cerca un dispositivo, apre un prestito o segnala un guasto. Il secondo è il confine architetturale: dove deve stare il codice che rende possibile quel comportamento.

Per micro-sfida: aggiungi lo stato in manutenzione, il punto centrale è questo: Il dominio contiene il significato del problema: strumenti, prestiti, stati ammessi e regole che devono valere anche se cambia la UI o il modo in cui salviamo i dati.

Il rischio tipico è confondere un controllo di schermata con una regola del progetto. Se una regola protegge il senso del Registro, deve vivere nel dominio o vicino al caso d’uso. Per evitarlo, non partire dal file che hai già aperto nell’editor. Parti dalla domanda: “quale responsabilità sto modificando?”. Se la risposta riguarda una regola del laboratorio, guarda il dominio. Se riguarda una sequenza di operazioni, guarda i casi d’uso. Se riguarda salvataggio, file, localStorage, API o database, guarda l’infrastruttura. Se riguarda input, pulsanti, form e messaggi, guarda la Presentation.

Il tempo è breve: non provare a fare tutto, punta a capire il concetto e produrre un risultato piccolo. Alla fine della lezione lo studente non deve ricordare una definizione a memoria: deve saper indicare un punto del progetto, spiegare perché quel codice sta lì e mostrare una verifica del comportamento.

Passo per passo nel progetto

1. Rileggi il titolo della lezione e riscrivilo come domanda pratica. Per esempio: “dove deve stare questa regola?”, “chi deve salvare questo dato?”, “come verifico questo errore?”.
2. Apri solo i file necessari. Se devi toccare più di tre file, fermati e scrivi prima una mini-mappa.
3. Scrivi la regola in linguaggio naturale.
4. Trasformala in una funzione o in un metodo con un nome leggibile.
5. Verifica almeno un caso valido e un caso non valido.
6. Controlla che la regola non sia duplicata nella UI.
7. Aggiorna una nota breve nel README o negli appunti se hai cambiato un confine del progetto.

Esempio da leggere lentamente

Questo esempio serve a ragionare, non a incollare codice senza capire:

function verificaStrumentoPrestabile(strumento) {
  if (strumento.stato === "guasto") {
    throw new Error("STRUMENTO_GUASTO_NON_PRESTABILE");
  }
  if (strumento.stato === "in_prestito") {
    throw new Error("STRUMENTO_GIA_IN_PRESTITO");
  }
}

Leggilo chiedendoti che cosa cambierebbe se domani sostituissimo la pagina web con una CLI, oppure localStorage con un’API. Se l’esempio continua ad avere senso senza riscrivere tutto, il confine è probabilmente buono. Se invece un dettaglio tecnico si propaga in molti file, il progetto sta tornando fragile.

Prova di comprensione

Prima di chiudere la lezione, rispondi per iscritto a queste domande:

• Qual è la responsabilità principale trattata in questa lezione?
• In quale livello del progetto dovrebbe stare?
• Quale errore faresti se cercassi la soluzione più veloce?
• Quale piccolo test, controllo manuale o esempio dimostra che hai capito?
• Che cosa deve restare facile da cambiare dopo questa lezione?

Una risposta accettabile non deve essere lunga. Deve però usare parole concrete del Registro: strumento, prestito, stato, archivio, caso d’uso, messaggio, test.

Risultato atteso

Alla fine devono essere vere queste frasi:

in_manutenzione e uno stato valido.
Uno strumento in manutenzione non puo essere prestato.
La regola e nel dominio.
La UI mostra un messaggio comprensibile.
Esiste uno scenario o test che verifica il comportamento.

Variante avanzata

Se hai tempo, aggiungi una funzione:

export function mandaInManutenzione(strumento) {
  return {
    ...strumento,
    stato: StatoStrumento.IN_MANUTENZIONE,
  };
}

Poi chiediti:

Da quali stati posso andare in manutenzione?

Possibili risposte:

• da disponibile;
• da guasto;
• da in prestito solo alla chiusura del prestito, se lo strumento torna con problemi.

Non serve implementare tutto subito. Basta annotare le transizioni.

Cosa produrre

Alla fine della micro-sfida devi avere:

• StatoStrumento.IN_MANUTENZIONE;
• controllo di prestabilita aggiornato;
• scenario o test;
• messaggio utente;
• documentazione dello stato;
• breve nota sulle transizioni possibili.

Controllo finale del modulo

Il Modulo 6 e completato quando puoi rispondere si:

• ho un modello minimo di Strumento;
• ho un modello minimo di Prestito;
• ho stati dello strumento chiari;
• ho identificato invarianti importanti;
• le regole principali non stanno nella UI;
• gli errori di dominio hanno nomi comprensibili;
• so spiegare perche uno stato o una regola appartiene al dominio.

Nel prossimo modulo useremo questo dominio per costruire i casi d’uso: registrare strumenti, cercare, prestare, chiudere prestiti e aprire segnalazioni di guasto.