ApriSegnalazioneGuasto: cambiare stato e registrare motivo

Uno strumento può smettere di funzionare.

Il registro deve permettere di segnalarlo.

Il caso d’uso:

ApriSegnalazioneGuasto

serve a registrare il problema e a cambiare lo stato dello strumento.

Non basta scrivere una nota da qualche parte. Se lo strumento e guasto, non deve essere prestato.

Obiettivo

Alla fine devi avere un caso d’uso che:

• riceve id dello strumento, descrizione, data e autore della segnalazione;
• trova lo strumento;
• crea una segnalazione;
• cambia lo stato dello strumento in guasto;
• salva segnalazione e strumento;
• restituisce il risultato.

Il comando

const comando = {
  segnalazioneId: "g-001",
  strumentoId: "s-001",
  descrizione: "Il proiettore si accende ma non mostra immagine",
  segnalatoDa: "Prof. Bianchi",
  apertaIl: "2026-05-09",
};

Questo comando puo arrivare da un form.

Il caso d’uso non deve sapere nulla del form.

Modello minimo di segnalazione

Se non lo abbiamo ancora creato, possiamo aggiungere:

src/domain/segnalazioneGuasto.js

Codice:

export function creaSegnalazioneGuasto({
  id,
  strumentoId,
  descrizione,
  segnalatoDa,
  apertaIl,
}) {
  if (!id || id.trim() === "") {
    throw new Error("ID_SEGNALAZIONE_OBBLIGATORIO");
  }

  if (!strumentoId || strumentoId.trim() === "") {
    throw new Error("STRUMENTO_SEGNALAZIONE_OBBLIGATORIO");
  }

  if (!descrizione || descrizione.trim() === "") {
    throw new Error("DESCRIZIONE_GUASTO_OBBLIGATORIA");
  }

  return {
    id: id.trim(),
    strumentoId: strumentoId.trim(),
    descrizione: descrizione.trim(),
    segnalatoDa: segnalatoDa?.trim() || "non indicato",
    apertaIl,
    stato: "aperta",
  };
}

Questa e una modellazione minima.

Non serve creare subito un sistema completo di ticket.

Cambiare stato allo strumento

Quando apriamo una segnalazione di guasto, lo strumento deve diventare:

guasto

Esempio:

const strumentoAggiornato = {
  ...strumento,
  stato: StatoStrumento.GUASTO,
};

Questo cambio e una conseguenza del caso d’uso.

Il significato dello stato resta nel dominio.

Implementazione

File:

src/application/apriSegnalazioneGuasto.js

Codice:

import { StatoStrumento } from "../domain/statoStrumento.js";
import { creaSegnalazioneGuasto } from "../domain/segnalazioneGuasto.js";

export function creaApriSegnalazioneGuasto({
  archivioStrumenti,
  archivioSegnalazioniGuasto,
}) {
  return function apriSegnalazioneGuasto(comando) {
    const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);

    if (!strumento) {
      throw new Error("STRUMENTO_NON_TROVATO");
    }

    const segnalazione = creaSegnalazioneGuasto({
      id: comando.segnalazioneId,
      strumentoId: strumento.id,
      descrizione: comando.descrizione,
      segnalatoDa: comando.segnalatoDa,
      apertaIl: comando.apertaIl,
    });

    const strumentoAggiornato = {
      ...strumento,
      stato: StatoStrumento.GUASTO,
    };

    archivioSegnalazioniGuasto.salva(segnalazione);
    archivioStrumenti.salva(strumentoAggiornato);

    return {
      segnalazione,
      strumento: strumentoAggiornato,
    };
  };
}

Il caso d’uso non mostra messaggi.

La UI potra mostrare:

Segnalazione aperta. Lo strumento e stato segnato come guasto.

Casi da chiarire

Alcune domande possono restare aperte:

Si puo aprire una segnalazione su uno strumento gia guasto?
Si possono avere piu segnalazioni aperte sullo stesso strumento?
Chi puo chiudere una segnalazione?
Guasto e manutenzione sono stati alternativi o successivi?

Non dobbiamo risolvere tutto ora.

Annotiamo le domande per i moduli successivi.

Scenari

## Apertura valida

Dato uno strumento disponibile,
quando apro una segnalazione di guasto,
allora viene creata una segnalazione e lo strumento diventa guasto.

## Strumento non trovato

Dato uno strumentoId inesistente,
quando apro una segnalazione,
allora ottengo STRUMENTO_NON_TROVATO.

## Descrizione mancante

Dato un comando senza descrizione,
quando apro una segnalazione,
allora ottengo DESCRIZIONE_GUASTO_OBBLIGATORIA.

Esercizio

Scrivi tre segnalazioni realistiche:

• proiettore non mostra immagine;
• kit sensori incompleto;
• notebook non si accende.

Per ciascuna indica:

• strumentoId;
• descrizione;
• segnalatoDa;
• data;
• stato finale dello strumento.

Poi scrivi un caso non valido con descrizione vuota.

Cosa produrre

Alla fine della lezione devi avere:

• file src/application/apriSegnalazioneGuasto.js;
• modello minimo SegnalazioneGuasto o scheda equivalente;
• cambio stato dello strumento a guasto;
• almeno tre scenari;
• elenco di domande da chiarire;
• nessuna logica di guasto dentro la UI.

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 apriSegnalazioneGuasto: cambiare stato e registrare motivo, il punto centrale è questo: Un caso d’uso coordina un’operazione completa: riceve un comando, legge ciò che serve, applica regole, salva il risultato e restituisce un esito.

Il rischio tipico è far diventare il caso d’uso una seconda UI o un secondo database. Deve coordinare, non mostrare HTML e non conoscere dettagli tecnici di salvataggio. 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 è sufficiente per alternare spiegazione, modifica guidata e revisione. 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. Definisci input e output del caso d’uso.
4. Leggi i dati attraverso un archivio o una dipendenza esplicita.
5. Chiama le regole del dominio.
6. Salva il risultato senza sapere come funziona la persistenza concreta.
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 registraPrestito(comando, archivioStrumenti, archivioPrestiti) {
  const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);
  verificaStrumentoPrestabile(strumento);
  const prestito = apriPrestito(strumento.id, comando.nomePersona);
  archivioPrestiti.salva(prestito);
  archivioStrumenti.salva({ ...strumento, stato: "in_prestito" });
  return 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.

Controllo finale

La lezione e completata quando puoi rispondere si:

• una segnalazione ha descrizione e strumento collegato;
• aprire una segnalazione cambia lo stato dello strumento;
• lo strumento guasto non sara prestabile;
• il caso d’uso salva segnalazione e strumento;
• la UI mostra messaggi, ma non contiene la regola.

Nella prossima lezione scriviamo un caso d’uso senza UI.