[Feature] Implementata schedulazione completa per file CSV/Excel

- Aggiunta validazione percorsi file prima del salvataggio profili - Implementati metodi di lettura file CSV e Excel per schedulazioni - Supporto doppia modalità: caricamento browser (preview) e percorso manuale (schedulazione) - Gestione completa deletion sync anche per file CSV/Excel - Rilevamento automatico separatori CSV (virgola, punto e virgola, tab, pipe) - Supporto formati Excel legacy (.xls) e moderni (.xlsx) - Abilitati profili file nella UI di schedulazione - Logging dettagliato per troubleshooting - Documentazione completa in CSV_SCHEDULING_IMPLEMENTATION.md - Aggiornati README.md e copilot-instructions.md con nuove feature - Rimosso testo 'TEST' dalla pagina di login
2026-01-25 12:45:32 +01:00
parent a5f2f79fac
commit a5f8943c72
12 changed files with 1040 additions and 40 deletions
@@ -0,0 +1,410 @@
+# 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.