# DOMUSCAN — Piano di implementazione della Fase 0

> Dettaglio della **Fase 0 — Decisioni e corpus pilota** di [PIANO_PILOTA.md](PIANO_PILOTA.md). Riferimenti: [progetto.md](../progetto.md) (cosa e come), [architettura.md](../architettura.md) (stack e convenzioni di codice).

## Scopo

Arrivare al primo giorno di sviluppo del SAL 1 con:

1. **decisioni scritte**, senza punti aperti che blocchino il codice;
2. **dati reali autorizzati** su cui sviluppare e misurare;
3. **rischi tecnici principali già verificati** con piccoli prototipi;
4. **ambienti, domini e quadro legale** pronti.

La Fase 0 non produce codice di prodotto. Produce documenti, dati e prototipi da buttare.

**Durata indicativa:** 2–3 settimane. I tempi dipendono soprattutto da quanto rapidamente gli studi pilota forniscono il materiale.

> ⚠️ La Fase 0 **non compare nei SAL dell'offerta** (21/07/2026). Va chiarito con il committente se rientra nella Fase A o se va concordata a parte. Va verificato anche lo stato del contratto: l'offerta era valida 30 giorni.

---

## Attori

| Ruolo | Chi | Responsabilità in Fase 0 |
|---|---|---|
| Committente / ideatore | Ing. Christian Canino | Decisioni di prodotto, contatto con gli studi pilota, strategia brevettuale |
| Analisi e sviluppo | Dott.ssa Franca Basilotta | Decisioni tecniche, prototipi, metriche |
| Sviluppo | Damiano | Prototipi, ambienti, repository, ground truth |
| Studi pilota | Da individuare | Materiale, accesso al gestionale, test sul campo |
| Consulenti esterni | Legale/privacy, brevettuale | Ruoli GDPR, accordi, deposito |

*(Da aggiornare se la ripartizione reale è diversa.)*

---

## Flussi di lavoro

I flussi 0.1–0.3 sono propedeutici; gli altri possono procedere in parallelo.

### 0.1 Registro delle decisioni

**Obiettivo:** chiudere per iscritto le scelte che oggi i documenti lasciano aperte.

Registro in [DECISIONI.md](../DECISIONI.md), che fa fede sullo stato delle decisioni (la tabella seguente riporta le proposte di partenza): una voce per decisione con **contesto, opzioni, scelta, motivazione, data e chi ha deciso**. Le decisioni pubblicate non si modificano; se cambiano, si aggiunge una nuova voce che sostituisce la precedente.

Decisioni da chiudere (da [progetto.md §11](../progetto.md#11-decisioni-e-punti-aperti), più quelle emerse dallo stack):

| # | Decisione | Proposta di partenza | Dipende da |
|---|---|---|---|
| D1 | Stack tecnologico | Quello di [architettura.md](../architettura.md): PHP procedurale, SQL standard, JS vanilla, Bootstrap. Allineare progetto.md §7.2, che cita Node/Python e microservizi Docker | — |
| D2 | Database | Relazionale con SQL standard (MySQL/MariaDB o PostgreSQL, secondo l'hosting) | D1, 0.8 |
| D3 | Dove risiede il file | Document Vault DOMUSCAN cifrato come default; puntatore al cloud dello studio come opzione futura | 0.9 (privacy) |
| D4 | Regola di auto‑associazione | Pubblicazione automatica solo per i livelli A (token) e B (chiave fiscale univoca); tutto il resto in revisione | — |
| D5 | Tipo di sigillo | Da scegliere tra hash con segreto `k` fuori dal DB e firma asimmetrica con timestamp | 0.9 (brevetto), 0.7 |
| D6 | Perimetro MVP | Solo quanto previsto dai 3 SAL; spiegazione IA, tassonomia e benchmark rimandati alla V1 | Committente |
| D7 | Autenticazione del condomino | Da definire: account con invito, OTP via email o link a scadenza | 0.9 |
| D8 | Modalità di aggancio del token | Modalità A (token in causale), dopo la verifica sul gestionale | 0.3 |
| D9 | Esecuzione dei job asincroni in PHP | Coda su tabella DB + worker CLI avviati da cron/supervisor | D1 |
| D10 | Librerie esterne | Elenco da approvare (vedi 0.2) | D1 |

**Uscita:** DECISIONI.md con D1–D10 chiuse; progetto.md e PIANO_PILOTA.md aggiornati dove contraddicono le decisioni.

### 0.2 Allineamento dello stack e librerie

**Obiettivo:** confermare che lo stack scelto copre tutte le capacità richieste dall'MVP e, dove serve, scegliere librerie con licenza compatibile.

[architettura.md](../architettura.md) chiede PHP puro e la conferma esplicita per ogni libreria esterna. Elenco delle capacità da coprire, con le candidate da valutare:

| Capacità | Candidate da valutare | Punto di attenzione |
|---|---|---|
| Hash SHA‑256, cifratura dei file | PHP nativo (`hash`, `sodium`) | Nessuna libreria esterna necessaria |
| Parsing FatturaPA XML | PHP nativo (`DOMDocument`/`SimpleXML`) | Fatture firmate `.xml.p7m`: estrazione del contenuto via `openssl` |
| Testo e coordinate dai PDF | `smalot/pdfparser` oppure `pdftotext -bbox` (Poppler, da riga di comando) | Le coordinate sono indispensabili per il Print Layer |
| OCR selettivo | Tesseract da riga di comando | Solo per le pagine scansionate |
| Generazione QR | `chillerlan/php-qrcode`, `endroid/qr-code` | Licenza |
| Sovrapposizione su PDF esistente | FPDI + FPDF/TCPDF | **La versione gratuita di FPDI non legge alcuni PDF moderni** (xref compressi): verificare sui PDF reali di Danea; alternativa: normalizzare prima con `qpdf` |
| Copia negli appunti del token | JS vanilla (Clipboard API) | Sufficiente per l'MVP; il widget desktop resta per la V1 |

**Uscita:** sezione "Librerie approvate" in DECISIONI.md, con licenza e motivazione per ognuna.

### 0.3 Indagine sul gestionale (Danea Domustudio)

**Obiettivo:** sapere con certezza come il token viaggia dal gestionale alla stampa. È il presupposto dell'intero protocollo DIBP.

Su un'installazione reale (presso uno studio pilota o una licenza di prova) verificare:

- quali campi del movimento (causale, descrizione, note, protocollo, riferimento) **compaiono nelle stampe** del consuntivo, del rendiconto per voce e del partitario;
- i limiti di quei campi: lunghezza massima, caratteri ammessi (`[`, `]`, `-`), eventuale troncamento in stampa;
- se il PDF esportato contiene **testo estraibile** o immagini rasterizzate;
- quali esportazioni esistono oltre al PDF (Excel/CSV) e se riportano la causale;
- come avviene l'import delle fatture elettroniche e se il nome del file o altri riferimenti finiscono nelle stampe (modalità C);
- se esiste un campo "protocollo" utilizzabile (modalità D).

Ripetere la verifica, anche in forma ridotta, su un secondo gestionale se uno studio pilota ne usa un altro.

**Uscita:** `PROJECT DOCS/SCHEDA_GESTIONALE_DANEA.md` con screenshot, PDF di esempio e la modalità di aggancio raccomandata (chiude D8).

### 0.4 Corpus pilota

**Obiettivo:** disporre di materiale reale, autorizzato e vario.

1. **Individuare 1–3 studi pilota**: almeno uno con Danea Domustudio, idealmente uno con un altro gestionale.
2. **Formalizzare l'autorizzazione** prima di ricevere qualsiasi file: accordo di riservatezza e nomina a responsabile del trattamento (vedi 0.9).
3. **Composizione minima** (indicativa, da tarare con gli studi):
   - 2–3 condomini, almeno un esercizio chiuso ciascuno;
   - per ognuno: consuntivo/rendiconto PDF e, se disponibili, preventivo e riparto;
   - tutte le fatture dell'esercizio in XML (meglio anche il PDF di cortesia); in totale almeno 100–200 documenti;
   - casi difficili da includere di proposito: fatture con lo stesso importo, note di credito, acconto e saldo, fattura ripartita su più voci o scale, più fatture in una voce aggregata, fatture `.p7m`, documenti scansionati, utenze (bollette).
4. **Conservazione**: archivio cifrato con accesso limitato al team, fuori dal repository e fuori da servizi cloud non approvati. Ogni file registrato in un inventario (origine, data, studio, hash).
5. **Set sintetico/anonimizzato**: una piccola copia senza dati personali da usare nei test automatici e nel repository.

**Uscita:** corpus archiviato, inventario completo, set anonimizzato.

### 0.5 Ground truth

**Obiettivo:** sapere qual è la risposta giusta, così da poter misurare il sistema.

- Definire un formato di etichettatura (foglio di calcolo/CSV): `id_riga`, `condominio`, `esercizio`, `pagina`, `testo_voce`, `importo_voce`, `id_documenti`, `importo_allocato`, `tipo_relazione` (1:1, 1:N, N:1, nota di credito…), `certezza`, `note`.
- Etichettare tutte le righe di almeno un consuntivo completo per studio.
- **Doppia verifica**: una seconda persona controlla un campione; le discordanze si risolvono con lo studio.
- Segnare le righe che **non hanno** un documento fiscale (sono casi legittimi, non errori).

**Uscita:** file di ground truth versionato, che diventerà la base dei test di regressione dal SAL 1 in avanti.

### 0.6 Metriche e criteri di collaudo

**Obiettivo:** concordare prima come si misura il successo, così i collaudi dei SAL sono oggettivi.

| Metrica | Definizione | Soglia |
|---|---|---|
| Associazioni automatiche errate | Righe a cui il sistema associa da solo un documento sbagliato | **0** (assoluta) |
| Copertura automatica | % di righe associate senza intervento umano | Da fissare dopo la baseline |
| Accuratezza di estrazione | % di campi chiave (fornitore, numero, data, totale) estratti correttamente, per formato | Da fissare dopo i prototipi |
| Tempo operatore | Minuti per gestire un lotto di 100 fatture | Baseline misurata a mano in Fase 0 |
| Integrità del PDF | Testi e importi originali invariati dopo l'overlay | 100% |
| Accessi cross‑tenant | Accessi riusciti a dati di un altro studio o condominio | **0** (assoluta) |

Per ogni SAL scrivere i **criteri di collaudo** concreti (quali test, su quali documenti, quali esiti), partendo dai test T01–T12 della Specifica DIBP e T01–T07 del Capitolato.

**Uscita:** `PROJECT DOCS/CRITERI_COLLAUDO.md` condiviso e approvato dal committente.

### 0.7 Prototipi di fattibilità

**Obiettivo:** eliminare i rischi tecnici prima di impegnarsi sui SAL. Sono prototipi da buttare: servono a rispondere "si può fare con questo stack?".

| Prototipo | Domanda | Esito atteso |
|---|---|---|
| P1 — Lettura del consuntivo | Riesco a ricostruire righe, importi e coordinate dal PDF reale di Danea e a trovare i token? | Righe estratte dai PDF del corpus, con il tasso di successo |
| P2 — Lettura FatturaPA | Riesco a leggere XML e `.p7m` del corpus estraendo i campi della chiave fiscale? | Tutte le fatture del corpus lette, con l'elenco delle eccezioni |
| P3 — Overlay QR | Riesco ad aggiungere un QR accanto a una riga senza alterare il resto del PDF? | PDF arricchito; verifica prima/dopo del testo estratto |
| P4 — Token | Il formato `DSN-XXXX-XXXX` con checksum regge copia/incolla, stampa ed estrazione dal PDF? | Token ritrovati al 100% nei PDF di prova generati dal gestionale |
| P5 — Sigillo | La variante scelta (D5) è verificabile in modo efficiente e regge la catena degli storni? | Script di prova con i casi "chiude" e "non chiude" |

**Uscita:** breve report per prototipo (cosa ha funzionato, limiti, impatto sulle stime) in `DEVELOPMENT DOCS/`.

### 0.8 Ambienti, repository e domini

**Obiettivo:** il primo giorno del SAL 1 si scrive codice, non si configurano server.

- **Repository git**: inizializzarlo (oggi la cartella non è un repository), con la struttura delle cartelle in snake_case secondo [architettura.md](../architettura.md) e il `.gitignore` esistente (che già esclude `PROJECT DOCS/`, segreti e documenti interni).
- **Hosting**: VPS OVH, scelta e approvata ([D11](../DECISIONI.md#d11--hosting)); da acquistare con un dimensionamento iniziale adeguato al pilota. I costi sono a carico del committente.
- **Ambienti**: sviluppo locale, staging e produzione separati; gestione dei segreti via `.env` fuori dal repository.
- **Domini**: `domuscan.it` risultava *inactive / dnsHold* alla registrazione. Configurare i DNS, attivare `verify.domuscan.it` (resolver) e il sottodominio dell'applicazione, con certificati TLS. Decidere il ruolo di `domuscan.org`.
- **Email**: casella dedicata per l'acquisizione delle fatture (ed eventualmente PEC), da usare nella Fase 1.
- **Backup**: strategia definita e prima prova di ripristino.

**Uscita:** repository inizializzato, staging raggiungibile su dominio con HTTPS, costi stimati e approvati.

### 0.9 Legale, privacy e proprietà intellettuale

**Obiettivo:** poter trattare dati reali in modo lecito e non compromettere il brevetto.

- **Ruoli GDPR**: lo studio è presumibilmente titolare e DOMUSCAN responsabile del trattamento. Preparare il modello di accordo ex art. 28.
- **Informativa ai condomini** sull'accesso ai documenti tramite QR.
- **Valutazione d'impatto (DPIA)**: decidere con il consulente se serve.
- **Conservazione**: tempi di retention dei documenti e dei log.
- **Brevetto**: lo schema delle rivendicazioni è una bozza per il consulente. **Nessuna demo pubblica, pagina web o presentazione esterna del metodo prima del deposito**: la divulgazione può compromettere la novità. Allineare la scelta del sigillo (D5) con il consulente.
- **Licenze del gestionale**: verificare che stampare e rielaborare i PDF del consuntivo non violi la licenza di Danea (rischio basso, ma va scritto).

**Uscita:** accordi firmati con gli studi pilota prima di ricevere i dati; checklist privacy approvata; vincolo di riservatezza fino al deposito condiviso con il team.

---

## Sequenza consigliata

```
Settimana 1   0.1 avvio decisioni ─┬─ 0.9 accordi studi pilota ─▶ 0.4 raccolta corpus
              0.2 stack/librerie   │   0.8 repo + hosting + domini
                                   │
Settimana 2   0.3 indagine Danea ──┴─▶ 0.7 prototipi P1–P4
              0.4 corpus completato ─▶ 0.5 ground truth
                                     0.6 metriche + baseline tempi
Settimana 3   0.7 P5 sigillo · chiusura decisioni D1–D10
              0.6 criteri di collaudo approvati · gate di uscita
```

Percorso critico: **accordi con gli studi → corpus → indagine Danea → prototipi**. Se gli studi tardano, si possono anticipare 0.2, 0.8 e i prototipi su PDF e XML generati in proprio, ma il gate non si chiude senza materiale reale.

---

## Gate di uscita dalla Fase 0

La Fase 0 è chiusa, e il SAL 1 può partire, quando:

- [ ] DECISIONI.md riporta D1–D10 chiuse e approvate dal committente
- [ ] progetto.md e PIANO_PILOTA.md sono allineati alle decisioni (in particolare lo stack)
- [ ] La scheda del gestionale conferma che il token compare nella stampa del consuntivo e resta estraibile
- [ ] Il corpus pilota è autorizzato, archiviato in modo sicuro e inventariato, ed esiste un set anonimizzato
- [ ] La ground truth di almeno un consuntivo completo è etichettata e verificata
- [ ] Metriche, baseline dei tempi e criteri di collaudo dei tre SAL sono approvati
- [ ] I prototipi P1–P4 hanno dato esito positivo, oppure i limiti sono documentati con un piano alternativo
- [ ] Repository, staging, domini con HTTPS e backup sono operativi; i costi di hosting sono approvati
- [ ] Gli accordi privacy con gli studi pilota sono firmati e il vincolo di riservatezza sul brevetto è condiviso

---

## Rischi principali

| Rischio | Effetto | Mitigazione |
|---|---|---|
| Il gestionale non stampa la causale nel consuntivo | Il protocollo DIBP (modalità A) non funziona | Verificarlo per primo (0.3); ripiegare sulle modalità D o C, o sulla chiave fiscale |
| Gli studi pilota non forniscono dati in tempo | Fase 0 bloccata | Coinvolgerli dalla settimana 1; prototipi su dati sintetici nel frattempo |
| PDF di Danea non gestibili con le librerie PHP gratuite | Print Layer a rischio | Prototipo P3 sui PDF reali; normalizzazione con `qpdf`; valutare strumenti a riga di comando |
| Disallineamento sullo stack tra documenti e team | Stime e consegne incoerenti con l'offerta | Chiudere D1 e aggiornare i documenti subito |
| Divulgazione del metodo prima del deposito | Perdita della novità brevettuale | Vincolo di riservatezza; demo solo sotto NDA |
| Fase 0 non coperta dal budget | Attrito con il committente | Chiarirlo all'avvio (vedi nota in "Scopo") |
