utilities/README.md

# Fix Gaia Excel - Script Python

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

- Python 3.6 o superiore
- pip (gestore pacchetti Python)

## Installazione

### 1. Creare l'ambiente virtuale

```powershell
# Crea l'ambiente virtuale nella cartella venv
python -m venv venv
```

### 2. Attivare l'ambiente virtuale

**Su Windows (PowerShell):**
```powershell
.\venv\Scripts\Activate.ps1
```

**Su Windows (CMD):**
```cmd
.\venv\Scripts\activate.bat
```

**Su Linux/macOS:**
```bash
source venv/bin/activate
```

> **Nota:** Se ricevi un errore di policy su PowerShell, esegui:
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```

### 3. Installare le dipendenze

```powershell
pip install -r requirements.txt
```

Se il file `requirements.txt` non esiste, installa manualmente:
```powershell
pip install openpyxl
```

### 4. Generare il file requirements.txt (opzionale)

Se vuoi aggiornare il file delle dipendenze:
```powershell
pip freeze > requirements.txt
```

## Utilizzo

### Eseguire lo script

**IMPORTANTE:** Lo script deve essere eseguito con `python` esplicitamente, non direttamente come `.\fixgaiaexcel.py`:

```powershell
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:**
- Input: `data\Elenco_Soci_BLSD.xlsx`
- Output: `data\Elenco_Soci_BLSD_modificato.xlsx`

## Reinstallazione su nuovo PC

### Passaggi completi

1. **Clona o copia il progetto** sul nuovo PC

2. **Verifica che Python sia installato:**
   ```powershell
   python --version
   ```
   
   Se Python non è installato, scaricalo da [python.org](https://www.python.org/downloads/)

3. **Crea l'ambiente virtuale:**
   ```powershell
   python -m venv venv
   ```

4. **Attiva l'ambiente virtuale:**
   ```powershell
   .\venv\Scripts\Activate.ps1
   ```

5. **Installa le dipendenze:**
   ```powershell
   pip install -r requirements.txt
   ```

6. **Verifica l'installazione:**
   ```powershell
   pip list
   ```
   
   Dovresti vedere `openpyxl` nella lista dei pacchetti installati.

7. **Testa lo script:**
   ```powershell
   python fixgaiaexcel.py --help
   ```

## Struttura del progetto

## Troubleshooting

### Errore: "ModuleNotFoundError: No module named 'openpyxl'"

**Causa:** Lo script viene eseguito con il Python di sistema invece che con quello del venv.

**Soluzione:** Usa sempre `python` esplicitamente:
```powershell
# ✓ CORRETTO
python fixgaiaexcel.py file.xlsx

# ✗ SBAGLIATO (usa l'interprete di sistema)
.\fixgaiaexcel.py file.xlsx
```

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 nella prima riga. Verifica che il file Excel contenga la colonna "Titoli - Operativita - Data ottenimento - Data scadenza" nella prima riga.

### Errore di policy PowerShell
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

# 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

Quando hai finito di lavorare:
```powershell
deactivate
```

## Note

- L'ambiente virtuale (`venv/`) non dovrebbe essere committato in git. Aggiungi al `.gitignore`:
  ```
  venv/
  __pycache__/
  *.pyc
  ```

- Il file `requirements.txt` dovrebbe essere committato per facilitare l'installazione su altri PC.