Aggiorna la documentazione del README per chiarire l'utilizzo dello script e le opzioni disponibili; migliora la sezione di troubleshooting.

README.md

@@ -1,6 +1,11 @@
 # Fix Gaia Excel - Script Python
 
-Script per leggere e processare file Excel con struttura specifica, cercando e estraendo dati dalla colonna "Titoli - Operativita - Data ottenimento - Data scadenza".
+Script per processare file Excel contenenti dati di titoli e qualifiche.
+
+Lo script cerca la colonna "Titoli - Operativita - Data ottenimento - Data scadenza", estrae le qualifiche e le date, e aggiunge due nuove colonne al file Excel con dati puliti e normalizzati.
+
+**Autore:** Luigi D'Acunto  
+**Data:** 25 novembre 2025
 
 ## Requisiti
 
@@ -60,45 +65,54 @@ pip freeze > requirements.txt
 
 ### Eseguire lo script
 
+**IMPORTANTE:** Lo script deve essere eseguito con `python` esplicitamente, non direttamente come `.\fixgaiaexcel.py`:
+
 ```powershell
-python fixgaiaexcel.py <percorso_file_excel>
+python fixgaiaexcel.py <percorso_file_excel> [opzioni]
 ```
 
+### Opzioni disponibili
+
+#### Modalità data più vecchia (default)
+```powershell
+python fixgaiaexcel.py "data\report.xlsx"
+```
+
+#### Modalità data più recente
+```powershell
+python fixgaiaexcel.py "data\report.xlsx" --data-recente
+```
+oppure (forma breve):
+```powershell
+python fixgaiaexcel.py "data\report.xlsx" --recente
+```
+
+#### Visualizzare l'help completo
+```powershell
+python fixgaiaexcel.py --help
+```
+
+### Cosa fa lo script
+
+1. Apre il file Excel specificato
+2. Cerca la colonna "Titoli - Operativita - Data ottenimento - Data scadenza"
+3. Per ogni riga con dati:
+   - Estrae la qualifica (testo senza date dalla prima riga della cella)
+   - Estrae tutte le date in formato aaaa-mm-gg
+   - Seleziona la data più vecchia (o più recente se specificato)
+4. Aggiunge due nuove colonne:
+   - **"Qualifica"**: testo pulito della qualifica
+   - **"Data"**: data selezionata secondo il criterio
+5. Salva un nuovo file con suffisso "_modificato"
+
+### File di output
+
+Il file originale **non viene modificato**.  
+Viene creato un nuovo file: `nomefile_modificato.xlsx`
+
 **Esempio:**
-```powershell
+- Input: `data\Elenco_Soci_BLSD.xlsx`
-python fixgaiaexcel.py data\report.xlsx
+- Output: `data\Elenco_Soci_BLSD_modificato.xlsx`
-```
-
-### Output
-
-Lo script:
-1. Apre il file Excel specificato
-2. Cerca la colonna con intestazione "Titoli - Operativita - Data ottenimento - Data scadenza"
-3. Estrae e stampa tutti i dati sotto quella colonna
-4. Mostra il conteggio totale degli elementi trovati
-
-### Esempio di output
-
-```
-Apertura file: data\report.xlsx
-----------------------------------------------------------------------
-Foglio attivo: Foglio1
-Dimensioni: 150 righe x 10 colonne
-----------------------------------------------------------------------
-Colonna target trovata: posizione 5
-Intestazione: Titoli - Operativita - Data ottenimento - Data scadenza
-----------------------------------------------------------------------
-
-Dati trovati (10 elementi):
-
-    1. Valore 1
-    2. Valore 2
-    3. Valore 3
-    ...
-
-----------------------------------------------------------------------
-Totale elementi letti: 10
-```
 
 ## Reinstallazione su nuovo PC
 
@@ -142,28 +156,66 @@ Totale elementi letti: 10
 
 ## Struttura del progetto
 
-```
+## Troubleshooting
-cripy/
+
-├── venv/                  # Ambiente virtuale (NON committare in git)
+### Errore: "ModuleNotFoundError: No module named 'openpyxl'"
-├── data/                  # Cartella per i file Excel
+
-├── fixgaiaexcel.py        # Script principale
+**Causa:** Lo script viene eseguito con il Python di sistema invece che con quello del venv.
-├── requirements.txt       # Dipendenze Python
+
-└── README.md             # Questo file
+**Soluzione:** Usa sempre `python` esplicitamente:
+```powershell
+# ✓ CORRETTO
+python fixgaiaexcel.py file.xlsx
+
+# ✗ SBAGLIATO (usa l'interprete di sistema)
+.\fixgaiaexcel.py file.xlsx
 ```
 
-## Troubleshooting
+Verifica che il venv sia attivo (dovresti vedere `(venv)` nel prompt):
+```powershell
+# Se non è attivo, attivalo
+.\venv\Scripts\Activate.ps1
+```
 
 ### Errore: "Il file non esiste"
 Verifica che il percorso del file Excel sia corretto e che il file esista.
 
 ### Errore: "Colonna non trovata"
-Lo script cerca l'intestazione esatta nella prima riga. Verifica che il file Excel contenga la colonna "Titoli - Operativita - Data ottenimento - Data scadenza" nella prima riga.
+Lo script cerca l'intestazione nella prima riga. Verifica che il file Excel contenga la colonna "Titoli - Operativita - Data ottenimento - Data scadenza" nella prima riga.
 
-### Errore di importazione openpyxl
+### Errore di policy PowerShell
-Assicurati di aver attivato l'ambiente virtuale e installato le dipendenze:
+Se ricevi un errore durante l'attivazione del venv:
 ```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+## Note
+
+- **Esecuzione dello script:** Usa sempre `python fixgaiaexcel.py` invece di `.\fixgaiaexcel.py` per assicurarti di usare l'interprete Python del venv.
+
+- L'ambiente virtuale (`venv/`) non dovrebbe essere committato in git. È già escluso dal `.gitignore`.
+
+- Il file `requirements.txt` è committato per facilitare l'installazione su altri PC.
+
+- I file Excel in `data/` sono esclusi dal git per proteggere dati sensibili.
+
+## Esempi completi
+
+### Workflow tipico
+
+```powershell
+# 1. Attiva l'ambiente virtuale
 .\venv\Scripts\Activate.ps1
-pip install openpyxl
+
+# 2. Processa un file (data più vecchia)
+python fixgaiaexcel.py ".\data\Elenco_Soci_BLSD.xlsx"
+
+# 3. Processa un file (data più recente)
+python fixgaiaexcel.py ".\data\Elenco_Soci_OPEM.xlsx" --data-recente
+
+# 4. Visualizza l'help
+python fixgaiaexcel.py --help
+
+# 5. Quando hai finito
+deactivate
 ```
 
 ## Disattivare l'ambiente virtuale