Auto-sync: 20260503_230000

memory-bank/features-archive.md

@@ -0,0 +1,58 @@
+# 🗄️ Features Archive
+
+Questo documento è un archivio tecnico completo che descrive tutte le funzionalità (features) principali presenti all'interno dell'applicazione **CAI Facile**, spiegando lo scopo ("Cosa fa") e l'implementazione tecnica a livello di codice ("Come lo fa").
+
+---
+
+## 1. Compilazione Guidata del Modulo CID
+* **File Coinvolti**: `comp_1-5.dart` fino a `comp_15.dart`, `comp_16.dart`, `global_data.dart`
+* **Cosa fa**: Trasforma il complesso modulo cartaceo ministeriale della Constatazione Amichevole in un flusso guidato step-by-step (wizard) ottimizzato per smartphone.
+* **Come lo fa**: Lo stato dell'intera compilazione viene mantenuto in RAM tramite le variabili statiche della classe `GlobalData`.
+  - Utilizza validatori Regex nei form (es. email e telefoni internazionali).
+  - La **localizzazione automatica** in `comp_1-5.dart` usa i package `geolocator` e `geocoding` per recuperare le coordinate GPS del telefono e tradurle nel nome della strada/città dell'incidente senza che l'utente debba digitarla.
+  - La **dinamica dell'incidente** viene disegnata dall'utente su un `CustomPaint` vettoriale (`PainterV40`), permettendo il piazzamento di veicoli (auto, moto, furgoni), frecce e percorsi liberi.
+
+## 2. Autocompilazione e Persistenza Locale (Profilo Utente)
+* **File Coinvolti**: `services/profilo_service.dart`
+* **Cosa fa**: Evita la noiosa riscrittura manuale dei dati anagrafici e della polizza assicurativa per i futuri incidenti o compilazioni.
+* **Come lo fa**: Ad ogni salvataggio del modulo, il servizio estrae i dati del contraente, del veicolo, dell'assicurazione e del conducente da `GlobalData` e li memorizza sul dispositivo fisico usando le `SharedPreferences` (sistema chiave-valore nativo di iOS/Android). All'avvio dell'app o della sezione, l'app interroga la cache e popola automaticamente i text field.
+
+## 3. Scambio Dati P2P via Firebase e QR Code
+* **File Coinvolti**: `scambio_dati_screen.dart`, `cid_data_manager.dart`, `firebase_exchange.dart`
+* **Cosa fa**: Risolve il problema di dover compilare a mano un solo telefono o scambiarsi i telefoni durante l'incidente. Il Veicolo A e il Veicolo B possono compilare la propria parte sui rispettivi smartphone per poi unire i dati magicamente.
+* **Come lo fa**: L'architettura si basa su **Google Cloud Firestore**. 
+  - Il Conducente A (Host) preme "Ricevi Dati", il sistema genera una Sessione univoca sul DB e genera un **QR Code** con l'ID sessione.
+  - Il Conducente B (Guest) scansiona il QR Code col pacchetto `mobile_scanner`, si connette a Firestore, e invia in formato JSON i propri dati.
+  - La classe `CidDataManager` serializza i dati di `GlobalData` lato A e lato B isolandoli, per evitare sovrascritture incrociate (es. il Veicolo B non può sovrascrivere il disegno del grafico del Veicolo A).
+
+## 4. Motore di Generazione PDF e Sigillo Crittografico
+* **File Coinvolti**: `pdf_engine.dart`, `cai_mapping.dart`
+* **Cosa fa**: Stampa i dati raccolti sul modulo grafico ministeriale del CID e genera il file PDF legalmente valido e condivisibile via WhatsApp/Mail.
+* **Come lo fa**: Usa la libreria `Syncfusion Flutter PDF`. 
+  - Legge un template vergine `assets/CAI_p1.pdf`.
+  - Itera sul dizionario in `cai_mapping.dart` che collega le variabili di `GlobalData` ai nomi esatti dei `PdfTextBoxField` e `PdfCheckBoxField` del form PDF.
+  - Appiattisce i campi interattivi (`flattenAllFields()`) trasformandoli in testo statico per impedirne la modifica successiva.
+  - *Advanced*: Renderizza il `Canvas` del disegno e i punti vettoriali delle `Firme Autografe` in PNG per stamparli sopra il documento.
+
+## 5. Monetizzazione In-App (Paywall)
+* **File Coinvolti**: `screens/paywall_screen.dart`, `services/subscription_service.dart`
+* **Cosa fa**: Sistema di barriera all'accesso (Paywall) che sblocca le funzioni premium dell'app (es. la possibilità di usare lo Scambio Dati).
+* **Come lo fa**: L'app si appoggia a **RevenueCat** (`purchases_flutter`). Il servizio si inizializza all'apertura dell'app distinguendo se è su iOS (certificati P8) o su Android (chiavi API Google Play). L'acquisto non è un abbonamento ricorrente, ma uno sblocco "Una-Tantum" locale da 0,99€ che altera il flag `isPro` dell'utente.
+
+## 6. Verifica Copertura RCA (Anti-Frode)
+* **File Coinvolti**: `verifica_rca_screen.dart`, `test_scraping.dart`
+* **Cosa fa**: Permette all'utente di inserire la targa della controparte per scoprire immediatamente se il veicolo è assicurato oppure no.
+* **Come lo fa**: In assenza di API pubbliche gratuite, utilizza un proxy di web scraping (`test_scraping.dart`) che effettua chiamate HTTP mascherate simulando un browser verso portali governativi (es. Il Portale dell'Automobilista). Intercetta la risposta HTML, la parsifica e restituisce alla UI l'informazione cruda sulla polizza.
+
+## 7. Firma Elettronica Avanzata (FEA) 🚧 *In corso*
+* **File Coinvolti**: `screens/fea_verification_screen.dart`, `pdf_engine.dart`
+* **Cosa fa**: Previene il disconoscimento della firma digitale garantendole pieno valore legale.
+* **Come lo fa**: 
+  - L'utente inserisce il cellulare e riceve un **OTP (One Time Password)** via SMS, confermando in maniera inequivocabile l'identità hardware al momento della firma sul display.
+  - Il sistema appende una **Pagina 2 (Attestato FEA)** al PDF generato con l'ID univoco della transazione OTP e l'orario certificato.
+  - Infine, `pdf_engine.dart` carica da root bundle il file `assets/certificate.pfx` (chiave privata) e usa `PdfSignature` per **sigillare crittograficamente** l'intero PDF. Qualsiasi alterazione al PDF effettuata dopo il salvataggio invaliderà automaticamente la certificazione in Adobe Acrobat.
+
+## 8. Soccorsi Rapidi (Pronto Soccorso / Carro Attrezzi)
+* **File Coinvolti**: `carro_attr.dart`, `ps.dart`
+* **Cosa fa**: Interfacce di emergenza rapide per l'utente in panico post-incidente, mostrando in un clic il carro attrezzi più vicino o l'ospedale più vicino.
+* **Come lo fa**: Esegue query geospaziali calcolando la distanza tra le coordinate dell'utente (ottenute via `geolocator`) e i punti di interesse nelle vicinanze. Avvia intent nativi (es. `url_launcher` con schemi `tel:`) per chiamare istantaneamente l'ospedale o l'officina selezionata.