Errori di dominio comprensibili

Quando una regola di dominio viene violata, il sistema deve reagire.

Non basta fallire con un errore tecnico:

Cannot read properties of undefined

E non basta mostrare messaggi scritti a caso in ogni punto del codice.

Vogliamo errori con nomi chiari.

Obiettivo

Alla fine devi avere:

• una lista di errori di dominio;
• codici errore coerenti;
• una funzione o tabella che li trasforma in messaggi utente;
• esempi di errori tecnici da non mostrare direttamente.

Che cosa e un errore di dominio

Un errore di dominio nasce quando una regola del problema viene violata.

Esempi:

STRUMENTO_NON_TROVATO
STRUMENTO_NON_PRESTABILE
STRUMENTO_GUASTO_NON_PRESTABILE
STRUMENTO_GIA_IN_PRESTITO
NOME_STRUMENTO_OBBLIGATORIO
STATO_STRUMENTO_NON_VALIDO
PRESTITO_GIA_CHIUSO
ASSEGNATARIO_PRESTITO_OBBLIGATORIO

Questi errori parlano del Registro del laboratorio.

Non parlano di HTML, database, fetch, JSON o localStorage.

Errore tecnico e errore di dominio

Errore tecnico:

Cannot read properties of undefined

Possibile errore di dominio:

STRUMENTO_NON_TROVATO

Messaggio utente:

Strumento non trovato.

Sono tre livelli diversi.

Mescolarli crea confusione:

• l’utente vede messaggi incomprensibili;
• il dominio decide testi di interfaccia;
• i test dipendono da frasi lunghe;
• cambiare un messaggio rompe controlli inutilmente.

Usare codici errore

Una soluzione semplice e usare codici errore.

File:

src/domain/erroriDominio.js

Codice:

export const ErroriDominio = {
  STRUMENTO_NON_TROVATO: "STRUMENTO_NON_TROVATO",
  STRUMENTO_NON_PRESTABILE: "STRUMENTO_NON_PRESTABILE",
  STRUMENTO_GIA_IN_PRESTITO: "STRUMENTO_GIA_IN_PRESTITO",
  NOME_STRUMENTO_OBBLIGATORIO: "NOME_STRUMENTO_OBBLIGATORIO",
  STATO_STRUMENTO_NON_VALIDO: "STATO_STRUMENTO_NON_VALIDO",
  PRESTITO_GIA_CHIUSO: "PRESTITO_GIA_CHIUSO",
};

Poi:

throw new Error(ErroriDominio.STRUMENTO_NON_PRESTABILE);

Non e l’unico modo possibile. In progetti piu grandi potremmo usare classi di errore o oggetti risultato.

Per questo laboratorio i codici sono abbastanza chiari.

Mappare errori in messaggi

La UI puo trasformare il codice in testo:

const messaggiErrore = {
  STRUMENTO_NON_TROVATO: "Strumento non trovato.",
  STRUMENTO_NON_PRESTABILE: "Questo strumento non puo essere prestato.",
  STRUMENTO_GIA_IN_PRESTITO: "Questo strumento risulta gia in prestito.",
  NOME_STRUMENTO_OBBLIGATORIO: "Inserisci il nome dello strumento.",
  STATO_STRUMENTO_NON_VALIDO: "Lo stato dello strumento non e valido.",
  PRESTITO_GIA_CHIUSO: "Questo prestito e gia stato chiuso.",
};

export function messaggioPerErrore(errore) {
  return messaggiErrore[errore.message] ?? "Operazione non riuscita.";
}

Questa funzione puo stare nella presentation o in un modulo dedicato ai messaggi.

Non deve stare nel dominio se contiene testi pensati per l’utente.

Esempio completo

Dominio:

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

  if (strumento.stato !== "disponibile") {
    throw new Error("STRUMENTO_NON_PRESTABILE");
  }
}

Presentation:

try {
  registraPrestito(input);
  mostraMessaggio("Prestito registrato.");
} catch (errore) {
  mostraMessaggio(messaggioPerErrore(errore));
}

Il dominio non sa dove viene mostrato il messaggio.

La presentation non riscrive la regola.

Non nascondere tutto in un errore generico

Evita:

throw new Error("ERRORE");

Oppure:

throw new Error("Operazione non valida");

Sono troppo generici.

Un buon codice errore aiuta a capire:

• quale regola e stata violata;
• quale test scrivere;
• quale messaggio mostrare;
• quale parte del dominio sta parlando.

Quando usare messaggi diretti

Per piccoli esercizi puo sembrare piu semplice scrivere:

throw new Error("Uno strumento guasto non puo essere prestato.");

Non e un disastro, ma ha un limite: il testo diventa parte del dominio.

Se poi vogliamo cambiare il messaggio per l’utente, dobbiamo toccare il dominio.

Nel corso preferiamo codici errore per allenare la separazione.

Esercizio

Costruisci una tabella:

| Regola violata | Codice errore | Messaggio utente |
| --- | --- | --- |
| Strumento non trovato | STRUMENTO_NON_TROVATO | Strumento non trovato. |
| Strumento guasto | STRUMENTO_GUASTO_NON_PRESTABILE | Questo strumento e guasto e non puo essere prestato. |

Aggiungi almeno otto righe.

Poi scegli due errori tecnici e trasformali in errori comprensibili.

Esempio:

Cannot read properties of undefined
-> STRUMENTO_NON_TROVATO
-> Strumento non trovato.

Cosa produrre

Alla fine della lezione devi avere:

• lista di errori di dominio;
• file o sezione erroriDominio;
• tabella codice errore -> messaggio utente;
• almeno due esempi di trasformazione da errore tecnico a messaggio;
• regole aggiornate per usare codici coerenti.

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 errori di dominio comprensibili, il punto centrale è questo: Gestire errori significa distinguere origine, significato e messaggio. Un errore di dominio non è uguale a un campo mancante o a un salvataggio fallito.

Il rischio tipico è mostrare all’utente il messaggio tecnico grezzo oppure nascondere tutti gli errori dietro una frase generica. L’utente deve sapere cosa fare; chi mantiene il sistema deve poter capire cosa è successo. 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. Classifica l’errore: input, dominio, applicazione o infrastruttura.
4. Scrivi un messaggio utente breve e utile.
5. Conserva il dettaglio tecnico solo dove serve.
6. Testa almeno uno scenario di errore.
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:

const messaggi = {
  STRUMENTO_NON_TROVATO: "Strumento non trovato.",
  STRUMENTO_GUASTO_NON_PRESTABILE: "Questo strumento è guasto e non può essere prestato.",
  ARCHIVIO_NON_DISPONIBILE: "Non riesco a salvare i dati. Riprova tra poco."
};

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:

• so distinguere errore tecnico, errore di dominio e messaggio utente;
• uso codici errore coerenti;
• il dominio non contiene testi di UI sparsi;
• la UI non contiene le regole;
• posso testare gli errori del dominio.

Nella prossima lezione chiudiamo il modulo con una micro-sfida: aggiungere lo stato in_manutenzione.