# Decisions & Architecture

## Gestione Firebase Sync e Tipizzazione
- **Problema**: Firebase trasforma dizionari con chiavi numeriche sequenziali (come le 17 circostanze del CID) in List, causando crash a runtime.
- **Soluzione**: Introdotta e adottata la funzione helper `fixCircostanze` in `CidDataManager` per fare un parsing dinamico sicuro sia da List che da Map.

## Coordinate PDF
- **Decisione (Blindata)**: Il motore PDF utilizza un posizionamento assoluto (`pw.Stack`) con coordinate fisse (es. Box 12 Y=575.0, Font 8pt Bold) per garantire una stampa pixel-perfect identica al modulo cartaceo ufficiale. Non rompere mai il layout per testo in overflow.

## Mappatura Payload
- Si utilizzano nomi brevi (minificati) per il payload JSON (es. `cog` per Cognome, `cf` per Codice Fiscale, `circ` per Circostanze) per ridurre le dimensioni dei pacchetti e ottimizzare i codici QR.

## Sincronizzazione Dati Condivisi
- Il "Cassetto 1" (Grafico Incidente con auto e strade) viene gestito **esclusivamente dal Conducente A** e sincronizzato in sovrascrittura su B per evitare conflitti logici.
- Le Firme ("Cassetto 2") restano indipendenti (A non sovrascrive B).

## Monetizzazione & Paywall (RevenueCat)
- **Decisione**: L'app utilizza un modello "Hard Paywall parziale". Gli utenti possono compilare il modulo offline gratuitamente, ma la **funzionalità core di Scambio Dati (QR Code e sincronizzazione Firebase)** è bloccata dietro un abbonamento annuale.
- **Implementazione**: Utilizzo di RevenueCat (`purchases_flutter`) per delegare la validazione delle ricevute lato server. Interfaccia Paywall custom (`PaywallScreen`) piuttosto che il pacchetto UI di RevenueCat per mantenere coerenza stilistica e aumentare le conversioni con copy persuasivo ("Sblocca la sincronizzazione").

## Firma Elettronica Avanzata (FEA)
- **Decisione**: Per conferire pieno valore legale di "scrittura privata" al documento (ex art. 2702 c.c.) e rispettare i requisiti del CAD, il CID viene protetto con una Firma Elettronica Avanzata.
- **Flusso**: 1) Identificazione utente tramite OTP via SMS (Firebase Phone Auth). 2) Aggiunta di un "Attestato di Certificazione FEA" in Pagina 2 del PDF con firme autografe visibili. 3) Applicazione di un sigillo crittografico invisibile sull'intero PDF tramite certificato PKCS#12 (`assets/certificate.pfx`).
- **Privacy (GDPR)**: Nessun log viene salvato sul database Firebase. La prova crittografica e l'Audit Trail dell'OTP "viaggiano" esclusivamente fusi all'interno del PDF stesso, in modo inalterabile.