# DOMUSCAN — Registro delle decisioni

> Registro delle scelte di progetto. Riferimenti: [progetto.md](progetto.md), [PIANO_FASE_0.md](PIANI_DI_IMPLEMENTAZIONE/PIANO_FASE_0.md), [architettura.md](architettura.md).

## Regole del registro

- Ogni decisione ha un identificativo stabile (`D1`, `D2`, …) che non si riusa.
- **Stati possibili:**
  - `APERTA`: da discutere;
  - `PROPOSTA`: c'è una proposta, in attesa di approvazione;
  - `APPROVATA`: decisa, il codice deve rispettarla;
  - `SOSTITUITA`: superata da una decisione successiva, indicata nel campo *Sostituita da*.
- Una decisione `APPROVATA` **non si modifica**. Se cambia, si crea una nuova voce e la precedente passa a `SOSTITUITA`.
- Le decisioni di prodotto le approva il committente (Ing. Christian Canino); quelle tecniche il team di sviluppo, informando il committente.

### Modello per nuove voci

```
## Dx — Titolo
- **Stato:** APERTA | PROPOSTA | APPROVATA | SOSTITUITA
- **Contesto:** perché serve decidere
- **Opzioni:** alternative considerate
- **Decisione:** scelta adottata
- **Motivazione:** perché
- **Conseguenze:** cosa cambia per il codice, i costi, i documenti
- **Decisa da / data:** —
- **Sostituita da:** —
```

---

## Riepilogo

| ID | Decisione | Stato | Esito |
|---|---|---|---|
| D1 | Stack tecnologico | APPROVATA | PHP procedurale, JS vanilla, SQL, Bootstrap ([architettura.md](architettura.md)) |
| D2 | Database | SOSTITUITA | PostgreSQL → sostituita da D12 |
| D3 | Dove risiede il file della fattura | APPROVATA | Document Vault DOMUSCAN (puntatore come opzione futura) |
| D4 | Regola di auto‑associazione | APPROVATA | Pubblicazione automatica solo livelli A e B |
| D5 | Tipo di sigillo | APPROVATA | Firma asimmetrica con timestamp |
| D6 | Perimetro dell'MVP | APPROVATA | Solo i 3 SAL dell'offerta |
| D7 | Autenticazione del condomino | APPROVATA | Account con invito; predisposizione per SPID e CIE |
| D8 | Modalità di aggancio del token | APERTA | In attesa dell'indagine Danea |
| D9 | Esecuzione dei job asincroni | APPROVATA | Coda su DB + worker PHP via cron |
| D10 | Librerie esterne | APERTA | Approvate PHPMailer e Bootstrap (Fase 1); il resto dopo i prototipi P1–P5 |
| D11 | Hosting | APPROVATA | VPS OVH (da acquistare) |
| D12 | Database | APPROVATA | MariaDB (sostituisce D2) |
| D13 | Chiave Amministratore | APPROVATA | Una per amministratore, `DSA-XXXX-XXXX-XXXX`, rigenerabile con storico |
| D14 | Attivazione degli account amministratore | APPROVATA | Automatica alla conferma dell'email |

---

## D1 — Stack tecnologico

- **Stato:** APPROVATA
- **Contesto:** i documenti di analisi (DomusScan.pdf, offerta) indicano Node.js/Python, microservizi Docker e PostgreSQL/MongoDB. [architettura.md](architettura.md) indica PHP, HTML, JS vanilla, SQL, CSS e Bootstrap, con approccio procedurale e senza framework.
- **Opzioni:**
  1. Stack di architettura.md (PHP procedurale, JS vanilla, SQL standard, Bootstrap);
  2. stack dei documenti di analisi (Node.js/Python, microservizi in container).
- **Decisione:** opzione 1, come definito in architettura.md.
- **Motivazione:** è lo standard già adottato dal team; ha costi di hosting contenuti e dipendenze ridotte. Le capacità richieste dall'MVP sono coperte da PHP nativo, da strumenti a riga di comando (Poppler, Tesseract, qpdf) e da poche librerie, da verificare con i prototipi.
- **Conseguenze:**
  - aggiornare PROGETTO.md §7.2 e i riferimenti a "microservizi/Cloud‑Native";
  - comunicare al committente lo scostamento rispetto all'offerta;
  - hosting su VPS (vedi D11);
  - i job asincroni vanno risolti in PHP (vedi D9).
- **Decisa da / data:** committente — registrata il 06/10/2026
- **Sostituita da:** —

## D2 — Database

- **Stato:** SOSTITUITA
- **Contesto:** serve un database relazionale per il Binding Registry, l'audit log e il modello canonico. architettura.md chiede SQL standard.
- **Opzioni:**
  1. MySQL / MariaDB (diffusissimo negli hosting PHP);
  2. PostgreSQL (indicato nei documenti di analisi; tipi JSON e vincoli più ricchi).
- **Decisione:** opzione 2, PostgreSQL.
- **Motivazione:** è già indicato nei documenti di analisi; offre vincoli più ricchi (utili per l'integrità del Binding Registry e dell'audit log) e un supporto JSON nativo per i metadati estratti.
- **Conseguenze:**
  - estensione PHP `pdo_pgsql` obbligatoria;
  - restare comunque su SQL standard dove possibile, come chiede architettura.md;
  - backup con `pg_dump`.
- **Decisa da / data:** team — registrata il 06/10/2026
- **Sostituita da:** D12 (15/10/2026)

## D3 — Dove risiede il file della fattura

- **Stato:** APPROVATA
- **Contesto:** l'analisi Basilotta suggerisce il "puntatore certificato" (DOMUSCAN conserva solo l'hash e un link al cloud dello studio). La Specifica DIBP e il Capitolato richiedono un Document Vault DOMUSCAN con copia autorizzata.
- **Opzioni:**
  1. Document Vault DOMUSCAN cifrato;
  2. solo puntatore al cloud dello studio;
  3. Vault come default, puntatore come opzione per tenant.
- **Decisione:** opzione 3, con il solo Vault nell'MVP.
- **Motivazione:** il Vault garantisce che l'hash si possa sempre ricontrollare e che il documento resti disponibile; il puntatore dipende da sistemi esterni non controllati.
- **Conseguenze:**
  - costi di storage (contenuti: le fatture XML sono leggere);
  - DOMUSCAN diventa responsabile del trattamento per la conservazione, da riflettere negli accordi privacy.
- **Decisa da / data:** committente — registrata il 06/10/2026
- **Sostituita da:** —

## D4 — Regola di auto‑associazione

- **Stato:** APPROVATA
- **Contesto:** la Specifica DIBP vieta la pubblicazione di associazioni probabilistiche. Il Capitolato (D04) la ammette sopra una soglia calibrata sul pilota.
- **Opzioni:**
  1. auto‑pubblicazione solo per i livelli A (token valido) e B (chiave fiscale canonica univoca);
  2. anche il probabilistico sopra una soglia.
- **Decisione:** opzione 1. Il matching probabilistico produce solo proposte in Review Console.
- **Motivazione:** il criterio di accettazione è "zero associazioni automatiche errate"; senza dati del pilota una soglia non è calibrabile.
- **Conseguenze:** la copertura automatica sarà più bassa; la si potrà rivalutare dopo il pilota con una nuova decisione.
- **Decisa da / data:** committente — registrata il 06/10/2026
- **Sostituita da:** —

## D5 — Tipo di sigillo

- **Stato:** APPROVATA
- **Contesto:** lo schema "la catena che chiude" usa `S = hash(Hd + Hs + Hc + k)` con un segreto `k` non salvato nel database. La bozza brevettuale descrive hash, identificativo, timestamp e firma con chiave privata, verificabile con chiave pubblica.
- **Opzioni:**
  1. HMAC con segreto `k` fuori dal DB;
  2. firma asimmetrica (es. Ed25519) con timestamp, verificabile pubblicamente;
  3. firma asimmetrica con marca temporale eIDAS.
- **Decisione:** opzione 2, firma asimmetrica con timestamp. Il contenuto firmato comprende l'hash del documento, l'hash della registrazione e l'hash della catena degli storni, così che il meccanismo "la catena che chiude" resti valido.
- **Motivazione:** permette la verifica indipendente con la sola chiave pubblica (rivendicazione 2), senza i costi per marca dell'opzione 3.
- **Conseguenze:**
  - nell'MVP la firma si realizza con l'estensione `sodium` di PHP (Ed25519);
  - la chiave privata è conservata fuori dal database e dal repository, con una procedura di rotazione;
  - la marca temporale eIDAS resta un'evoluzione possibile, da registrare come nuova decisione;
  - resta da allineare con il consulente brevettuale (TODO 0.9); il prototipo P5 verifica solo questa opzione.
- **Decisa da / data:** team — registrata il 06/10/2026
- **Sostituita da:** —

## D6 — Perimetro dell'MVP

- **Stato:** APPROVATA
- **Contesto:** l'offerta da 7.500 € copre acquisizione, overlay QR, Review Console e resolver. Il Capitolato colloca nell'MVP anche la spiegazione IA, la tassonomia, la scheda intelligente e il controllo accessi completo.
- **Opzioni:**
  1. MVP = solo i 3 SAL dell'offerta;
  2. MVP esteso secondo il Capitolato, con un nuovo preventivo.
- **Decisione:** opzione 1. Spiegazione IA, tassonomia, benchmark e stampante virtuale passano alla V1.
- **Motivazione:** è coerente con il budget e i tempi firmati, e porta prima il valore centrale (verificabilità) sul campo.
- **Conseguenze:** il Capitolato va letto come riferimento per la V1.
- **Decisa da / data:** committente — registrata il 06/10/2026
- **Sostituita da:** —

## D7 — Autenticazione del condomino

- **Stato:** APPROVATA
- **Contesto:** il QR non è un'autorizzazione: chi lo inquadra deve essere riconosciuto come avente diritto.
- **Opzioni:**
  1. account con invito da parte dello studio;
  2. OTP via email su indirizzi registrati dallo studio;
  3. link personale a scadenza;
  4. SPID (futuro).
- **Decisione:** opzione 1, account con invito da parte dello studio. Il sistema va predisposto per aggiungere in seguito SPID e CIE.
- **Motivazione:** è semplice da realizzare nell'MVP e lascia allo studio il controllo su chi accede.
- **Conseguenze:**
  - lo studio carica l'anagrafica minima dei condomini (nome, email, unità) e invia gli inviti;
  - l'identità dell'utente va separata dal metodo di accesso (tabella degli "identificativi di accesso" per utente), così che SPID/CIE si aggiungano come nuovi metodi senza migrare gli account;
  - va riflessa nell'informativa privacy.
- **Decisa da / data:** team — registrata il 06/10/2026
- **Sostituita da:** —

## D8 — Modalità di aggancio del token

- **Stato:** APERTA
- **Contesto:** il protocollo DIBP richiede che il token inserito nel gestionale compaia nella stampa del consuntivo.
- **Opzioni:**
  - A. token nel campo causale/descrizione;
  - B. assistente appunti/overlay desktop;
  - C. nome del file "carrier";
  - D. protocollo esterno.
- **Decisione:** —, in attesa della scheda SCHEDA_GESTIONALE_DANEA.md.
- **Motivazione:** —
- **Conseguenze:** nell'MVP la copia del token avviene dall'interfaccia web (Clipboard API); il widget desktop è previsto per la V1.
- **Decisa da / data:** —
- **Sostituita da:** —

## D9 — Esecuzione dei job asincroni

- **Stato:** APPROVATA
- **Contesto:** la pipeline `ingest → parse → match → review → publish` deve essere asincrona, idempotente e ripetibile. Con PHP non ci sono worker nativi.
- **Opzioni:**
  1. coda su tabella del database + worker PHP da riga di comando avviati da cron o supervisor;
  2. message broker esterno (Redis, RabbitMQ).
- **Decisione:** opzione 1, worker PHP avviati da cron.
- **Motivazione:** nessuna dipendenza aggiuntiva e SQL standard; è sufficiente per i volumi del pilota.
- **Conseguenze:**
  - tabella job con stato, tentativi ed errore;
  - lock per evitare esecuzioni doppie;
  - chiave di idempotenza per job.
- **Decisa da / data:** team — registrata il 06/10/2026
- **Sostituita da:** —

## D10 — Librerie esterne

- **Stato:** APERTA
- **Contesto:** architettura.md chiede PHP puro e la conferma esplicita per ogni libreria esterna, preferendo licenze open source o una tantum.
- **Decisione:** —, l'elenco si compila dopo i prototipi P1–P5.
- **Decisa da / data:** —
- **Sostituita da:** —

### Librerie approvate

| Libreria / strumento | Uso | Licenza | Stato | Note |
|---|---|---|---|---|
| `phpmailer/phpmailer` 7.1.1 (Composer) | Invio SMTP autenticato delle email transazionali (conferma, recupero password, notifiche) | LGPL‑2.1‑only | ✅ Approvata il 15/10/2026 (PIANO_PILOTA_v2 §2.9, punto 2) | Usata solo in modalità `EMAIL_MODALITA=smtp`; in sviluppo le email sono scritte su file. Installata in `vendor/` con `composer install` |
| Bootstrap 5.3.8 | Interfaccia (CSS e JS) | MIT | ✅ Approvata (architettura.md) | Copia locale in `pubblico/risorse/vendor/bootstrap/`, nessun CDN (PIANO_PILOTA_v2 §2.9, punto 3). Integrità verificata con l'hash SHA‑512 pubblicato su npm |

### Candidate da valutare

Verifica di licenze e manutenzione al 06/10/2026, su dati di Packagist e dei repository ufficiali. "Release 12 mesi" = numero di versioni pubblicate tra il 06/10/2025 e il 06/10/2026.

| Libreria / strumento | Uso | Ultima stabile | Licenza | PHP richiesto | Manutenzione | Valutazione |
|---|---|---|---|---|---|---|
| PHP nativo (`hash`, `sodium`, `openssl`, `DOM`, `SimpleXML`) | Hash, firma Ed25519, cifratura, `.p7m`, XML | — | PHP License | — | — | ✅ Nessuna dipendenza esterna |
| `chillerlan/php-qrcode` | Generazione QR | 6.0.1 (18/03/2026) | MIT / Apache‑2.0 (a scelta) | ^8.2, `ext-mbstring` | Attiva (3 release) | ✅ Candidata principale per i QR |
| `endroid/qr-code` | Generazione QR | 6.1.3 (05/02/2026) | MIT | **^8.4** | Attiva (4 release) | ⚠️ Alternativa; impone PHP 8.4 sul server |
| `setasign/fpdf` | Generazione PDF di base | 1.9.0 (31/05/2026) | Permissiva (licenza FPDF, distribuita come MIT su Packagist) | —, `ext-zlib`, `ext-gd` | Stabile, poche release (1) | ✅ Base per l'overlay con FPDI |
| `setasign/fpdi` | Importare pagine di PDF esistenti per l'overlay | v2.6.8 (11/06/2026) | MIT | ≥7.2 ≤8.5, `ext-zlib` | Attiva (4 release) | ⚠️ **Confermato dal sorgente:** il parser gratuito rifiuta i PDF con xref compressi (`CrossReferenceException::COMPRESSED_XREF`). Il parser completo è commerciale (FPDI PDF‑Parser). Mitigazione: normalizzare prima con `qpdf` (prototipo P3) |
| `tecnickcom/tcpdf` | Alternativa a FPDF | 7.0.15 (03/10/2026) | LGPL‑3.0‑or‑later | ≥8.2, `ext-curl` | **Deprecata**: solo manutenzione; lo sviluppo è passato a `tc-lib-pdf` | ❌ Sconsigliata per un progetto nuovo |
| `tecnickcom/tc-lib-pdf` | Successore di TCPDF | 8.78.2 (03/10/2026) | LGPL‑3.0‑or‑later | ^8.2 | Attiva | ⚠️ Solo se FPDF non basta; licenza LGPL (vedi nota) |
| `smalot/pdfparser` | Testo dai PDF in PHP puro | v2.12.5 (17/04/2026) | LGPL‑3.0 | ≥7.1, `ext-zlib`, `ext-iconv` | Attiva (4 release) | ⚠️ Fallback; coordinate da verificare in P1. Licenza LGPL (vedi nota) |
| Poppler (`pdftotext -bbox`) | Testo **con coordinate** dai PDF | Attivo (commit 06/10/2026) | **GPL** | Riga di comando | Attiva | ⚠️ Candidato principale per P1. Usato come programma esterno, non collegato al codice (vedi nota) |
| qpdf | Normalizzazione dei PDF prima dell'overlay | Attivo (commit 26/09/2026) | Apache‑2.0 | Riga di comando | Attiva | ✅ |
| Tesseract | OCR selettivo | Attivo (commit 28/09/2026) | Apache‑2.0 | Riga di comando | Attiva | ✅ Richiede i dati di lingua `ita` |

**Nota sulle licenze (GPL/LGPL).** architettura.md esclude licenze che limitino l'uso del software.
- Poppler (GPL) viene solo **eseguito come programma separato** (`pdftotext`), non incluso nel codice. Secondo l'interpretazione prevalente questo non estende la GPL a DOMUSCAN.
- Le librerie LGPL (`smalot/pdfparser`, `tc-lib-pdf`) sono in genere compatibili con software proprietario se restano sostituibili.
- DOMUSCAN è erogato come servizio e non distribuito. Questo riduce ulteriormente gli obblighi, ma la valutazione va **confermata dal consulente legale** prima di approvare D10.

**Proposta preliminare per D10**, da confermare dopo i prototipi:
- PHP nativo per hash, firma e XML;
- `chillerlan/php-qrcode` per i QR;
- FPDF + FPDI, con normalizzazione `qpdf`, per l'overlay;
- Poppler `pdftotext -bbox` per l'estrazione;
- Tesseract per l'OCR.

## D11 — Hosting

- **Stato:** APPROVATA
- **Contesto:** l'offerta consiglia Google Cloud Run oppure Hetzner Cloud / DigitalOcean. Con lo stack PHP (D1) e i worker via cron (D9) è più adatta una VPS tradizionale. I costi sono a carico del committente.
- **Opzioni:**
  1. VPS OVH;
  2. Hetzner Cloud;
  3. DigitalOcean;
  4. Google Cloud Run.
- **Decisione:** opzione 1, VPS OVH. Va ancora acquistata.
- **Motivazione:** scelta già fatta dal team e approvata dal committente; data center europei, compatibili con il GDPR.
- **Conseguenze:**
  - stack di server: PHP‑FPM, web server, PostgreSQL e cron sulla stessa VPS nel pilota;
  - backup su uno spazio separato dalla VPS (vedi la strategia di backup);
  - dimensionamento da confermare all'acquisto.
- **Decisa da / data:** team, approvata dal committente — registrata il 06/10/2026
- **Sostituita da:** —

## D12 — Database

- **Stato:** APPROVATA
- **Contesto:** [architettura.md](architettura.md), che prevale sugli altri documenti, indica MariaDB. D2 aveva scelto PostgreSQL; [PIANO_PILOTA_v2.md](PIANI_DI_IMPLEMENTAZIONE/PIANO_PILOTA_v2.md) riallinea il progetto ad architettura.md prima di scrivere il primo codice.
- **Opzioni:**
  1. MariaDB;
  2. PostgreSQL (D2).
- **Decisione:** opzione 1, MariaDB (versione di riferimento: 12.3 LTS).
- **Motivazione:** è lo stack fissato da architettura.md; è diffuso negli hosting PHP e disponibile come pacchetto nelle distribuzioni Linux della VPS (D11).
- **Conseguenze:**
  - estensione PHP `pdo_mysql` obbligatoria (al posto di `pdo_pgsql`);
  - SQL standard dove possibile: `VARCHAR` con vincoli `CHECK` al posto di `ENUM`, colonne generate `GENERATED ALWAYS AS` per i vincoli condizionali (es. una sola Chiave Amministratore attiva), date in UTC. Restano specifici di MariaDB solo `AUTO_INCREMENT`, `ENGINE=InnoDB` e la sintassi dei trigger;
  - tabelle in `utf8mb4` / `utf8mb4_unicode_ci`;
  - backup con `mariadb-dump` (al posto di `pg_dump`); client `mariadb`;
  - le conseguenze di D9 (coda su tabella) e D11 (stack del server) valgono con MariaDB al posto di PostgreSQL.
- **Decisa da / data:** team, da architettura.md — registrata il 15/10/2026
- **Sostituita da:** —

## D13 — Chiave Amministratore

- **Stato:** APPROVATA
- **Contesto:** la Fase 1 di [PIANO_PILOTA_v2.md](PIANI_DI_IMPLEMENTAZIONE/PIANO_PILOTA_v2.md) introduce una chiave personale dell'amministratore, da inserire nelle registrazioni perché DOMUSCAN riconduca le fatture allo studio. È distinta dal Binding Token per documento (`DSN-…`) di DomusScan.pdf.
- **Opzioni:** chiave per amministratore o per studio; inserita dall'amministratore o dal fornitore; rigenerabile o no.
- **Decisione:**
  - una chiave **per amministratore**, lasciando aperta la possibilità di passare a una chiave per studio (il modello dati la collega all'amministratore, che appartiene a uno studio);
  - la inserisce **l'amministratore o lo studio** (causale o note della registrazione);
  - la **rigenerazione è ammessa**, con conferma della password: la vecchia chiave passa a `revocata` ma resta nello storico e riconoscibile, così un condomino che verifica un documento già emesso può ancora risalire alla firma;
  - formato `DSA-XXXX-XXXX-XXXX`: 11 caratteri casuali (CSPRNG, 55 bit) + 1 carattere di controllo Luhn mod 32, alfabeto Base32 di Crockford.
- **Motivazione:** risposte del committente al §2.9 del piano (15/10/2026).
- **Conseguenze:** al massimo una chiave attiva per amministratore, garantita anche da un vincolo `UNIQUE` del database; ogni emissione e revoca va nel registro di audit. Il carattere di controllo rileva ogni carattere errato e ogni scambio di caratteri adiacenti, tranne lo scambio tra `0` e `Z` (limite noto dell'algoritmo di Luhn, come `09`↔`90` nel Luhn decimale).
- **Decisa da / data:** committente — registrata il 15/10/2026
- **Sostituita da:** —

## D14 — Attivazione degli account amministratore

- **Stato:** APPROVATA
- **Contesto:** in pilota si poteva prevedere un'approvazione manuale di DOMUSCAN prima dell'emissione della chiave, per ammettere solo gli studi selezionati.
- **Opzioni:**
  1. attivazione automatica alla conferma dell'email;
  2. approvazione manuale di DOMUSCAN.
- **Decisione:** opzione 1. L'account si attiva quando l'amministratore apre il link ricevuto via email e conferma; nella stessa transazione riceve la Chiave Amministratore.
- **Motivazione:** risposta del committente al §2.9, punto 4, del piano (15/10/2026).
- **Conseguenze:** il link di conferma è monouso, vale 24 ore e si consuma con un POST (i filtri antispam che aprono i link in anteprima non lo invalidano). Lo stato `sospeso` permette di bloccare un account a mano se necessario.
- **Decisa da / data:** committente — registrata il 15/10/2026
- **Sostituita da:** —
