============================================================
   GUIDA ALL'USO - CriptoTaxWebApp (Windows / Apple/macOS)
============================================================

CriptoTaxWebApp calcola automaticamente plusvalenze e
minusvalenze (metodo LIFO), il Quadro RW e l'imposta sul
valore delle cripto-attività (IC) per la
dichiarazione dei redditi in Italia.

IMPORTANTE: l'app funziona interamente sul tuo computer, in
OFFLINE. I tuoi file CSV non vengono inviati ad alcun server
esterno.
NOTA RETE: l'unica eccezione è il tasso USD/EUR per convertire gli
importi delle operazioni in USDT (vedi sezione 7): viene scaricato
dalla BCE e mai il tuo storico.


------------------------------------------------------------
 1) PREREQUISITI (solo la prima volta)
------------------------------------------------------------
L'unico software necessario è Python (gratuito, python.org).

WINDOWS:
 1. Vai su www.python.org/downloads e scarica l'ultima versione.
 2. Nell'installazione SPUNTA "Add Python to PATH".
 3. Clicca "Install Now" e attendi la fine.

APPLE (macOS):
 1. Vai su www.python.org/downloads e scarica la versione macOS,
    oppure da Terminale:  brew install python3
 2. Dal Terminale, dentro questa cartella, esegui:
        chmod +x Avvia_CriptoTaxWebApp.command
 3. In alcuni casi bisogna dare i permessi con: tasto destro
    sul file .command -> Apri (prima volta) -> conferma.

Nota: la prima installazione scarica le librerie da internet
(una tantum). Dopo di che l'app funziona completamente offline.


------------------------------------------------------------
 2) COME AVVIARE L'APP
------------------------------------------------------------

WINDOWS:
  Doppio click su:  Avvia_CriptoTaxWebApp.bat
  Si apre una finestra nera con i log. Dopo qualche secondo il
  browser si apre automaticamente su:
        http://127.0.0.1:8000
Non chiudere la finestra nera: finché resta aperta, l'app è
   attiva. Per fermare tutto, chiudi quella finestra.
   PRIVACY "USA E GETTA": alla chiusura il database e le cache
   vengono eliminati automaticamente dal disco (anche quando
   chiudi la finestra con la X). Se all'uscita la finestra nera
   mostra un "AVVISO: alcuni file di runtime non sono stati
   eliminati", qualche file è rimasto bloccato (es. da un altro
   programma): chiudi tutto e cancellali a mano da data/ per
   non lasciare i tuoi dati sulla chiavetta.

APPLE (macOS):
  Doppio click su:  Avvia_CriptoTaxWebApp.command
  Si apre il Terminale con i log e parte il browser su:
        http://127.0.0.1:8000
  Per fermare: chiudi il Terminale (o premi Ctrl+C).

AVVIO MANUALE (qualsiasi sistema, da terminale dentro la cartella):
        python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
  poi apri il browser su http://127.0.0.1:8000

NOTA PER SVILUPPATORI:
  L'inizializzazione del database (resetta le tabelle di app.db) avviene
  SOLO all'avvio del server (FastAPI lifespan). Non importare app.main
  dentro i tuoi script per richiamare le funzioni di calcolo: l'import
  è sicuro e NON ripulisce il database, ma gli script esterni che
  usano app.internal per analisi/backup NON devono lanciare init_db()
  da soli, altrimenti cancellano i dati caricati nella sessione in corso.


------------------------------------------------------------
  3) PREPARARE I FILE CSV (piattaforma per piattaforma)
------------------------------------------------------------
OSCARIO L'app accetta **uno o più file nello stesso upload** (.csv,
.tsv, .txt, .xlsx, .xls). Puoi caricare insieme trades, depositi,
prelievi e acquisti con carta: l'app riconosce il formato di ogni
file, lo adatta e li unisce eliminando i duplicati.

INTERNO: carica SEMPRE il file degli acquisti (BUY), cioè i
movimenti con cui hai comprato le cripto con euro/carta.
Senza di essi il costo di carico (LIFO) risulta pari a zero e la
plusvalenza calcolata non è reale. Includi quindi anche:
  - depositi (USDT/altri ricevuti sul conto),
  - prelievi (in uscita dal conto),
  - acquisti con carta/euro (fiat -> cripto).

L'app riconosce nativamente, tra gli altri, questi formati:
   - Gate.io "Trade History" (colonne No, Time, Trade type, ...)
   - Gate.io "Acquisti con carta/euro" (Gate Connect: colonne
     Transaction Date, ..., Fiat Amount, Fiat Currency,
     Crypto Quantity, Crypto Currency, ..., Status)
   - Gate.io "Depositi"  (Order ID, Time, ... Coin, Amount, Status)
   - Gate.io "Prelievi"  (Order ID, Time, ... Average Coin, ...)
   - Binance, Coinbase, Kraken, formato personalizzato
   - qualsiasi CSV con colonne riconoscibili per parola chiave

   * GATE.IO
     Da esportare:  Wallet -> Transaction History -> Trade
                    (o: Trade -> Session -> Esporta storico)
    Colonne attese: No, Time, Trade type, Role, Market, Deal
                    price, Deal amount, Total, Fee
Soporta i campi "0.45 MLN" e "2.9376 USDT" (numero +
     simbolo asset nella stessa cella).
     Attenzione: esporta ZERO registri con "MixOrder" o
     "AssignedSell"/"AssignedBuy" insieme ai trade normali,
     altrimenti le quantità possono doppiarsi (per questo
     l'app rimuove automaticamente le righe duplicate).
     Per la plusvalenza reale esporta ANCHE:
       - Deposit:   Wallet -> Transaction History -> Deposits
                    (esporta il file con Order ID, Coin, Amount,
                    Status - l'app lo riconosce da solo);
       - Withdraw:  Wallet -> Transaction History -> Withdrawals
                    (esporta il file con Trading Fee, Amount
                    Received - riconosciuto automaticamente);
       - Acquisti con carta/euro: nella pagina degli acquisti
         di Gate.io (comprare cripto con carta/SEPA, sezione
         "Gate Connect") esporta lo storico. L'app riconosce
         le colonne "Transaction Date / Transaction Time /
         Transaction Type / Fiat Amount / Fiat Currency /
         Crypto Quantity / Crypto Currency / Status" e usa il
         valore in EUR pagato come COSTO DI CARICO nel LIFO.
         Vengono tenuti solo i movimenti completati (Status
         "Done"), scartando i tentativi falliti ("Failed"/
         "Cancel").
       Se l'exchange non esporta i movimenti d'acquisto,
       aggiungili manualmente al file personalizzato (vedi
       sotto) con type=buy:
           time,type,asset,quantity,usdt
           2025-03-14 10:00:00,buy,USDT,186.50,186.50
     Tutti questi file si caricano INSIEME ai trades in un unico
     upload.
     NOTA sul calcolo: il metodo LIFO usa l'intero storico
     caricato (anni precedenti inclusi) come inventario, così
     anche le vendite di inizio anno usano il reale costo di
     carico e non un costo pari a zero.

  * BINANCE
    Da esportare:  Orders -> Trade History (storico reale,
                   NON l'estratto conto depositi)
    Colonne attese: Date(UTC), Market, Type, Amount, Total
    Nota: il download ufficiale è un file ZIP contenente
    "Order" e "Trade". Usa il file TRADE (.csv), non Order.
    Decomprimi lo ZIP prima di caricare.

  * COINBASE
    Da esportare:  Reports -> Generate report -> type
                   "Transactions" -> file .csv o .tsv
    Colonne attese: Timestamp, Transaction Type, Asset,
                    Quantity Transacted, USD Subtotal.
    Attenzione: il report Coinbase contiene righe "Rewards
    Income", "Learning Reward", "Send", "Buy", "Sell", ecc.
    Tutte vengono riconosciute; le vendite/acquisti entrano
    nel calcolo, le ricompense vengono solo registrate.

  * KRAKEN
    Da esportare:  History -> Trades -> Export (CSV "Trades")
    Colonne attese: time, pair, type, amount, total (oppure
                    le intestazioni che produce l'export:
                    txid, dtime, type, pair, cost, vol, fee)
    Nota: se esporti "Ledger" invece di "Trades" il report
    può contenere molte righe non di trading (stake, fee,
    transfer) che l'app riconosce come tipi generici.

  * TREZOR (e altri wallet: Ledger, ...)
    Da esportare:  il report del wallet con tutti i movimenti
                   (Trezor Suite: Account -> History/Export CSV).
                   L'export è per singolo account/coin: se fai uno
                   swap per es. USDT -> BTC comparirà una riga
                   SENT sull'account USDT e una RECV sull'account
                   BTC. Carica ENTRAMBI i file.
    Colonne attese: Timestamp, Date, Time, Type (SENT/RECV/SELF),
                    Transaction ID, Fee, Fee unit, Address, Label,
                    Amount, Amount unit, Fiat (USD), ...
    Riconoscimento:
      - SENT  -> prelievo neutro (nessun realizzo) se è un
                 semplice trasferimento verso un portafoglio tuo;
      - RECV  -> deposito neutro;
      - SELF  -> movimento tra indirizzi tuoi: ignorato.
    Specifica su QUAL è lavorato con la colonna "Amount unit" e il
    controvalore è preso da "Fiat (USD)" (o, se manca, calcolato).
    NOTA: un CSV di un wallet NON distingue da solo un trasferimento
    da una CONVERSIONE (swap) interna. Per gli swap vedi la sezione
    "CONVERSIONI (SWAP)" qui sotto.

  * CONVERSIONI (SWAP) TRA CRIPTO IN WALLET
    Caso tipico: hai convertito 500 USDT -> 0,008 BTC direttamente
    dentro Trezor (o Ledger). Il CSV registra solo SENT/RECV neutri
    e senza un intervento la plusvalenza sull'USDT venduto NON
    verrebbe calcolata.
    Cosa fare:
      1. Carica normalmente i CSV del wallet (le righe diventano
         DEPOSIT/WITHDRAWAL neutri);
      2. Nella pagina principale usa il riquadro
         "REGISTRA UNA CONVERSIONE (SWAP)": indica data, asset
         venduto e quantità, asset ricevuto e quantità, e il
         CONTROVALORE della conversione (quanto valeva l'operazione,
         es. 500 €);
      3. L'app crea la coppia SELL asset ceduto + BUY asset ricevuto
         al controvalore indicato: il LIFO realizza la plus/minusvalenza
         sull'asset ceduto e fissa il costo di carico dell'asset
         ricevuto;
      4. RICONCILIAZIONE AUTOMATICA: le righe neutre corrispondenti
         (WITHDRAWAL della stessa quantità dell'asset venduto e
         DEPOSIT di quella dell'asset ricevuto, entro 2 giorni)
         vengono RIMOSSE, così la stessa operazione non conta due
         volte. Se i candidati sono più di uno (es. due prelievi da
         500 USDT nello stesso periodo) l'app mostra l'elenco e ti
         chiede di selezionare quali rimuovere.
    Da NON usare per i semplici trasferimenti tra i TUOI portafogli
    (exchange -> wallet): quelli restano neutri e non vanno registrati
    come swap.
    Perché è necessario: dal punto di vista fiscale NON tutte le
    conversioni cripto-cripto sono neutre. La neutralità vale solo
    per le permute "in prospettiva di investimento" tra attività con
    medesime caratteristiche e funzioni (es. BTC <-> ETH,
    Circolare AdE 30/E/2023, par. 5.4.5). La conversione verso
    stablecoin/aziendali (USDT/USDC) o token di moneta elettronica
    (EMT) realizza invece una plusvalenza tassabile al momento dello
    scambio; con l'avvento di DAC8 (D.Lgs. 194/2025) questi swap
    saranno segnalati all'Agenzia delle Entrate, quindi vanno
    dichiarati correttamente.

  * CESSIONI (PAGAMENTI CON CRIPTO)
    Se paghi un prodotto/servizio direttamente col wallet (es. BTC spesi
    dal Trezor per comprare un bene), per il fisco non è un trasferimento:
    è una VENDITA che realizza una plusvalenza/minusvalenza al valore in €
    del bene alla data del pagamento.
    Nell'app (riquadro "REGISTRA UNA CESSIONE"):
      1. indica data, asset speso e quantità;
      2. CONTROVALORE (€) = il valore del bene pagato in quella data;
      3. l'app crea SOLO la SELL dell'asset (nessun BUY fittizio) e il
         LIFO calcola da solo il risultato della cessione;
      4. la riga neutra WITHDRAWAL della stessa uscita già importata dal
         CSV viene rimossa automaticamente (conferma se i candidati sono
         più di uno), così la quantità non conta due volte.
    I trasferimenti tra i TUOI portafogli NON sono cessioni: restano neutri.

  * ALTRI EXCHANGE / QUALSIASI CSV
    L'app tenta il riconoscimento automatico cercando le
    colonne per parole chiave: time/data, pair/asset/coin/
    market, type/side, amount/quantity, total/usdt/value,
    fee/commission. Basta che esistano le colonne con quei
    nomi (o simili).

  * FILE PERSONALIZZATO (il modo più sicuro)
    Crea un CSV con queste 5 colonne (o usa quello già
    presente in data/):
        time,type,asset,quantity,usdt
    esempi di riga:
        2025-03-14 10:00:00, buy, BTC, 0.001, 88.50
        2025-03-14 11:30:00, sell, BTC, 0.0005, 47.00
    Dove:
        time     = data/ora nel formato AAAAMMGG o AAAA-MM-GG
        type     = buy / sell / deposit / withdrawal
        asset    = simbolo dell'asset (es. BTC, ETH, MLN)
        quantity = quantità negoziata
        usdt     = controvalore in dollari (solo per i calcoli)
    Prima di caricare assicurati che:
        - il file sia CSV (separatore virgola, tab o punto e
          virgola; l'app rileva la codifica automaticamente);
        - la prima riga contenga le intestazioni delle colonne;
        - non ci siano righe vuote in coda.
    Puoi caricare PIÙ FILE INSIEME (trades + depositi + prelievi
    + acquisti): l'app riconosce il formato di ciascuno, li adatta
    e li unisce eliminando i duplicati. Ogni nuovo upload si
    AGGIUNGE ai dati già presenti (lo storico degli anni precedenti
    viene così conservato): i duplicati identici vengono scartati,
    quindi puoi ricaricare tranquillamente lo stesso file.


------------------------------------------------------------
  4) COME GENERARE IL REPORT FISCALE
------------------------------------------------------------

1. PREPARA I DATI: prepara tutti i file delle operazioni come
   descritto nella sezione 3 qui sopra ("PREPARARE I FILE CSV"):
   trades, depositi, prelievi e acquisti con carta/euro.

2. NELLA PAGINA PRINCIPALE:
   - Exchange: lascia "Rilevamento Automatico" oppure seleziona
     il tuo exchange (l'app rileverà comunque ogni file).
   - Anno Fiscale: scegli l'anno da analizzare (2020-2028).
   - File: hai due modi per caricare i dati:
       a) seleziona TUTTI i file (trades, depositi, prelievi,
          acquisti) - puoi sceglierne più di uno
          contemporaneamente (Ctrl+click / Ctrl+A);
        b) oppure usa "seleziona un'INTERA CARTELLA": scegli la
           cartella che contiene tutti i CSV e l'app carica
           automaticamente tutti i file al suo interno.
     In ogni caso le nuove operazioni si AGGIUNGONO a quelle
     già caricate in precedenza (i duplicati identici vengono
     eliminati): si può ripetere l'upload di uno stesso file
     senza il rischio di azzerare lo storico.

3. Clicca "ANALIZZA CSV E CALCOLA TASSE".

L'ELABORAZIONE AVVIENE IN 2 PASSAGGI:
 - Passo 1 - PREVIEW: compare l'anteprima delle prime 20
   transazioni riconosciute (dopo l'unione di tutti i file
   caricati e la rimozione dei duplicati). Vedi il riepilogo
   "File adattati" per ogni file, e le "Righe Totali" che
   includono anche depositi, prelievi e acquisti. Controlla
   che siano corrette e clicca per procedere al calcolo.
 - Passo 2 - REPORT: si genera il report completo con:
   * dettaglio di ogni vendita (gain/loss calcolato con il
     metodo LIFO: si consumano per primi i lotti acquistati
     più di recente);
   * report fiscale: totale plusvalenze, minusvalenze, imposta;
l'aliquota applicata è del 33% a partire dal 2026 incluso; fino
      al 2025 l'aliquota era del 26% (Legge di Bilancio 2025,
      L. 207/2024; configurabile in app/services/tax_report.py).
      Nota: il 26% resta in vigore SOLO per la plusvalenza realizzata
      su token di moneta elettronica (EMT) espressi in euro e
      conformi al regolamento MiCA (es. un EUR-stablecoin regolato);
      le cripto-attività ordinarie seguono sempre il 33% dal 2026.
    * possibilità di RIVALUTAZIONE delle cripto detenute al
      01/01/2025 (L. 207/2024, art. 1, commi 26-28): si può
      assumere come nuovo costo fiscale il VALORE AL 01/01/2025
      versando un'imposta sostitutiva del 18%, entro il
      30/11/2025 (o 3 rate annuali con interessi 3%). Conviene
      se il costo di carico storico è molto più basso del valore
      attuale o se i costi storici non sono più dimostrabili.
      L'app NON applica automaticamente questa opzione: i calcoli
      usano sempre il costo storico reale (LIFO); eventuali
      rivalutazioni vanno gestite a parte con il commercialista;
* Quadro RW: valori posseduti e detenzione; OBBLIGATORIO anche senza
  soglia minima (Circolare AdE 30/E/2023) per chi detiene cripto;
    * IC (imposta sul valore delle cripto-attività, 0,2% al 31/12):
      imposta patrimoniale calcolata sul valore; NON dovuta se
      inferiore a 12€ (nessuna soglia di esenzione di 5.000€ per
      le cripto-attività);
    * snapshot portafoglio: consistenza per asset nel periodo;
    * valore patrimoniale REALE al 31/12: per ogni asset ancora
      detenuto, costo di carico LIFO vs valore di mercato al
      31/12, con esito NON realizzato (perdite latenti incluse,
      anche per monete fallite/delistate come LINA).

DATI DEL CONTRIBUENTE (nome, cognome, codice fiscale):
 Nel form di upload (Passo 1) puoi inserire nome, cognome e
 codice fiscale (facoltativi). Vengono mostrati nell'anteprima,
 nella sezione "Dati del Contribuente" del report e nella
 copertina del PDF per il commercialista.
 IMPORTANTE: i dati NON vengono salvati su disco: sono tenuti
 solo in memoria (RAM) e si azzerano automaticamente a OGNI
 avvio dell'app, come le transazioni.
 AVVERTENZA IMPORTANTE (calcolo corretto del LIFO): a ogni
 avvio dell'app devi RICARICARE l'INTERO storico transazionale
 (tutti i file, con tutti gli anni, dal primo acquisto), non
 solo i file dell'anno che vuoi calcolare. Se per il 2023
 carichi solo i file del 2023, i lotti acquistati negli anni
 precedenti mancano dall'inventario e le plusvalenze calcolate
 risultano sbagliate (costo di carico azzerato).

ESPORTARE IL REPORT IN PDF (per il commercialista):
 Dopo il Passo 2, nella pagina del report c'è il pulsante
 "Scarica PDF per Commercialista". Il PDF contiene:
1) Riepilogo redditi diversi (art. 67 TUIR): plusvalenze,
       minusvalenze, risultato netto, imponibile, imposta
       (26% fino al 2025, 33% dal 2026);
    2) Esito dinamico del calcolo:
        - fino al 2024: franchigia/esenzione di €2.000
          (art. 67, comma 1-ter TUIR). Sotto i €2.000 nessuna
          imposta; sopra i €2.000 imposta al 26% solo
          sull'eccedenza;
        - dal 2025: la franchigia di €2.000 è ELIMINATA
          (L. di Bilancio 2025). Ogni plusvalenza netta è
          soggetta all'imposta del 26% (anno 2025) e del 33%
          dal 2026;
        - minusvalenza: evidenzia la COMPENSABILITÀ in 4 anni
          e allega il dettaglio delle vendite come dimostranza;
    3) Quadro RW / IC: valore al 31/12, imposta 0,2% (non dovuta
       sotto 12€), scadenza versamento F24, dettaglio asset con
       prezzo reale;
   4) VALORE PATRIMONIALE REALE al 31/12: tabella per asset con
      quantità, costo di carico (LIFO), valore di mercato reale
      e esito non realizzato. Evidenzia le perdite NON realizzate
      (tassabili solo alla vendita) e documenta il patrimonio
      effettivo, incluse monete fallite come LINA (valore ~0);
   5) Note fiscali e riferimenti di legge.
 Questo PDF è pensato direttamente per il commercialista per
 la compilazione della dichiarazione (Redditi / 730).


------------------------------------------------------------
  5) COSA CONTIENE LA CARTELLA
------------------------------------------------------------
 Avvia_CriptoTaxWebApp.bat      -> avvio app su Windows
 Avvia_CriptoTaxWebApp.command  -> avvio app su Apple/macOS
 app/                          -> codice sorgente dell'app
 static/                       -> fogli di stile e JavaScript
 data/                         -> dati locali (database, cache
                                  prezzi, CSV storici)
 requirements.txt              -> elenco librerie installate
 GUIDA_USO.txt                 -> questa guida


------------------------------------------------------------
  6) RISOLUZIONE PROBLEMI
------------------------------------------------------------

 PROBLEMA: "Python non trovato"
 SOLUZIONE: installa Python e spunta "Add Python to PATH"
            (Windows); su macOS reinstallalo. Riavvia il launcher.

 PROBLEMA: il browser non si apre
 SOLUZIONE: apri manualmente http://127.0.0.1:8000

 PROBLEMA: porta 8000 già occupata
 SOLUZIONE: chiudi l'altra istanza, oppure avvia manualmente con
            un'altra porta: python -m uvicorn app.main:app --port 8001
            e apri http://127.0.0.1:8001

 PROBLEMA: "Formato CSV non supportato"
 SOLUZIONE: il CSV deve contenere almeno le colonne
            time/date, pair/market, type/side, amount.
            Esporta il Trade History, non un estratto conto.

 PROBLEMA: nessuna transazione per l'anno scelto
 SOLUZIONE: verifica che l'anno fiscale selezionato corrisponda
            alle date presenti nel CSV.

 PROBLEMA: primo avvio molto lento
 SOLUZIONE: è normale, pip sta scaricando le librerie. Attendi
            il messaggio "Uvicorn running".


------------------------------------------------------------
  7) NOTE SULLA METODOLOGIA
------------------------------------------------------------
 - Le vendite sono valorizzate con il metodo LIFO (Last In,
   First Out): il costo dei lotti venduti è quello dei lotti
   acquistati più recentemente.
 - Il calcolo usa l'INTERO storico caricato: le vendite di un
   anno usano il costo dei lotti acquistati anche negli anni
   precedenti. Per questo è importante caricare TUTTI i file
   delle operazioni (dagli inizi) in un unico upload.
 - Se una vendita avviene senza lotti acquistati precedenti,
   il gain/loss della parte non coperta è considerato pari al
   valore di vendita (costo 0): niente dati inventati.
 - I calcoli seguono la normativa fiscale italiana di
   riferimento; per casi complessi (staking, airdrop, mining,
   riacquisto a 12 mesi) consulta un commercialista.
- IMPORTANTE: i calcoli avvengono esclusivamente in locale;
    nessuno storico transazionale lascia il tuo computer.
    PERÒ: per le operazioni in USDT il controvalore viene convertito
    in EURO con il tasso USD/EUR del giorno dell'operazione fornito
    dalla BCE: per farlo l'app usa la CONNESSIONE INTERNET. Viene
    scaricato solo il tasso di cambio (mai i tuoi dati); se la rete
    non è disponibile l'app usa il tasso medio annuo e comunque
    completa il calcolo in locale.


------------------------------------------------------------
  8) I PREZZI (QUADRO RW / IC) - CHIAVI OPZIONALI
------------------------------------------------------------
Per stimare il valore del portafoglio (Quadro RW / IC)
l'app consulta i prezzi storici in quest'ordine:
   1. CoinGecko (gratuito, senza chiave: dati storici fino a
      circa 365 giorni fa)
   2. CryptoCompare (gratuito SENZA chiave: prevede dati
      storici completi. Con chiave gratuita funziona meglio)
   3. Gate.io (senza chiave)
   4. Dal TUO database di acquisti (prezzo medio pagato):
      usato quando le API non trovano l'asset o la coppia è
      stata delistata (es. BMEX, HIFI, US). La stima resta
      quindi basata sui tuoi dati reali, non su valori finti.

Se non ricorda un prezzo usa il valore 1 EUR a solo come
ultima risorsa, e lo segnala nei log.

CONFIGURARE LE CHIAVI (OPZIONALE, per dati storici migliori):
  WINDOWS: apri "Avvia_CriptoTaxWebApp.bat" con il Blocco note
           e, prima della riga che avvia uvicorn, aggiungi:
             set CRYPTOCOMPARE_API_KEY=TuaChiave
             set FIXER_API_KEY=TuaChiaveFixer
  APPLE:   apri "Avvia_CriptoTaxWebApp.command" con un editor e
           aggiungi prima dell'avvio:
             export CRYPTOCOMPARE_API_KEY="TuaChiave"
             export FIXER_API_KEY="TuaChiaveFixer"

  Dove le ottieni (gratuite):
   - CryptoCompare: https://min-api.cryptocompare.com  (chiave
     gratuita per uso personale)
   - Fixer.io: https://fixer.io (tasso USD/EUR; 100 richieste/
     mese gratis)
   - CoinGecko Premium: https://www.coingecko.com (solo se
     servono dati oltre i 365 giorni o volumi alti)

Senza chiavi l'app funziona comunque (CoinGecko + Gate.io +
   dal tuo storico acquisti). Le chiavi servono solo per avere
   prezzi ancora più completi.


------------------------------------------------------------
  9) RACCOMANDAZIONI PER LA DISTRIBUZIONE VIA USB
------------------------------------------------------------
Questa sezione è pensata per chi diffonde l'app tramite
chiavetta USB (es. a parenti o conoscenti) e per chi la
riceve.

 1. PRIVACY: come si chiude correttamente e come si cancella
    la cartella dati
    - Chiudi SEMPRE l'app chiudendo la finestra nera del
      launcher (Windows) o il Terminale/ Ctrl+C (macOS), NON
      solo la scheda del browser. Alla chiusura il database e
      le cache vengono eliminati automaticamente dal disco
      (privacy "usa e getta", vedi sezione 2).
    - Se alla chiusura compare l'AVVISO "alcuni file di runtime
      non sono stati eliminati", qualche file è rimasto bloccato:
      chiudi tutti i programmi che usano la chiavetta e cancella
      a MANO la cartella  data/  (dentro la cartella dell'app)
      prima di estrarre la chiavetta. Così non restano dati
      personali neppure come file.
    - Ricorda: i CSV che carichi restano in memoria (RAM) e si
      azzerano a ogni avvio; i dati personali non vengono salvati
      su disco (vedi sezione 3, "DATI DEL CONTRIBUENTE").

 2. USARE L'APP SOLO SU COMPUTER DI CUI SI HA PIENO CONTROLLO
    - Usa l'app su computer dedicati, propri, o di cui hai pieno
      controllo (niente computer pubblici, di biblioteca, di
      un'azienda o condivisi non fidati).
    - Non copiare i file CSV della chiavetta su computer altrui:
      contengono il tuo storico finanziario personale.
    - Se l'app viene usata su un computer condiviso, cancella la
      cartella  data/  dopo ogni utilizzo (vedi punto 1).

 3. AGGIORNAMENTO DELL'APP (semplice)
    - L'app è interamente nella cartella di distribuzione: per
      aggiornare basta SOSTITUIRE i file nuovi su quelli vecchi
      (riscrivendoci sopra), mantenendo al massimo la tua
      cartella  data/  se contiene prezzi già scaricati.
    - Per chi sa usare git: dentro la cartella dell'app eseguire
        git pull
      per portare l'ultima versione (se il progetto è distribuito
      come repository).
    - Dopo un aggiornamento, fai sempre una prova con un CSV di
      esempio: il report deve generarsi correttamente prima di
      fidarti dei risultati.

 4. VERIFICA DEI FILE CSV E BACKUP
    - Controlla SEMPRE i file CSV prima di caricarli (colonne
      corrette, niente righe vuote in coda, date nel formato
      atteso; vedi sezione 3).
    - Se i file provengono da un'altra persona, verificali tu
      stesso prima di caricarli.
    - Fai un BACKUP dei tuoi CSV originali (es. su un secondo
      supporto o in un archivio separato) prima di qualsiasi
      caricamento: l'app non modifica mai i tuoi file, ma un
      backup evita di perdere la storia transazionale per
      ricaricarla in futuro.

 5. VERSIONI CONTRAFFATTE DEL SOFTWARE
    - Ottieni l'app SOLO da fonti fidate (chi te l'ha consegnata
      personalmente, o il repository ufficiale indicato dallo
      sviluppatore), MAI da link casuali o file rinominati.
    - Se una copia arriva senza QUESTO file GUIDA_USO.txt o con
      un nome diverso dai file descritti nella sezione 5, potrebbe
      essere una versione contraffatta: NON usarla e avvisa chi
      te l'ha consegnata.
    - Dove disponibile, verifica l'integrità con il file di
      controllo (somma hash) fornito dallo sviluppatore oppure
      controlla che la firma digitale dell'archivio sia valida.

Il software NON è firmato digitalmente da una autorità di
certificazione: la sicurezza si basa sulla fonte di consegna
(punto 5) e sul fatto che tutta l'elaborazione avviene in locale.