Data-Coupler/CSV_SCHEDULING_IMPLEMENTATION.md

# Implementazione Schedulazione File CSV/Excel

## Data
24 Gennaio 2026

## Panoramica
Implementata la funzionalità completa di schedulazione per profili che utilizzano file CSV o Excel come sorgente dati. Precedentemente questa funzionalità era disattivata per motivi di sicurezza, ora è completamente funzionale con validazioni appropriate.

## Modifiche Implementate

### 1. Validazione File CSV nel Salvataggio Profilo
**File**: `Data_Coupler/Pages/DataCoupler.razor.cs`

**Modifica**: Aggiunta validazione nel metodo `OnProfileSaved` per verificare che:
- Il file CSV/Excel specificato esista nel filesystem
- Il file sia leggibile dall'applicazione

**Implementazione**:
```csharp
// Validazione specifica per file CSV
if (profile.SourceType == "file" && !string.IsNullOrEmpty(profile.SourceFilePath))
{
    // Verifica esistenza
    if (!System.IO.File.Exists(profile.SourceFilePath))
    {
        await JSRuntime.InvokeVoidAsync("alert", 
            "Errore: Il file non esiste o non è accessibile.");
        return;
    }

    // Verifica leggibilità
    try
    {
        using var fs = System.IO.File.OpenRead(profile.SourceFilePath);
        fs.Close();
    }
    catch (Exception fileEx)
    {
        await JSRuntime.InvokeVoidAsync("alert", 
            $"Errore: Il file non può essere letto. Dettagli: {fileEx.Message}");
        return;
    }
}
```

**Benefici**:
- Previene errori durante l'esecuzione schedulata
- Fornisce feedback immediato all'utente in fase di configurazione
- Verifica i permessi di lettura del file

---

### 2. Implementazione Lettura File per Schedulazioni
**File**: `Data_Coupler/Services/ScheduledProfileExecutionService.cs`

**Modifica**: Implementati i seguenti metodi per la lettura di file CSV e Excel:

#### Metodi Implementati:

1. **`GetAllRecordsFromFileAsync`** - Metodo principale
   - Determina il tipo di file (CSV, XLSX, XLS)
   - Verifica esistenza del file
   - Delega alla funzione appropriata

2. **`ReadCsvFileAsync`** - Lettura file CSV
   - Rilevamento automatico del separatore (`,`, `;`, `\t`, `|`)
   - Parsing corretto con gestione virgolette
   - Supporto per file di grandi dimensioni

3. **`ReadExcelFileAsync`** - Lettura file Excel
   - Supporto per formati `.xlsx` e `.xls`
   - Utilizzo di `ExcelDataReader` library
   - Registrazione encoding provider (`System.Text.CodePagesEncodingProvider`)
   - Lettura del primo foglio Excel

4. **Helper Methods**:
   - `DetectCsvSeparator`: Rilevamento automatico separatore CSV
   - `ParseCsvLine`: Parsing linea CSV con gestione quote e escape

**Esempio di utilizzo**:
```csharp
private async Task<IEnumerable<Dictionary<string, object>>> GetAllRecordsFromSourceAsync(
    DataCouplerProfile profile, IDatabaseManager? databaseManager)
{
    if (profile.SourceType.ToLower() == "file")
    {
        return await GetAllRecordsFromFileAsync(profile);
    }
    // ... altri tipi
}
```

**Caratteristiche**:
- Supporto completo per CSV con separatori multipli
- Gestione corretta di campi con virgolette e caratteri speciali
- Parsing robusto con logging dettagliato
- Compatibilità con file Excel legacy (.xls) e moderni (.xlsx)

---

### 3. Abilitazione Profili File nella Schedulazione
**File**: `Data_Coupler/Pages/Scheduling.razor`

**Modifica**: Rimosso il filtro `Where(p => p.SourceType != "file")` che escludeva i profili file dalla lista di schedulazione.

**Prima**:
```csharp
@foreach (var profile in availableProfiles.Where(p => p.SourceType != "file"))
{
    <option value="@profile.Id">@profile.Name</option>
}
```

**Dopo**:
```csharp
@foreach (var profile in availableProfiles)
{
    <option value="@profile.Id">@profile.Name @(profile.SourceType == "file" ? "(File)" : "")</option>
}
```

**Miglioramenti UI**:
- Etichetta `(File)` per identificare profili con file
- Messaggio informativo aggiornato:
  > ℹ️ I profili con file CSV/Excel come sorgente sono ora supportati per le schedulazioni.
  > Il file specificato nel profilo verrà letto ad ogni esecuzione.

---

### 4. Gestione Cancellazioni per File CSV
**Implementazione**: La gestione delle cancellazioni opzionali funziona automaticamente anche per i profili file grazie all'architettura esistente.

**Flusso**:
1. I record vengono letti dal file CSV/Excel
2. Vengono trasformati in `Dictionary<string, object>` come i record database
3. Il sistema di associazioni (`KeyAssociationService`) traccia i record
4. Se abilitato, il `DeletionSyncService` sincronizza le eliminazioni

**Compatibilità**:
- ✅ Supporto completo per `EnableDeletionSync` flag
- ✅ Tracking chiavi sorgente (`SourceKeyField`)
- ✅ Sistema di associazioni record
- ✅ Pre-discovery di record esistenti

---

## Gestione File per Schedulazioni

### Due Modalità di Caricamento

#### 1. **Caricamento Browser** (per Preview)
- **Scopo**: Configurare mapping e vedere anteprima dati
- **Funzionamento**: 
  - File caricato tramite browser (InputFile component)
  - Processato in memoria
  - **Non salvato sul server**
- **Uso**: Solo per configurazione iniziale del profilo

#### 2. **Percorso Manuale** (per Schedulazione) ⭐
- **Scopo**: Specificare posizione file per schedulazioni
- **Funzionamento**:
  - Utente inserisce percorso completo (es: `C:\Data\products.csv`)
  - Sistema valida esistenza e leggibilità
  - Percorso salvato nel profilo
- **Uso**: **Obbligatorio** per profili che devono essere schedulati

### Esempi di Percorsi Validi

**Windows**:
```
C:\Data\products.csv
\\server\share\customers.xlsx
D:\ImportFiles\orders.csv
```

**Linux/Container**:
```
/data/products.csv
/mnt/share/customers.xlsx
/app/import/orders.csv
```

### Workflow Completo

1. **Configurazione Iniziale**:
   - Carica file da browser per preview
   - Configura mapping campi vedendo i dati reali
   - **Importante**: Questo file è solo temporaneo

2. **Preparazione Schedulazione**:
   - Posiziona il file nella location definitiva sul server
   - Inserisci il percorso completo nel campo "Percorso File sul Server"
   - Clicca "Valida e Carica" per verificare
   - Salva il profilo

3. **Esecuzione Schedulata**:
   - Il sistema legge il file dal percorso salvato
   - Il file deve esistere e essere accessibile
   - Aggiornamenti al file vengono letti automaticamente

### Considerazioni Importanti

**Sicurezza**:
- Il file deve essere accessibile dal processo dell'applicazione
- Verificare permessi di lettura sulla directory
- Per ambienti multi-utente, considerare ACL appropriati

**Percorsi Relativi vs Assoluti**:
- **Consigliato**: Percorsi assoluti per chiarezza
- Se si usano percorsi relativi, sono relativi alla working directory dell'applicazione

**Aggiornamento File**:
- Il sistema legge sempre il file corrente dal percorso
- Per aggiornare i dati, basta sovrascrivere il file nella stessa posizione
- Non serve modificare il profilo se il percorso rimane invariato

**Deployment Container**:
- Montare volumi per directory contenenti i file
- Esempio docker-compose:
  ```yaml
  volumes:
    - /host/data:/data  # Monta directory host in /data nel container
  ```
- Nel profilo usare: `/data/products.csv`

**Best Practices**:
- ✅ Usare una directory dedicata per file di import (es: `/data/imports/`)
- ✅ Nominare i file in modo descrittivo
- ✅ Implementare rotazione/backup dei file
- ✅ Monitorare spazio disco
- ❌ Non usare directory temporanee che vengono pulite
- ❌ Non usare percorsi di rete senza verifica connessione

---

## Funzionamento Completo

### Creazione Profilo con File CSV
1. L'utente seleziona "File" come tipo sorgente
2. **Opzione A - Caricamento Browser (per preview)**:
   - Carica un file CSV/Excel tramite browser
   - Il file viene processato in memoria per preview
   - Permette di configurare il mapping vedendo i dati reali
   - **Non viene salvato sul server** - solo per anteprima

3. **Opzione B - Percorso Manuale (richiesto per schedulazione)**:
   - Inserisce il percorso completo del file sul server (es: `C:\Data\products.csv`)
   - Clicca "Valida e Carica" per:
     - Verificare che il file esista
     - Verificare che sia leggibile
     - Caricare preview per configurare mapping
   - Il percorso viene salvato nel profilo

4. L'utente configura il mapping campi
5. **Salvataggio**: Il sistema valida che il file sia accessibile e leggibile
6. Il **percorso completo originale** del file viene salvato in `SourceFilePath`

**Nota Importante**: Per le schedulazioni è **necessario** specificare il percorso file manualmente. Il file deve essere accessibile dal server nella posizione specificata.

### Schedulazione Profilo File
1. L'utente crea una nuova schedulazione
2. Seleziona un profilo con `SourceType = "file"`
3. Configura la frequenza (giornaliera, settimanale, intervallo, ecc.)
4. Abilita opzionalmente `EnableDeletionSync` per sincronizzare eliminazioni

### Esecuzione Schedulata
1. Il background service avvia l'esecuzione alla schedulazione prevista
2. `ScheduledProfileExecutionService.ExecuteProfileAsync` viene chiamato
3. Il servizio legge il file dal percorso salvato usando `GetAllRecordsFromFileAsync`
4. I record vengono trasformati e inviati alla destinazione REST
5. Il sistema di associazioni traccia i record per evitare duplicati
6. Se configurato, vengono sincronizzate le eliminazioni

---

## Sicurezza e Validazioni

### Validazioni Implementate:
- ✅ Verifica esistenza file prima del salvataggio profilo
- ✅ Verifica permessi di lettura file
- ✅ Gestione eccezioni durante la lettura file
- ✅ Logging dettagliato per troubleshooting
- ✅ Validazione formato file (CSV, XLSX, XLS)

### Considerazioni di Sicurezza:
- Il file deve essere accessibile dal processo dell'applicazione
- Percorsi assoluti sono salvati nel database
- Per ambienti containerizzati, montare volumi con i file
- Permessi filesystem devono consentire lettura

---

## Formati File Supportati

### CSV
- **Separatori**: `,` (virgola), `;` (punto e virgola), `\t` (tab), `|` (pipe)
- **Rilevamento automatico**: Sì
- **Gestione quote**: Supporto completo per campi tra virgolette
- **Escape caratteri**: Supporto per `""` (double quote escape)
- **Dimensione massima**: 50 MB (configurabile)

### Excel
- **Formati**: `.xlsx` (Office Open XML), `.xls` (Binary Format)
- **Fogli multipli**: Legge il primo foglio per default
- **Header**: Prima riga utilizzata come intestazione
- **Dimensione massima**: 50 MB (configurabile)

---

## Esempi di Utilizzo

### Esempio 1: Schedulazione Giornaliera CSV
```
Profilo: "Import Prodotti da CSV"
- Sorgente: File CSV (products.csv)
- Destinazione: REST API (Salesforce)
- SourceKeyField: "ProductCode"
- UseRecordAssociations: true

Schedulazione: "Import Prodotti Quotidiano"
- Tipo: Daily (Giornaliera)
- Ora: 08:00
- EnableDeletionSync: false
```

**Comportamento**: Ogni giorno alle 08:00, il sistema legge `products.csv`, trasforma i dati secondo il mapping configurato, e li invia a Salesforce. I record esistenti vengono aggiornati, i nuovi creati.

### Esempio 2: Sincronizzazione con Eliminazioni
```
Profilo: "Sincronizza Clienti Excel"
- Sorgente: File Excel (customers.xlsx)
- Destinazione: REST API (SAP Business One)
- SourceKeyField: "CustomerID"
- UseRecordAssociations: true

Schedulazione: "Sync Clienti Settimanale"
- Tipo: Weekly (Settimanale)
- Giorno: Lunedì
- Ora: 06:00
- EnableDeletionSync: true
```

**Comportamento**: Ogni lunedì alle 06:00, il sistema:
1. Legge `customers.xlsx`
2. Sincronizza i clienti con SAP Business One
3. Identifica clienti eliminati dal file
4. Elimina i corrispondenti record in SAP B1

---

## Testing e Validazione

### Test Consigliati:
1. **Test file CSV con separatori diversi**
   - Comma-separated
   - Semicolon-separated
   - Tab-separated

2. **Test file Excel**
   - Formato .xlsx moderno
   - Formato .xls legacy
   - Fogli con molte colonne/righe

3. **Test errori**
   - File non esistente
   - File senza permessi di lettura
   - File corrotto
   - File troppo grande

4. **Test schedulazione**
   - Esecuzione immediata manuale
   - Esecuzione automatica schedulata
   - Verifica storico esecuzioni
   - Test con `EnableDeletionSync` attivo

---

## Limitazioni Note

1. **Fogli Excel**: Attualmente viene letto solo il primo foglio del file Excel
2. **Dimensione file**: Limite di 50 MB per sicurezza (configurabile in codice)
3. **Percorsi assoluti**: I file devono essere accessibili tramite percorso assoluto
4. **Encoding**: Supporto per encoding standard (UTF-8, Windows-1252)

---

## Prossimi Sviluppi Potenziali

- [ ] Supporto per lettura di fogli Excel multipli
- [ ] Configurazione dinamica del foglio Excel da leggere
- [ ] Supporto per file remoti (HTTP, FTP, Azure Blob)
- [ ] Cache intelligente per file grandi non modificati
- [ ] Validazione schema file prima dell'esecuzione
- [ ] Notifiche in caso di file non trovato durante schedulazione

---

## Conclusioni

L'implementazione della schedulazione per file CSV/Excel è ora completa e robusta. La funzionalità include:

✅ Validazione completa del file in fase di configurazione  
✅ Lettura affidabile di CSV con separatori multipli  
✅ Supporto per file Excel moderni e legacy  
✅ Integrazione completa con sistema di associazioni  
✅ Supporto per sincronizzazione eliminazioni opzionale  
✅ Logging dettagliato per troubleshooting  
✅ Error handling robusto  

Gli utenti possono ora schedulare trasferimenti dati da file CSV/Excel esattamente come farebbero con sorgenti database, con le stesse funzionalità avanzate di tracking record e sincronizzazione.