Differenza tra regola di dominio e coordinamento applicativo

Nel modulo precedente abbiamo costruito regole di dominio.

Ora dobbiamo usarle dentro operazioni complete.

La distinzione e questa:

Il dominio decide cosa e valido.
Il caso d'uso coordina cosa deve succedere.

Se questa distinzione non e chiara, i casi d’uso diventano file pieni di regole duplicate oppure il dominio diventa un contenitore che prova a fare tutto.

Obiettivo

Alla fine devi saper classificare una responsabilita come:

• regola di dominio;
• coordinamento applicativo;
• UI;
• infrastruttura.

E devi saper spiegare perche.

Esempio: registrare un prestito

Requisito:

Il docente puo registrare un prestito per uno strumento disponibile.

Regole di dominio:

• uno strumento guasto non puo essere prestato;
• uno strumento in manutenzione non puo essere prestato;
• uno strumento gia in prestito non puo essere prestato di nuovo;
• un prestito deve avere un assegnatario;
• un prestito deve riferirsi a uno strumento.

Coordinamento applicativo:

• leggere lo strumento dall’archivio;
• leggere i prestiti aperti;
• chiamare le regole del dominio;
• creare il nuovo prestito;
• aggiornare lo stato dello strumento;
• salvare prestito e strumento.

La UI raccoglie input.

L’infrastruttura salva e legge dati.

Regola di dominio

Una regola di dominio resta vera anche se cambia il modo in cui usiamo il sistema.

Esempio:

Solo uno strumento disponibile puo essere prestato.

Questa regola vale con:

• pagina web;
• CLI;
• test automatico;
• localStorage;
• JSON;
• database;
• API.

Quindi deve stare nel dominio.

Coordinamento applicativo

Il coordinamento applicativo descrive i passi dell’operazione.

Esempio:

Per registrare un prestito devo recuperare lo strumento, verificare le regole, creare il prestito e salvare le modifiche.

Questa frase non e una regola del laboratorio. E il flusso applicativo.

Sta nel caso d’uso.

Cattivo segnale: caso d’uso con troppe regole scritte a mano

Esempio fragile:

export function registraPrestito(comando) {
  const strumento = strumenti.find((item) => item.id === comando.strumentoId);

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

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

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

  // crea e salva
}

Il caso d’uso sta iniziando a riscrivere regole del dominio.

Meglio:

export function registraPrestito(comando) {
  const strumento = archivioStrumenti.trovaPerId(comando.strumentoId);

  verificaStrumentoPrestabile(strumento);

  // crea e salva
}

Il caso d’uso sa quando chiamare la regola.

Il dominio sa che cosa rende lo strumento prestabile.

Cattivo segnale opposto: dominio che salva dati

Anche questo e fragile:

export function prestaStrumento(strumento, prestito) {
  if (strumento.stato !== "disponibile") {
    throw new Error("STRUMENTO_NON_PRESTABILE");
  }

  localStorage.setItem("prestito", JSON.stringify(prestito));

  return {
    ...strumento,
    stato: "in_prestito",
  };
}

Qui il dominio conosce localStorage.

Il dominio non deve sapere dove finiscono i dati.

Il salvataggio e infrastruttura, usata dal caso d’uso.

Tabella pratica

Responsabilita	Dove sta
Uno strumento guasto non puo essere prestato	Domain
Trovare lo strumento prima di registrare il prestito	Application
Leggere il valore di un input HTML	Presentation
Salvare strumenti in localStorage	Infrastructure
Creare un prestito valido	Domain
Salvare prestito e strumento aggiornati	Application che usa Infrastructure
Mostrare “Prestito registrato”	Presentation

Questa tabella non serve a fare teoria. Serve a decidere dove scrivere codice.

Schema del flusso

UI
  raccoglie input
  chiama il caso d'uso

Application
  coordina l'operazione
  chiama dominio
  usa archivi

Domain
  applica regole
  crea oggetti validi

Infrastructure
  legge e salva dati

Le frecce non devono diventare una gabbia dogmatica, ma una guida pratica.

Esercizio

Classifica queste frasi:

1. Cerca in archivio lo strumento richiesto.
2. Uno strumento deve avere uno stato valido.
3. Mostra un errore sotto al form.
4. Se il prestito e chiuso, non puo essere chiuso di nuovo.
5. Salva i prestiti in JSON.
6. Dopo la chiusura del prestito, aggiorna lo stato dello strumento.
7. Genera un messaggio utente per STRUMENTO_NON_PRESTABILE.

Scrivi:

Domain
Application
Presentation
Infrastructure

Possibile soluzione:

1. Application
2. Domain
3. Presentation
4. Domain
5. Infrastructure
6. Application
7. Presentation

Cosa produrre

Alla fine della lezione devi avere:

• una tabella responsabilita -> livello;
• almeno tre regole di dominio estratte dai casi d’uso;
• almeno tre passaggi di coordinamento applicativo;
• almeno due esempi di cose che non devono stare nel caso d’uso;
• almeno due esempi di cose che non devono stare nel dominio.

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 differenza tra regola di dominio e coordinamento applicativo, 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:

• so distinguere regola e coordinamento;
• il caso d’uso non contiene dettagli di UI;
• il dominio non salva dati;
• la UI non decide le regole importanti;
• posso spiegare dove metterei una nuova responsabilita.

Nella prossima lezione scriviamo il primo caso d’uso: RegistraStrumento.