Controllo diagramma architetturale

Questa lezione appartiene al Modulo 23 — Revisione finale.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione verifichi che il diagramma architetturale del tuo progetto corrisponda al codice effettivamente scritto — non all’idea originale, ma all’implementazione reale.

Obiettivo della lezione

Confrontare il diagramma architetturale esistente con il codice del Registro e correggere le discrepanze. Un diagramma che non corrisponde al codice è peggio di nessun diagramma — inganna chi lo legge.

Alla fine devi avere: un diagramma aggiornato che riflette la struttura reale del Registro, con i quattro livelli, le dipendenze tra loro e i componenti principali.

Cosa deve mostrare un diagramma corretto

Un diagramma architetturale del Registro deve mostrare almeno:

• i quattro livelli: domain, application, infrastructure, presentation
• il flusso delle dipendenze (presentation → application → domain, infrastructure → domain)
• i componenti principali per livello (Strumento, ApriPrestito, archivioStrumentiLocalStorage, UI)
• il punto di composizione (main.js)

Non deve essere UML preciso — un diagramma ASCII o Mermaid è sufficiente.

Come verificare la corrispondenza con il codice

Per ogni elemento nel diagramma, apri il file corrispondente nel progetto e verifica che esista davvero. Per ogni dipendenza disegnata, controlla che ci sia un import corrispondente nel codice. Se il diagramma mostra una freccia da presentation a domain, verifica che non esista un import diretto — la freccia dovrebbe passare per application.

Procedura guidata

1. Apri il diagramma esistente (nel README o in un file separato).
2. Apri l’esplora-file del progetto.
3. Per ogni blocco nel diagramma, verifica che il file o la cartella esista.
4. Per ogni freccia nel diagramma, verifica che ci sia un import corrispondente.
5. Cerca dipendenze nel codice che non appaiono nel diagramma.
6. Aggiorna il diagramma per riflettere lo stato reale.

Attività in classe

Compila questa scheda durante la verifica:

## Verifica diagramma

Elemento nel diagramma: domain/strumento.js
Esiste nel codice? sì / no
Dipendenze mostrate nel diagramma: (elenco)
Dipendenze reali negli import: (elenco)
Discrepanza trovata: sì / no — quale:

Elemento: application/apriPrestito.js
Esiste nel codice? sì / no
Dipendenze mostrate: (elenco)
Dipendenze reali: (elenco)
Discrepanza:

[ripeti per ogni componente principale]

Componenti nel codice non rappresentati nel diagramma:
Componenti nel diagramma non trovati nel codice:

Spiegazione guidata per studiare

Un diagramma architetturale diventa obsoleto quando il codice cambia ma il diagramma no. È la “deriva del documento”: la documentazione descrive un progetto passato, non quello attuale. Chi legge il diagramma pensa di capire il sistema ma si trova davanti a qualcosa di diverso.

Verificare il diagramma significa rileggere il codice con un occhio specifico: “questa dipendenza che ho disegnato esiste davvero? Quella che non ho disegnato sta violando l’architettura?”. Spesso durante questa verifica si scoprono violazioni architetturali — presentation che importa direttamente da domain, caso d’uso che conosce localStorage.

Passo per passo nel progetto

1. Se non hai ancora un diagramma, creane uno in formato Mermaid nel README:

## Architettura del Registro

graph TD
  subgraph Presentation
    UI[azioni.js / main.js]
  end
  subgraph Application
    AP[apriPrestito.js]
    CP[chiudiPrestito.js]
    SG[segnalaGuasto.js]
    CS[cercaStrumenti.js]
    RS[registraStrumento.js]
  end
  subgraph Domain
    STR[strumento.js]
    PRE[prestito.js]
  end
  subgraph Infrastructure
    ASL[archivioStrumentiLocalStorage.js]
    APL[archivioPrestitiLocalStorage.js]
  end
  MAIN[main.js] --> UI
  MAIN --> AP
  MAIN --> ASL
  UI --> AP
  UI --> CP
  UI --> SG
  AP --> STR
  AP --> ASL
  CP --> APL
  ASL --> STR

1. Apri ogni file dell’applicazione e leggi gli import. Confronta con il diagramma.

# verifica rapida: cerca tutti gli import nel progetto
grep -r "^import" src/ --include="*.js"

1. Cerca violazioni architetturali — import che non dovrebbero esserci:

# cerca import di localStorage nel dominio — non dovrebbero esserci
grep -r "localStorage" src/domain/ --include="*.js"

# cerca import da infrastructure nella presentation che bypassano application
grep -r "import.*infrastructure" src/presentation/ --include="*.js"

1. Per ogni discrepanza trovata, decidi: correggi il codice o aggiorna il diagramma?

   • Se il codice è sbagliato (viola l’architettura) → correggi il codice
   • Se il diagramma è vecchio (il codice è cambiato correttamente) → aggiorna il diagramma

2. Verifica che il diagramma mostri il flusso corretto delle dipendenze:

Flusso corretto:
presentation → application → domain
infrastructure → domain (implementa le interfacce)
main.js compone tutto

NON corretto:
presentation → domain (saltando application)
domain → infrastructure (il dominio non deve conoscere la persistenza)
application → DOM o localStorage (i casi d'uso non toccano UI o storage)

Esempio — diagramma ASCII semplice

Se non vuoi usare Mermaid, un diagramma ASCII nel README è ugualmente valido:

## Architettura del Registro del laboratorio

┌─────────────────────────────────────────────────┐
│ PRESENTATION (main.js, azioni.js)               │
│  └─ gestori eventi → chiama casi d'uso          │
└────────────────────┬────────────────────────────┘
                     │ chiama
┌────────────────────▼────────────────────────────┐
│ APPLICATION (apriPrestito, chiudiPrestito, ...)  │
│  └─ coordina operazioni, non contiene regole     │
└──────────┬─────────────────────────┬────────────┘
           │ usa                     │ delega a
┌──────────▼────────┐   ┌────────────▼───────────┐
│ DOMAIN            │   │ INFRASTRUCTURE          │
│ (strumento.js,    │   │ (archivioLocalStorage)  │
│  prestito.js)     │   │  └─ legge/scrive LS     │
└───────────────────┘   └────────────────────────┘
           ▲
           │ usa modelli del dominio
└──────────┴─────────────────────────────────────┘

MAIN.JS — punto di composizione: importa tutto, collega tutto

Prova di comprensione

Rispondi per iscritto:

• Hai trovato discrepanze tra il diagramma e il codice? Quali?
• Hai trovato import nel codice che violano l’architettura? Dove?
• Perché un diagramma obsoleto è peggio di nessun diagramma?
• Cosa aggiunge il diagramma che il codice da solo non comunica facilmente?

Errori da evitare

• aggiornare il diagramma senza rileggere il codice reale;
• disegnare il diagramma dell’architettura ideale invece di quella reale;
• usare nomi nel diagramma che non corrispondono ai file effettivi;
• non mostrare main.js come punto di composizione.

Prodotto da consegnare

Il diagramma aggiornato (Mermaid o ASCII) nel README, coerente con il codice reale. Come verifica: mostra il diagramma e il codice fianco a fianco al docente, indicando quale file corrisponde a quale blocco.

Checklist di chiusura

• ogni blocco nel diagramma corrisponde a un file o una cartella reale;
• le frecce nel diagramma corrispondono agli import nel codice;
• non ci sono violazioni architetturali nel codice (domain importa infrastructure, ecc.);
• main.js è mostrato come punto di composizione;
• il diagramma è leggibile senza spiegazioni aggiuntive.

Risultato atteso

Ho verificato il diagramma confrontandolo con il codice reale.
Discrepanze trovate: [descrizione].
Correzioni applicate: [al codice / al diagramma].
Il diagramma aggiornato è nel README e corrisponde all'implementazione.
Un nuovo lettore del progetto può orientarsi guardando il diagramma.