ChiudiPrestito: completare il ciclo di vita

Un prestito non finisce da solo.

Va chiuso.

Il caso d’uso:

ChiudiPrestito

serve a registrare la restituzione di uno strumento.

Non e solo un cambio di campo da aperto a chiuso. Deve coordinare anche lo stato finale dello strumento.

Obiettivo

Alla fine devi avere un caso d’uso che:

• riceve l’id del prestito;
• trova il prestito;
• verifica che sia aperto;
• trova lo strumento collegato;
• chiude il prestito;
• imposta lo stato finale dello strumento;
• salva prestito e strumento;
• restituisce il risultato.

Il comando

const comando = {
  prestitoId: "p-001",
  chiusoIl: "2026-05-10",
  statoFinaleStrumento: "disponibile",
  note: "Restituito completo",
};

Il campo statoFinaleStrumento e importante.

Quando uno strumento torna, non sempre torna disponibile.

Puo tornare:

• disponibile;
• guasto;
• in manutenzione.

Perche non basta chiudere il prestito

Se chiudiamo solo il prestito:

prestito.stato = "chiuso";

ma lasciamo lo strumento:

strumento.stato = "in_prestito";

il sistema resta incoerente.

Il prestito e chiuso, ma lo strumento sembra ancora fuori.

ChiudiPrestito deve coordinare entrambi.

Passo 1: trovare il prestito

const prestito = archivioPrestiti.trovaPerId(comando.prestitoId);

if (!prestito) {
  throw new Error("PRESTITO_NON_TROVATO");
}

Questo e coordinamento applicativo.

Passo 2: chiudere il prestito nel dominio

Nel dominio abbiamo:

const prestitoChiuso = chiudiPrestito(prestito, comando.chiusoIl);

Se il prestito e gia chiuso, la funzione deve lanciare:

PRESTITO_GIA_CHIUSO

La regola resta nel dominio.

Passo 3: trovare lo strumento

const strumento = archivioStrumenti.trovaPerId(prestito.strumentoId);

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

Questo caso e raro, ma possibile se i dati sono incoerenti.

Il caso d’uso deve gestirlo con un errore chiaro.

Passo 4: impostare lo stato finale

const strumentoAggiornato = {
  ...strumento,
  stato: comando.statoFinaleStrumento,
};

Qui dobbiamo stare attenti.

Lo stato finale deve essere uno stato valido.

Possiamo usare:

if (!isStatoStrumentoValido(comando.statoFinaleStrumento)) {
  throw new Error("STATO_STRUMENTO_NON_VALIDO");
}

Questa validazione si appoggia al dominio.

Implementazione completa

import { chiudiPrestito } from "../domain/prestito.js";
import { isStatoStrumentoValido } from "../domain/statoStrumento.js";

export function creaChiudiPrestito({
  archivioPrestiti,
  archivioStrumenti,
}) {
  return function chiudiPrestitoCasoUso(comando) {
    const prestito = archivioPrestiti.trovaPerId(comando.prestitoId);

    if (!prestito) {
      throw new Error("PRESTITO_NON_TROVATO");
    }

    if (!isStatoStrumentoValido(comando.statoFinaleStrumento)) {
      throw new Error("STATO_STRUMENTO_NON_VALIDO");
    }

    const strumento = archivioStrumenti.trovaPerId(prestito.strumentoId);

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

    const prestitoChiuso = chiudiPrestito(prestito, comando.chiusoIl);

    const strumentoAggiornato = {
      ...strumento,
      stato: comando.statoFinaleStrumento,
    };

    archivioPrestiti.salva(prestitoChiuso);
    archivioStrumenti.salva(strumentoAggiornato);

    return {
      prestito: prestitoChiuso,
      strumento: strumentoAggiornato,
    };
  };
}

Il nome chiudiPrestitoCasoUso evita conflitto con la funzione di dominio chiudiPrestito.

In un progetto reale puoi scegliere nomi piu eleganti, ma qui la chiarezza conta di piu.

Scenari fondamentali

## Chiusura valida

Dato un prestito aperto,
quando lo chiudo con stato finale disponibile,
allora il prestito diventa chiuso e lo strumento diventa disponibile.

## Prestito gia chiuso

Dato un prestito gia chiuso,
quando provo a chiuderlo,
allora ottengo PRESTITO_GIA_CHIUSO.

## Stato finale guasto

Dato un prestito aperto,
quando lo chiudo indicando stato finale guasto,
allora il prestito diventa chiuso e lo strumento diventa guasto.

## Stato finale non valido

Dato uno stato finale non riconosciuto,
quando chiudo il prestito,
allora ottengo STATO_STRUMENTO_NON_VALIDO.

Dove sta la scelta dello stato finale

La UI puo offrire una scelta:

disponibile
guasto
in_manutenzione

Ma la validazione dello stato non deve dipendere solo dalla select.

Il caso d’uso deve controllare che lo stato sia valido.

Il dominio definisce quali stati esistono.

Esercizio

Parti da:

const prestito = {
  id: "p-001",
  strumentoId: "s-001",
  stato: "aperto",
};

const strumento = {
  id: "s-001",
  nome: "Kit sensori",
  stato: "in_prestito",
};

Scrivi cosa succede quando:

• il kit torna completo;
• il kit torna con un pezzo mancante;
• il prestito e gia chiuso;
• lo stato finale e rotto, che non e uno stato valido.

Cosa produrre

Alla fine della lezione devi avere:

• file src/application/chiudiPrestito.js;
• caso d’uso ChiudiPrestito;
• almeno quattro scenari;
• aggiornamento coordinato di prestito e strumento;
• controllo sullo stato finale;
• nessuna regola di chiusura nella 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 chiudiPrestito: completare il ciclo di vita, 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 chiudere un prestito aperto;
• non posso chiudere due volte lo stesso prestito;
• lo stato dello strumento viene aggiornato;
• lo stato finale e validato;
• il caso d’uso e testabile senza browser.

Nella prossima lezione apriamo una segnalazione di guasto.