# DOMUSCAN — Piano pilota v2 (partenza dal codice)

> Sostituisce come riferimento operativo [PIANO_PILOTA.md](PIANO_PILOTA.md), che resta come roadmap storica.
> Vincoli tecnici: [architettura.md](../architettura.md) (prevale sugli altri documenti in caso di conflitto).
> Riferimento funzionale principale: `documenti per analisi/DomusScan.pdf` (analisi Basilotta).
>
> **Redatto il:** 15/10/2026

---

## 0. Cosa cambia rispetto al piano precedente

- **Si parte subito con il codice.** Le attività ancora aperte della Fase 0 (indagine Danea, corpus pilota, ground truth, prototipi P1–P5, legale) non bloccano più la Fase 1: proseguono in parallelo e diventano prerequisiti solo delle fasi che ne hanno bisogno (indicate fase per fase).
- **Si procede per funzionalità verticali e utilizzabili**, non per strati. Ogni fase termina con qualcosa che un amministratore può aprire nel browser e usare.
- **Il database è MariaDB**, come da [architettura.md](../architettura.md). La decisione D2 di [DECISIONI.md](../DECISIONI.md) (PostgreSQL) va aggiornata, insieme a `configurazione/.env.esempio`, `documentazione/ambienti.md`, `documentazione/struttura_progetto.md` e `strumenti/verifica_ambiente.sh` (vedi task 1.1).

### Regole sempre valide (da architettura.md)

| Tema | Regola |
|---|---|
| Stack | PHP, HTML, CSS, JavaScript vanilla (nessun framework), Bootstrap, MariaDB |
| Stile | Procedurale: funzioni, niente classi salvo se imposte da librerie esterne |
| Dipendenze | PHP puro; ogni libreria esterna va **confermata dall'utente** prima dell'uso; solo licenze open source o una‑tantum |
| SQL | SQL standard (evitare estensioni specifiche di MariaDB dove esiste un'alternativa standard) |
| Naming | Tutto in italiano. File e cartelle `snake_case`, funzioni `camelCase`, variabili `snake_case`, costanti `UPPER_SNAKE_CASE`, classi `PascalCase` |
| Intestazione | Ogni file inizia con l'intestazione PHPDoc prevista (progetto, nome file, autore, descrizione, date, versione), aggiornata a ogni modifica |
| Commenti | Ogni funzione ha un blocco PHPDoc in italiano con `@description`, `@param`, `@return`, `@throws` |

### Principi di prodotto (da DomusScan.pdf)

- **Modello "ponte" / certificazione a valle:** DOMUSCAN non accede al gestionale e non lo sostituisce; lavora sui suoi output (PDF, CSV, stampe).
- **Fail‑closed:** in assenza di certezza nessun QR, nessuna associazione automatica. Meglio una voce non "bollinata" che una sbagliata.
- **Un solo gesto in più per l'amministratore:** incollare un codice DOMUSCAN nella registrazione contabile.
- **Utility ai margini del lavoro**, non un nuovo gestionale: interfacce minime e pulite.

---

## 1. Roadmap

```
Fase 1  Registrazione amministratore + Chiave Amministratore     ← questo documento, in dettaglio
Fase 2  Acquisizione fatture (upload, cartella DOMUSCAN_IN), hash, Vault, token documento
Fase 3  Lettura FatturaPA, chiave fiscale, ponte di registrazione (copia token)
Fase 4  Lettura del consuntivo, matching fail‑closed, Review Console
Fase 5  Print Layer: QR sul PDF del consuntivo (DOMUSCAN_OUT), sigillo
Fase 6  Resolver pubblico verify.domuscan.it, accessi dei condomini su invito, go‑live pilota
```

Le fasi 2–6 sono descritte in sintesi al §3 e verranno dettagliate all'avvio di ciascuna.

---

## 2. Fase 1 — Registrazione dell'amministratore e Chiave Amministratore

### 2.1 Obiettivo

Un amministratore di condominio si registra su DOMUSCAN, conferma il proprio indirizzo email e, alla conferma, il sistema **genera e gli assegna una Chiave Amministratore**: un codice personale, univoco e non indovinabile, da inserire sulle fatture (causale, note o riferimento del documento) perché DOMUSCAN possa ricondurle con certezza al suo studio.

L'amministratore trova la chiave nella propria area riservata, la copia con un clic e legge dove e come inserirla.

### 2.2 Che cos'è la Chiave Amministratore

> **Da confermare (vedi §2.9, punto 1).** DomusScan.pdf descrive un *Binding Token* per ogni documento (`DSN-K7M4`); la richiesta di questa fase introduce in più una chiave **per amministratore**. Il piano la tratta come un identificativo distinto, che non sostituisce il token per documento delle fasi successive.

| Proprietà | Scelta proposta | Motivo |
|---|---|---|
| Formato | `DSA-XXXX-XXXX-XXXX` | Prefisso diverso dal token documento `DSN-…`, per non confonderli né nel PDF né nel matching |
| Alfabeto | Base32 di Crockford (`0-9 A-Z` senza `I L O U`) | Niente caratteri ambigui quando si ricopia o si legge da un PDF |
| Contenuto | 11 caratteri casuali (55 bit) + 1 carattere di checksum (algoritmo di Luhn mod 32, sullo stesso alfabeto) | Non indovinabile, non enumerabile; il checksum scarta gli errori di battitura (carattere sbagliato, due adiacenti scambiati) prima di interrogare il database |
| Generazione | `random_bytes()` di PHP (CSPRNG) | Casualità crittografica senza librerie esterne |
| Dati personali | Nessuno | Il codice finisce su documenti che circolano: non deve rivelare nome, P.IVA o altro |
| Univocità | Indice `UNIQUE` sul database + nuova estrazione in caso di collisione | Garanzia anche nel caso (remoto) di collisione |
| Riconoscimento | Regex tollerante a spazi e minuscole, normalizzazione in maiuscolo e trattini | Prepara la lettura dai PDF della Fase 4 |
| Stato | `attiva` / `revocata`, con data di emissione e di revoca | Una chiave compromessa si revoca senza perdere lo storico |
| Rigenerazione | Solo su richiesta esplicita, con conferma della password; la vecchia chiave passa a `revocata` ma resta riconoscibile per le fatture già emesse | Le fatture già in circolazione non devono "perdere" il collegamento |

**Non è la chiave del sigillo.** La firma asimmetrica del sigillo (D5) usa una chiave privata Ed25519 di DOMUSCAN, conservata sul server; è un'altra cosa e arriva nella Fase 5. Nell'interfaccia si userà l'etichetta "Chiave Amministratore" (o "Codice DOMUSCAN") per evitare equivoci con la "chiave privata" crittografica.

### 2.3 Flusso utente

1. **Registrazione** (`/registrazione.php`): nome, cognome, denominazione dello studio, codice fiscale o P.IVA, email, password (due volte), accettazione di informativa privacy e condizioni.
2. Il sistema crea studio e amministratore in stato `da_verificare` e invia un'email con un link di conferma monouso, valido 24 ore.
3. **Conferma email** (`/conferma_email.php?t=…`): l'account passa a `attivo` e, nella stessa transazione, viene **generata e assegnata la Chiave Amministratore**. Evento scritto nel registro di audit.
4. **Accesso** (`/accesso.php`) con email e password.
5. **Area riservata** (`/area_riservata.php`): la chiave in evidenza, pulsante "Copia" (JS vanilla, Clipboard API), istruzioni su dove inserirla (causale/note della registrazione, campo note o riferimento della fattura), data di emissione.
6. **Rigenerazione** (`/chiave_rigenera.php`): conferma con password, revoca della vecchia chiave, emissione della nuova, email di notifica.
7. **Uscita** (`/uscita.php`) e **recupero password** (`/password_dimenticata.php`, `/password_reimposta.php`) con token monouso.

Link di conferma scaduto: pagina che permette di richiederne uno nuovo, senza rivelare se l'email è registrata.

### 2.4 Modello dati (MariaDB, `database/migrazioni/`)

| Tabella | Campi principali |
|---|---|
| `studi` | `id`, `denominazione`, `codice_fiscale_partita_iva` (UNIQUE), `creato_il` |
| `amministratori` | `id`, `studio_id` (FK), `nome`, `cognome`, `email` (UNIQUE), `hash_password`, `stato` (`da_verificare` / `attivo` / `sospeso`), `email_verificata_il`, `creato_il`, `aggiornato_il` |
| `chiavi_amministratore` | `id`, `amministratore_id` (FK), `chiave` (UNIQUE), `stato` (`attiva` / `revocata`), `emessa_il`, `revocata_il`, `motivo_revoca` |
| `token_monouso` | `id`, `amministratore_id` (FK), `scopo` (`verifica_email` / `reimposta_password`), `hash_token` (SHA‑256, mai il token in chiaro), `scade_il`, `usato_il` |
| `tentativi_accesso` | `id`, `email`, `indirizzo_ip`, `esito`, `tentato_il` — per limitare i tentativi |
| `registro_audit` | `id`, `attore_id`, `azione`, `oggetto_tipo`, `oggetto_id`, `dettagli` (JSON in TEXT), `indirizzo_ip`, `registrato_il` — solo inserimenti, mai update o delete |
| `migrazioni` | `nome_file`, `applicata_il` — tiene traccia degli script già eseguiti |

Vincolo applicativo, verificato dai test: **al massimo una chiave `attiva` per amministratore**. La tabella `studi` è già il "tenant" che servirà dalla Fase 2 (fatture, condomini).

### 2.5 Struttura del codice

Coerente con [documentazione/struttura_progetto.md](../../documentazione/struttura_progetto.md):

```
pubblico/
  index.php                     reindirizza ad accesso o area riservata
  registrazione.php  conferma_email.php  accesso.php  uscita.php
  area_riservata.php  chiave_rigenera.php
  password_dimenticata.php  password_reimposta.php
  risorse/css/domuscan.css
  risorse/js/copia_chiave.js
  risorse/vendor/bootstrap/     Bootstrap in locale (niente CDN)
sorgenti/
  comune/avvio.php              carica configurazione, sessione, gestione errori
  comune/configurazione.php     lettura del file .env (parser proprio, niente librerie)
  comune/database.php           connessione PDO (pdo_mysql), transazioni
  comune/sessione.php           sessione sicura, token CSRF
  comune/viste.php              rendering dei template, escape dell'output
  comune/email.php              invio email (vedi §2.9, punto 2)
  comune/audit.php              scrittura nel registro di audit
  comune/validazione.php        email, codice fiscale, partita IVA, password
  accessi/registrazione.php     creazione studio + amministratore, invio conferma
  accessi/autenticazione.php    accesso, uscita, limitazione dei tentativi
  accessi/token_monouso.php     emissione e consumo dei token monouso
  accessi/password.php          hash, verifica, reimpostazione
  associazioni/chiave_amministratore.php
                                generaChiaveAmministratore, calcolaChecksumChiave,
                                validaFormatoChiave, normalizzaChiave,
                                assegnaChiaveAmministratore, revocaChiaveAmministratore,
                                trovaAmministratorePerChiave
sorgenti/viste/                 template HTML (Bootstrap) delle pagine
database/migrazioni/
  001_studi_amministratori.sql  002_chiavi_amministratore.sql
  003_token_monouso_tentativi.sql  004_registro_audit.sql
strumenti/migra.php             applica in ordine le migrazioni non ancora eseguite
test/php/                       test delle funzioni (runner in PHP puro, vedi task 1.9)
```

### 2.6 Sicurezza (requisiti minimi della fase)

- Password con `password_hash()` (`PASSWORD_ARGON2ID` se disponibile, altrimenti `PASSWORD_DEFAULT`); minimo 10 caratteri.
- Query solo con prepared statement PDO; nessuna concatenazione di input nell'SQL.
- Token CSRF su ogni form POST; `session_regenerate_id()` dopo l'accesso; cookie `HttpOnly`, `SameSite=Lax`, `Secure` fuori dallo sviluppo.
- Escape sistematico dell'output (`htmlspecialchars`) tramite una funzione unica in `viste.php`.
- Limitazione dei tentativi di accesso (es. 5 errori in 15 minuti per email/IP); messaggi d'errore che non rivelano se l'email esiste.
- Token monouso salvati solo come hash, con scadenza e consumo atomico.
- Nessuna password, token o chiave nei log applicativi; nel registro di audit solo identificativi.
- Header di sicurezza di base (`Content-Security-Policy` restrittiva, `X-Content-Type-Options`, `Referrer-Policy`).

### 2.7 Task

| # | Task | Esito atteso |
|---|---|---|
| 1.1 | **Allineamento a MariaDB:** aggiornare D2 in DECISIONI.md, `.env.esempio` (porta 3306, variabili DB), `ambienti.md`, `struttura_progetto.md`, `verifica_ambiente.sh` (`pdo_mysql` al posto di `pdo_pgsql`, client `mysql`/`mariadb-dump`) e `backup.md` | Nessun riferimento residuo a PostgreSQL come scelta adottata |
| 1.2 | **Ambiente locale:** PHP ≥ 8.3 con `pdo_mysql`, `sodium`, `mbstring`, `openssl`; MariaDB; database e utente dedicati; `.env` compilato | `verifica_ambiente.sh` senza mancanze per i requisiti di questa fase; `php -S localhost:8000 -t pubblico` risponde |
| 1.3 | **Base comune:** `avvio.php`, configurazione da `.env`, connessione PDO, sessione e CSRF, viste con escape, gestione errori (dettagli solo in sviluppo) | Pagina di prova che legge dal database |
| 1.4 | **Migrazioni:** script SQL 001–004 e `strumenti/migra.php` idempotente | Rieseguire `migra.php` non produce errori né duplicati |
| 1.5 | **Chiave Amministratore:** funzioni di generazione, checksum, validazione, normalizzazione, assegnazione, revoca, ricerca | Test: formato, checksum che rileva un carattere errato e due caratteri scambiati, unicità, una sola chiave attiva |
| 1.6 | **Registrazione e conferma email:** form, validazioni (inclusi checksum di codice fiscale e partita IVA), creazione in transazione, email di conferma, attivazione con assegnazione della chiave | Registrazione → conferma → chiave visibile; link riusato o scaduto respinto |
| 1.7 | **Accesso, uscita, recupero password**, limitazione dei tentativi | Test dei casi d'errore; nessuna enumerazione delle email |
| 1.8 | **Area riservata e rigenerazione chiave:** layout Bootstrap responsive, copia negli appunti, istruzioni d'uso, rigenerazione con password e notifica | Utilizzabile anche da smartphone; storico delle chiavi revocate conservato |
| 1.9 | **Test:** runner minimale in PHP puro in `test/php/`, richiamato da `test/esegui_test.sh`; database di test separato | `bash test/esegui_test.sh` verde |
| 1.10 | **Documentazione:** README (avvio locale), `documentazione/` aggiornata, TODO.md con i task della Fase 1 | Un altro sviluppatore avvia il progetto seguendo solo la documentazione |

Ordine consigliato: 1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 → 1.7 → 1.8, con 1.9 e 1.10 portati avanti insieme a ciascun task.

### 2.8 Criteri di uscita (Fase 1 "fatta")

- [x] Un nuovo amministratore si registra, riceve l'email (in sviluppo: file in `dati/log/email/`), conferma e vede la propria Chiave Amministratore nell'area riservata.
- [x] La chiave rispetta formato e checksum, è unica, non contiene dati personali e c'è una sola chiave attiva per amministratore.
- [x] La rigenerazione revoca la vecchia chiave senza cancellarla e ne emette una nuova; l'evento è nel registro di audit.
- [x] Link di conferma e di reimpostazione password sono monouso e scadono.
- [x] Accesso protetto da CSRF e limitazione dei tentativi; nessun messaggio rivela se un'email è registrata.
- [x] Tutti i file hanno l'intestazione prevista e ogni funzione il suo blocco PHPDoc; naming conforme ad architettura.md.
- [x] Nessuna libreria esterna oltre a Bootstrap, salvo quelle confermate (§2.9).
- [x] `bash test/esegui_test.sh` verde.

### 2.9 Decisioni da confermare prima di iniziare

1. **Natura della chiave.** Il piano assume una chiave per amministratore, distinta dal token per documento (`DSN-…`) di DomusScan.pdf, nel formato `DSA-XXXX-XXXX-XXXX`. Da confermare: (a) per amministratore o per studio (se in futuro uno studio avrà più operatori); (b) chi la inserisce sulle fatture (l'amministratore in causale, o il fornitore nel campo note/riferimento della FatturaPA); (c) se la rigenerazione è ammessa.
	- a) per amministratore, con possibilità aperta di rollback verso studio. b) inserisce l'amministratore/studio. c) la rigenerazione è ammessa, ma bisogna tenere lo storico. se sono un condomino che vuole scansionare, e la chiave è cambiata, devo comunque poter visionare la firma
2. **Invio email.** In sviluppo le email vengono scritte su file. Per staging e produzione serve SMTP autenticato: (a) un piccolo client SMTP scritto in PHP puro (`stream_socket_client` + STARTTLS), oppure (b) PHPMailer (licenza LGPL‑2.1, via Composer). L'uso di PHPMailer richiede conferma esplicita come da architettura.md.
	- PHPMailer con licenza
3. **Bootstrap:** versione 5.3 in copia locale in `pubblico/risorse/vendor/` (licenza MIT), senza CDN per non dipendere da terzi.
	- punto da valutare. sicuramente senza CDN.
4. **Approvazione degli account:** attivazione automatica alla conferma dell'email (proposta) oppure approvazione manuale di DOMUSCAN prima dell'emissione della chiave, utile in pilota per ammettere solo gli studi selezionati.
	- Conferma con mail, cliccando sul link. 

---

## 3. Fasi successive (sintesi)

### Fase 2 — Acquisizione fatture e Vault
Upload multi‑file e cartella sorvegliata `DOMUSCAN_IN` (DomusScan.pdf, Fase A); SHA‑256, provenienza, deduplicazione; Vault cifrato con `sodium`; Document ID e **token documento** `DSN-XXXX-XXXX`; worker PHP via cron (D9). Fatture associate allo studio (tenant) creato in Fase 1.
*Prerequisito:* set di fatture sintetiche o anonimizzate.

### Fase 3 — Lettura FatturaPA e ponte di registrazione
Parser XML e `.xml.p7m`; chiave fiscale canonica (P.IVA fornitore, numero, data, importo); **riconoscimento della Chiave Amministratore** nei campi della fattura; pagina "documenti pronti per la registrazione" con copia del token in causale (il "ponte").
*Prerequisito:* D8 (quali campi Danea finiscono nella stampa del bilancio).

### Fase 4 — Consuntivo, matching e Review Console
Lettura del PDF del consuntivo con coordinate (Poppler); ricerca dei token; matching nell'ordine token → chiave fiscale → proposta, fail‑closed; Review Console con eccezioni (*Ambiguità*, *Token assente*, *Verificato*) e azioni tracciate.
*Prerequisito:* corpus pilota e ground truth (TODO 0.4–0.5).

### Fase 5 — Print Layer e sigillo
Dal PDF in `DOMUSCAN_OUT` al PDF con QR accanto alle righe, senza alterare numeri e testi; controllo prima/dopo; sigillo con firma asimmetrica e timestamp (D5).
*Prerequisito:* conferma delle librerie PDF/QR (D10), da approvare come da architettura.md.

### Fase 6 — Resolver, accessi dei condomini, go‑live
`verify.domuscan.it` con verifica dell'hash al volo e blocco se il documento è alterato; visualizzatore in sola lettura; condomini su invito dello studio (D7), predisposizione SPID/CIE; collaudo con uno studio reale; VPS OVH, HTTPS, backup provati.
*Prerequisiti:* VPS e DNS (TODO 0.8), gate legale/privacy (TODO 0.9).

---

## 4. Trasversali

- **Fail‑closed** come criterio di accettazione permanente.
- **Audit log append‑only** dal primo giorno (Fase 1).
- **Multi‑tenant:** ogni query dalla Fase 2 in poi filtra per `studio_id`; test anti accesso tra studi diversi.
- **Riservatezza fino al deposito del brevetto:** nessuna demo o pagina pubblica del metodo.
- **Nessun dato reale** in sviluppo; dati reali solo dopo gli accordi privacy con gli studi pilota.
