# DOMUSCAN — Definizione delle metriche di qualità

> Come si misura DOMUSCAN durante i collaudi e il pilota. Riferimenti: [CRITERI_COLLAUDO.md](CRITERI_COLLAUDO.md), [PIANO_FASE_0.md](PIANI_DI_IMPLEMENTAZIONE/PIANO_FASE_0.md) §0.6, [DECISIONI.md](DECISIONI.md) (D4).

## Regole generali

- **Base di confronto:** ogni metrica si calcola sul **corpus pilota** confrontando l'output del sistema con la **ground truth** etichettata in Fase 0 (§0.5). Il corpus usato per misurare non deve essere stato usato per tarare le regole sugli stessi casi: si tiene da parte una porzione di verifica.
- **Separazione per formato:** le metriche di estrazione si riportano separatamente per XML FatturaPA, PDF nativo e PDF scansionato. Non si aggregano formati diversi in un unico numero.
- **Normalizzazione prima del confronto:**
  - importi al centesimo, senza separatori delle migliaia;
  - date in formato ISO `AAAA-MM-GG`;
  - partite IVA senza prefisso `IT` e senza spazi;
  - testi in minuscolo, con spazi compattati.
- **Riproducibilità:** ogni misura riporta la data, la versione del codice, la versione del corpus e della ground truth, e il comando o la query usati per calcolarla.
- **Soglie:** le soglie **assolute** (marcate 🔒) non sono negoziabili. Le altre si fissano dopo la baseline e i prototipi della Fase 0 e vanno approvate dal committente.

## Riepilogo

| # | Metrica | Soglia | Quando si misura |
|---|---|---|---|
| M1 | Associazioni automatiche errate | 🔒 **0** | SAL 2, SAL 3, pilota |
| M2 | Copertura automatica | Da fissare dopo la baseline | SAL 2, pilota |
| M3 | Qualità delle proposte (livelli C/D) | Da fissare | SAL 2 |
| M4 | Accuratezza di estrazione | Da fissare dopo P1/P2 | SAL 1 (fatture), SAL 2 (consuntivo) |
| M5 | Ritrovamento dei token in stampa | 🔒 **100%** dei token leggibili | Fase 0 (P1/P4), SAL 2 |
| M6 | Tempo operatore per 100 fatture | Inferiore alla baseline manuale | Fase 0 (baseline), SAL 3, pilota |
| M7 | Integrità del PDF arricchito | 🔒 **100%** | SAL 2, SAL 3 |
| M8 | Rilevazione delle alterazioni | 🔒 **100%** | SAL 1, SAL 3 |
| M9 | Accessi non autorizzati riusciti | 🔒 **0** | SAL 3, ogni rilascio |
| M10 | Duplicati da ripetizione | 🔒 **0** | SAL 1, SAL 2, SAL 3 |

---

## M1 — Associazioni automatiche errate 🔒

- **Definizione:** numero di associazioni riga ↔ documento confermate **senza intervento umano** (livelli A e B di D4) che non coincidono con la ground truth, per documento sbagliato, importo allocato sbagliato o condominio sbagliato.
- **Formula:** `M1 = conteggio(associazioni automatiche ∉ ground truth)`
- **Soglia:** **0**. Un solo caso fa fallire il collaudo: per DOMUSCAN la precisione prevale sulla copertura.
- **Nota:** le associazioni confermate da un operatore non contano qui; si misurano in M3.

## M2 — Copertura automatica

- **Definizione:** quota di righe del rendiconto che hanno un documento nella ground truth e che il sistema associa correttamente senza intervento umano.
- **Formula:** `M2 = associazioni automatiche corrette / righe con documento nella ground truth`
- **Esclusioni:** le righe che nella ground truth non hanno un documento fiscale (es. quote, giroconti) sono escluse dal denominatore e riportate a parte.
- **Lettura:** una copertura bassa con M1 = 0 è accettabile. Indica quanto lavoro resta all'operatore, non un errore.

## M3 — Qualità delle proposte (livelli C/D)

- **Definizione:** per le righe non associate automaticamente, misura quanto le proposte mostrate in Review Console aiutano l'operatore.
- **Formule:**
  - `M3a (precisione in prima posizione) = righe in cui il primo candidato è quello corretto / righe con almeno un candidato`
  - `M3b (richiamo) = righe in cui il documento corretto compare tra i candidati / righe in revisione che hanno un documento nella ground truth`
- **Lettura:** M3 non autorizza mai una pubblicazione (D4). Serve a ridurre il tempo operatore (M6).

## M4 — Accuratezza di estrazione

- **Definizione:** quota di campi estratti correttamente rispetto alla ground truth, per campo e per formato.
- **Campi delle fatture:** partita IVA/CF del fornitore, partita IVA/CF del destinatario, tipo documento, numero, data, imponibile, IVA, totale.
- **Campi delle righe del consuntivo:** testo della voce, importo, pagina, token (se presente).
- **Formula:** `M4(campo, formato) = campi corretti / campi attesi`
- **Regola:** un campo che il sistema dichiara "incerto" e manda in revisione **non** conta come errore, ma va riportato a parte (tasso di revisione). Conta come errore un campo sbagliato presentato come certo.

## M5 — Ritrovamento dei token in stampa 🔒

- **Definizione:** quota di Binding Token inseriti nel gestionale che il sistema ritrova, con checksum valido, nel PDF del consuntivo prodotto dal gestionale.
- **Formula:** `M5 = token ritrovati e validi / token inseriti in righe stampate`
- **Soglia:** **100%** per i token stampati per intero. Se il gestionale tronca o altera il campo, la modalità di aggancio va rivista (D8), non la soglia.

## M6 — Tempo operatore per 100 fatture

- **Definizione:** minuti di lavoro umano per portare un lotto di 100 fatture dall'arrivo nello studio alla pubblicazione del rendiconto con i QR.
- **Componenti:** conferma del condominio, copia del token in causale, gestione delle eccezioni in Review Console, pubblicazione. È escluso il lavoro contabile che l'amministratore farebbe comunque.
- **Misura:** timestamp delle azioni nell'audit log; nei test di laboratorio, cronometro.
- **Baseline:** in Fase 0 si misura il tempo che oggi lo studio impiega per rispondere alle richieste di chiarimento e per ricostruire a mano il legame voce‑fattura.

## M7 — Integrità del PDF arricchito 🔒

- **Definizione:** il PDF arricchito non altera il contenuto del PDF originale.
- **Verifiche automatiche, per ogni PDF prodotto:**
  1. stesso numero di pagine originali (le pagine indice aggiunte sono riconoscibili e separate);
  2. il testo estratto dalle pagine originali coincide con quello estratto dal PDF arricchito, esclusi gli elementi aggiunti (QR, richiami, token rimosso nella versione per i condomini);
  3. tutti gli importi e i totali dell'originale sono presenti e identici;
  4. nessun elemento aggiunto si sovrappone al riquadro di un testo originale.
- **Soglia:** **100%** dei PDF del corpus di collaudo.

## M8 — Rilevazione delle alterazioni 🔒

- **Definizione:** quota di documenti alterati dopo l'acquisizione che il sistema rileva (hash diverso) e blocca.
- **Set di prova:** copie dei documenti del corpus modificate in modi diversi (un byte, un importo, metadati, file sostituito con un altro valido).
- **Formula:** `M8 = alterazioni rilevate e bloccate / alterazioni introdotte`
- **Soglia:** **100%**.

## M9 — Accessi non autorizzati riusciti 🔒

- **Definizione:** numero di richieste della suite di test di autorizzazione che restituiscono dati a cui l'utente non ha diritto (altro studio, altro condominio, documento non concesso, QR revocato, utente anonimo).
- **Metodo:** test automatici che alterano gli identificativi nelle richieste, riusano QR di altri condomini e accedono senza sessione.
- **Soglia:** **0**. Ogni tentativo negato deve risultare nel log degli accessi.

## M10 — Duplicati da ripetizione 🔒

- **Definizione:** documenti, binding, voci o QR duplicati generati ripetendo un'operazione: import dello stesso file da più canali, riavvio di un job, ristampa dello stesso rendiconto.
- **Formula:** `M10 = oggetti presenti dopo la ripetizione − oggetti presenti prima`
- **Soglia:** **0**. Le provenienze aggiuntive di un documento già presente vanno registrate, ma non creano un nuovo documento.
