Data-Coupler/.github/copilot-instructions.md

# Data-Coupler - GitHub Copilot Instructions

## 📋 Panoramica del Progetto

**Data-Coupler** è una soluzione enterprise di integrazione dati sviluppata in .NET 9.0 con architettura Blazor Server. Il sistema facilita il trasferimento e la sincronizzazione di dati tra diverse tipologie di sorgenti: database relazionali, REST API, file Excel/CSV con funzionalità avanzate di mapping, scheduling e gestione associazioni.

## 🏗️ Architettura del Sistema

### Progetti Principali

1. **CredentialManager** - Libreria per gestione sicura delle credenziali
   - Crittografia dei dati sensibili con Data Protection API
   - Persistenza su database SQLite
   - Supporto per credenziali database e REST API
   - Gestione profili Data Coupler e schedulazioni

2. **DataConnection** - Libreria per connessioni dati
   - **Database supportati**: SQL Server, MySQL, PostgreSQL, Oracle, SQLite, IBM DB2, SAP HANA
   - **REST API**: Generic REST, Salesforce, SAP Business One Service Layer
   - Factory pattern per gestione provider
   - Operazioni batch e parallel processing

3. **Data_Coupler** - Applicazione Blazor Server
   - Interfaccia web per gestione credenziali e profili
   - Sistema di trasferimento dati con mapping intelligente
   - Schedulazione avanzata con background services
   - Sistema di backup e ripristino completo

4. **Components** - Libreria componenti UI riutilizzabili
   - Componenti Blazor per gestione profili
   - Selettori e editor configurazioni
   - UI responsive con Bootstrap 5

## 🎯 Feature Implementate

### 1. Gestione Credenziali Sicura

#### Caratteristiche:
- **Crittografia**: Password e chiavi API crittografate con `IDataProtectionProvider`
- **Multi-piattaforma**: Supporto per database eterogenei e REST API
- **Test Connessioni**: Validazione credenziali prima del salvataggio
- **CRUD Completo**: Interfaccia web per gestione completa

#### File Chiave:
- `CredentialManager/Services/ICredentialService.cs`
- `CredentialManager/Services/EncryptionService.cs`
- `Data_Coupler/Pages/CredentialManagement.razor`

### 2. Sistema di Profili Data Coupler

#### Caratteristiche:
- **Profili Riutilizzabili**: Configurazioni salvate per trasferimenti ricorrenti
- **Mapping Campi**: Sistema avanzato di mappatura tra sorgente e destinazione
- **Sorgenti Multiple**: Database, REST API, File (Excel/CSV)
- **Gestione Completa**: CRUD con validazione e test

#### Componenti:
- **Sorgente**: Tipo (Database/REST/File), credenziale, tabella/endpoint/percorso file
- **Destinazione**: Tipo, credenziale, tabella/endpoint
- **Mapping**: Corrispondenza campi sorgente → destinazione
- **Chiave Sorgente**: Campo identificativo univoco per tracking

#### File Chiave:
- `CredentialManager/Models/DataCouplerProfile.cs`
- `CredentialManager/Services/DataCouplerProfileService.cs`
- `Data_Coupler/Pages/ProfilesManagement.razor`

### 3. Sistema di Associazioni Record (Key Associations)

#### Caratteristiche:
- **Tracciamento ID**: Memorizza relazione tra chiavi sorgente e ID destinazione
- **Prevenzione Duplicati**: Verifica esistenza prima di creare nuovi record
- **Pre-Discovery**: Cerca record esistenti nella destinazione prima della creazione
- **Hash Comparison**: Rileva modifiche dati tramite hash SHA256
- **Validazione Intelligente**: Verifica esistenza ID destinazione, cleanup automatico

#### Flusso Operativo:
1. Estrazione record da sorgente
2. Verifica associazione esistente in locale
3. **PRE-DISCOVERY**: Se non esiste, cerca nella destinazione tramite chiave
4. Se trovato → Crea associazione + Aggiorna record
5. Se non trovato → Crea nuovo record + Associazione
6. Calcola hash dati per tracking modifiche future

#### File Chiave:
- `CredentialManager/Models/KeyAssociation.cs`
- `CredentialManager/Services/KeyAssociationService.cs`
- `Data_Coupler/Pages/KeyAssociations.razor`
- `Data_Coupler/Services/AssociationService.cs`

#### Gestione Avanzata:
- **Pulizia Selettiva**: Elimina associazioni per sorgente/destinazione specifica
- **Pulizia Totale**: Reset completo sistema associazioni
- **Validazione**: Trova e pulisce associazioni con ID non più validi
- **Export/Import**: CSV per backup e migrazione dati

### 4. Trasferimento Dati Avanzato

#### Caratteristiche Standard:
- **Mapping Automatico**: Trasformazione campi sorgente → destinazione
- **Batch Processing**: Elaborazione ottimizzata per grandi volumi
- **Error Handling**: Gestione errori robusta con retry logic
- **Logging Dettagliato**: Tracciamento completo operazioni

#### Salesforce Composite API:
- **Batch Operations**: Fino a 25 operazioni per request (limite Salesforce)
- **Parallel Processing**: Elaborazione parallela batch multipli
- **Performance**: 10-25x più veloce per grandi dataset
- **Riduzione API Calls**: 60-90% in meno chiamate

#### Metodi Batch Implementati:
- `BatchExecuteQueriesAsync`: Esecuzione parallela multiple query SOQL
- `BatchFindEntitiesByKeysAsync`: Ricerca batch entità con diverse chiavi
- `BatchGetEntitiesByIdsAsync`: Recupero batch tramite ID (max 200 per query)
- `ExtractAllEntitiesAsync`: Estrazione completa con paginazione automatica
- `ExtractEntitiesParallelAsync`: Estrazione parallela con deduplicazione
- `ExtractLargeDatasetAsync`: Estrattore intelligente con auto-detect strategia
- `ExtractRecentlyModifiedAsync`: Sincronizzazione incrementale

#### File Chiave:
- `Data_Coupler/Pages/DataCoupler.razor.cs`
- `DataConnection/REST/Implementations/SalesforceServiceClient.cs`
- `Data_Coupler/Services/ScheduledProfileExecutionService.cs`

### 5. Sistema di Schedulazione Avanzata

#### Tipi di Schedulazione:
1. **Una Volta (Once)**: Esecuzione singola a data/ora specifica
2. **Giornaliera (Daily)**: Ogni giorno a orario specifico
3. **Settimanale (Weekly)**: Ogni settimana in giorno specifico
4. **Mensile (Monthly)**: Ogni mese in giorno specifico
5. **A Intervalli (Interval)**: Ricorrente ogni N unità di tempo
   - Secondi, Minuti, Ore, Giorni, Settimane, Mesi
   - Esempio: Ogni 5 minuti, ogni 2 ore, ogni 30 secondi

#### Componenti Sistema:
- **ProfileSchedule**: Modello dati schedulazione
- **ScheduledExecutionBackgroundService**: Background service per esecuzione automatica
- **ScheduledProfileExecutionService**: Logica completa trasferimento schedulato
- **ProfileScheduleService**: CRUD e gestione schedule

#### Funzionalità:
- **Esecuzione Automatica**: Background service sempre attivo
- **Gestione Stato**: Tracciamento esecuzioni (success, failed, running)
- **Storico Esecuzioni**: Log completo con timestamp, record processati, errori
- **Pausa/Riprendi**: Controllo dinamico schedulazioni
- **Override Database**: Possibilità di sovrascrivere sorgente/destinazione
- **Deletion Sync Configurabile**: Opzione per abilitare sincronizzazione eliminazioni (disabilitata di default)
- **Supporto File CSV/Excel**: Schedulazione completa per profili con file come sorgente
- **Validazione File**: Verifica esistenza e leggibilità file prima dell'esecuzione

#### File Chiave:
- `CredentialManager/Models/ProfileSchedule.cs`
- `CredentialManager/Services/ProfileScheduleService.cs`
- `Data_Coupler/BackgroundServices/ScheduledExecutionBackgroundService.cs`
- `Data_Coupler/Pages/Scheduling.razor`
- `Data_Coupler/Pages/SchedulingHistory.razor`

### 6. Sistema di Backup e Ripristino

#### Funzionalità Export:
- **Configurazione Flessibile**: Export selettivo per componente
- **Componenti Supportati**:
  - Profili Data Coupler
  - Credenziali (senza dati sensibili)
  - Associazioni Chiavi
  - Schedulazioni
- **Formato JSON**: Leggibile e versionato
- **Metadati**: Timestamp, utente, descrizione, componenti inclusi

#### Funzionalità Import:
- **Validazione Rigorosa**: Controllo formato, versione, integrità dati
- **Modalità Ripristino**:
  - **Overwrite**: Sostituisce dati esistenti
  - **Merge**: Integra con dati esistenti
  - **Preview**: Mostra anteprima senza eseguire
- **Transazioni Sicure**: Rollback automatico in caso di errori

#### Sicurezza:
- **Esclusione Dati Sensibili**: Password e API keys non inclusi in backup
- **Crittografia Opzionale**: Backup crittografati per sicurezza extra
- **Audit Logging**: Tracciamento completo operazioni backup/restore

#### File Chiave:
- `Data_Coupler/Services/BackupService.cs`
- `Data_Coupler/Models/BackupModels.cs`
- `Data_Coupler/Pages/SettingsPage.razor`

### 7. Sincronizzazione Eliminazioni (Deletion Sync)

#### Caratteristiche:
- **Rilevamento Eliminazioni**: Identifica record eliminati da sorgente
- **Sincronizzazione Automatica**: Elimina corrispondenti in destinazione
- **Gestione Associazioni**: Aggiorna/elimina associazioni correlate
- **Modalità Sicura**: Preview eliminazioni prima dell'esecuzione
- **Logging Completo**: Traccia tutte le operazioni di eliminazione
- **Configurazione Granulare**:
  - **Disabilitata** completamente nei trasferimenti manuali (DataCoupler.razor)
  - **Configurabile** nelle schedulazioni tramite flag `EnableDeletionSync`
  - **Default: false** per massima sicurezza
  - Warning esplicito nell'UI per operazioni critiche

#### Sicurezza:
- La funzionalità è **disabilitata di default** per evitare eliminazioni accidentali
- Disponibile **solo per le schedulazioni** con configurazione esplicita
- L'utente deve attivamente abilitare la funzione con piena consapevolezza
- Logging completo di tutte le operazioni di eliminazione per audit trail

#### File Chiave:
- `Data_Coupler/Services/DeletionSyncService.cs`
- `Data_Coupler/Services/ScheduledProfileExecutionService.cs`
- `CredentialManager/Models/ProfileSchedule.cs` (campo `EnableDeletionSync`)
- `Data_Coupler/Pages/Scheduling.razor` (UI configurazione)

### 8. Sistema di Autenticazione

#### Caratteristiche:
- **Login Protetto**: Autenticazione via credenziali o token
- **Session Management**: Gestione sessioni utente
- **Password Sicure**: Hashing con algoritmi moderni
- **Remember Me**: Persistenza login opzionale

#### File Chiave:
- `Data_Coupler/Services/AuthenticationService.cs`
- `Data_Coupler/Pages/Login.razor`
- `Data_Coupler/Middleware/AuthenticationMiddleware.cs`

### 9. Interfaccia Utente Avanzata

#### Pagine Principali:
- **Dashboard** (`Index.razor`): Panoramica sistema e quick actions
- **Data Coupler** (`DataCoupler.razor`): Interfaccia principale trasferimento dati
- **Gestione Profili** (`ProfilesManagement.razor`): CRUD profili completo
- **Schedulazione** (`Scheduling.razor`): Gestione schedule con UI intuitiva
- **Storico Schedulazioni** (`SchedulingHistory.razor`): Visualizzazione esecuzioni
- **Associazioni** (`KeyAssociations.razor`): Gestione completa associazioni
- **Credenziali** (`CredentialManagement.razor`): CRUD credenziali
- **Impostazioni** (`SettingsPage.razor`): Backup, sistema, sicurezza, manutenzione

#### Componenti UI:
- **ProfileSelector**: Selezione e caricamento profili
- **ProfileSaver**: Salvataggio profili con validazione
- **ProfileManagement**: CRUD profili completo
- **Toast Notifications**: Feedback utente in tempo reale
- **Modal Dialogs**: Conferme operazioni critiche
- **Progress Indicators**: Feedback operazioni lunghe

#### Design:
- **Bootstrap 5**: Framework CSS responsive
- **Font Awesome**: Iconografia consistente
- **Dark/Light Mode**: Temi personalizzabili
- **Mobile Responsive**: Ottimizzato per dispositivi mobili

### 10. Gestione File per Schedulazioni

#### Caratteristiche:
- **Doppia Modalità Caricamento**: Browser (preview) + percorso manuale (schedulazione)
- **Validazione Percorsi**: Verifica esistenza e permessi lettura file
- **Supporto CSV**: Rilevamento automatico separatori, gestione quote e escape
- **Supporto Excel**: Formati .xlsx e .xls, lettura automatica primo foglio
- **Schedulazione Completa**: File CSV/Excel utilizzabili in schedulazioni automatiche
- **Logging Dettagliato**: Tracciamento lettura file e parsing

#### Modalità Operative:

**Caricamento Browser (Preview)**:
- Carica file tramite InputFile component
- Processato in memoria per anteprima
- Non salvato sul server
- Utilizzato solo per configurazione mapping

**Percorso Manuale (Schedulazione)**:
- Campo "Percorso File sul Server" obbligatorio
- Validazione esistenza e leggibilità
- Percorso salvato in `SourceFilePath` del profilo
- Utilizzato per esecuzioni schedulate
- Esempi: `C:\Data\products.csv`, `/data/customers.xlsx`

#### File Chiave:
- `Data_Coupler/Pages/DataCoupler.razor` (UI caricamento file)
- `Data_Coupler/Pages/DataCoupler.razor.cs` (validazione file)
- `Data_Coupler/Services/ScheduledProfileExecutionService.cs` (lettura file schedulazioni)
- `CSV_SCHEDULING_IMPLEMENTATION.md` (documentazione completa)

### 11. Health Checks e Monitoraggio

#### Caratteristiche:
- **Health Checks**: Endpoint per monitoraggio stato applicazione
- **Database Health**: Verifica connessione database
- **Background Services**: Stato background services
- **Memory Monitoring**: Tracciamento utilizzo memoria
- **Performance Metrics**: Statistiche performance sistema

#### File Chiave:
- `Data_Coupler/HealthChecks/DatabaseHealthCheck.cs`
- `Data_Coupler/HealthChecks/BackgroundServiceHealthCheck.cs`

## 🔐 Sicurezza

### Gestione Credenziali:
- **Data Protection API**: Crittografia con chiavi managed da .NET
- **Key Rotation**: Supporto rotazione chiavi automatica
- **Secure Storage**: Persistenza sicura su SQLite

### Input Validation:
- **SQL Injection Prevention**: Query parametrizzate ovunque
- **XSS Protection**: Sanitizzazione input utente
- **Whitelist Validation**: Validazione nomi tabelle/campi

### Comunicazioni Sicure:
- **HTTPS**: Forzato in produzione
- **Certificate Validation**: Validazione certificati SSL/TLS
- **Secure Headers**: Security headers HTTP

### Audit Logging:
- **Tracciamento Accessi**: Log accessi credenziali
- **Operazioni Sensibili**: Log modifiche configurazioni
- **Security Events**: Alert eventi sicurezza

## 🛠️ Convenzioni di Codice

### Naming:
- **Classes/Interfaces**: PascalCase (es. `DataConnectionFactory`)
- **Methods**: PascalCase (es. `GetDataAsync`)
- **Properties**: PascalCase (es. `ConnectionString`)
- **Private Fields**: camelCase con underscore (es. `_logger`)
- **Local Variables**: camelCase (es. `connectionName`)

### Async/Await:
- Tutti i metodi I/O sono asincroni
- Naming convention: `*Async` suffix
- Uso di `CancellationToken` per operazioni cancellabili
- **MAI** usare `.Result` o `.Wait()` - rischio deadlock

### Dependency Injection:
- **Singleton**: Servizi stateless (es. `IEncryptionService`)
- **Scoped**: Servizi con stato per request (es. `IDataConnectionFactory`)
- **Transient**: Servizi leggeri (es. validators)

### Error Handling:
- Try-catch con logging specifico
- Messaggi utente user-friendly
- Dettagli tecnici nei log, non in UI
- Rollback transazioni in caso di errore

## 📝 Pattern Architetturali Utilizzati

### 1. Repository Pattern:
- Astrazione accesso dati
- `*Service` interfacce per business logic
- `*Repository` per accesso database

### 2. Factory Pattern:
- `DataConnectionFactory`: Creazione connessioni database/REST
- `RestServiceClientFactory`: Creazione client REST specifici

### 3. Strategy Pattern:
- Diversi provider database (SQL Server, MySQL, PostgreSQL, etc.)
- Diversi client REST (Generic, Salesforce, SAP B1)

### 4. Observer Pattern:
- Background services per schedulazioni
- Event-driven processing

## 🧪 Testing

### Unit Tests:
- Copertura servizi core
- Mock di dipendenze esterne
- Test naming: `MethodName_Scenario_ExpectedBehavior`

### Integration Tests:
- Test connessioni database reali
- Test API REST con server di test
- Test end-to-end UI con Playwright

## 📦 Deployment

### Docker Support:
- `Dockerfile`: Immagine Linux
- `Dockerfile.windows`: Immagine Windows
- `docker-compose.yml`: Orchestrazione multi-container
- Health checks integrati

### Windows Service:
- Deploy come Windows Service
- Auto-start configurabile
- Logging Windows Event Log

### Azure Deployment:
- App Service support
- Container Apps support
- Key Vault integration per secrets

## 🔄 Workflow di Sviluppo

### Branching Strategy:
- `main`: Produzione stabile
- `development`: Sviluppo attivo (pubblica su `latest` tag)
- `feature/*`: Nuove feature
- `hotfix/*`: Fix urgenti

### CI/CD Pipeline:

#### GitHub Actions (`.github/workflows/docker-build.yml`)
- **Branch `main`**: Pubblica immagini Docker con tag `latest`
- **Branch `development`**: Pubblica immagini Docker con tag `latest` e `development-latest`
- **Branch `staging`**: Pubblica immagini Docker con tag `staging-latest`
- **Ogni commit**: Crea tag con SHA e timestamp per tracciabilità
- **Registry**: GitHub Container Registry (`ghcr.io`)

#### Gitea Actions (`.gitea/workflows/docker-build.yml`)
- **Stessa configurazione** di GitHub Actions
- **Registry**: Gitea Container Registry (`gitea.home-nas-ds.org`)
- **Supporto**: Istanza Gitea self-hosted con registry abilitato
- **Setup**: Richiede secret `REGISTRY_TOKEN` con permessi `write:packages`
- **Documentazione**: `.gitea/workflows/README.md`

**Note sui Tag Docker**:
- `latest`: Condiviso tra `main` e `development` per garantire accesso alle ultime funzionalità
- `development-latest`: Specifico per il branch `development`, utile per distinguere le versioni in sviluppo
- `staging-latest`: Dedicato al branch `staging` per test pre-produzione
- Disponibile su **entrambi** i registry (GitHub e Gitea)

### Commit Messages:
- Formato: `[Tipo] Descrizione breve`
- Tipi: `[Feature]`, `[Fix]`, `[Refactor]`, `[Docs]`, `[Test]`
- Esempio: `[Feature] Implementato sistema schedulazione avanzata`

### Code Review:
- Ogni PR richiede review
- Checklist: code style, tests, documentation
- CI/CD automatico

## 📚 Documentazione Correlata

### File di Documentazione nel Progetto:
- **AGENTS.md**: Guida completa per AI agents e Copilot
- **ADVANCED_SCHEDULING_SYSTEM.md**: Sistema schedulazione dettagliato
- **GESTIONE_ASSOCIAZIONI_AVANZATA.md**: Sistema associazioni completo
- **SALESFORCE_BATCH_EXTRACTION_IMPROVEMENTS.md**: Batch extraction Salesforce
- **PRE_DISCOVERY_SYSTEM.md**: Sistema pre-discovery associazioni
- **DELETION_SYNC_IMPLEMENTATION.md**: Sincronizzazione eliminazioni
- **CSV_SCHEDULING_IMPLEMENTATION.md**: Schedulazione file CSV/Excel (NUOVO)
- **DOCKER_DEPLOYMENT.md**: Guida deployment Docker
- **WINDOWS_SERVICE_DEPLOYMENT.md**: Deploy come Windows Service
- **.gitea/workflows/README.md**: Configurazione Gitea Actions

## 🎓 Best Practices per AI Assistants

### Quando Modificare Codice:
1. **Leggere Documentazione**: Consultare file MD correlati
2. **Analizzare Pattern**: Seguire pattern esistenti nel codebase
3. **Validare Input**: Sempre validare parametri
4. **Error Handling**: Gestire tutti i possibili errori
5. **Logging**: Aggiungere log appropriati
6. **Testing**: Creare/aggiornare test correlati
7. **Documentazione**: Aggiornare XML comments e MD files

### Quando Creare Nuove Feature:
1. **Progettare Prima**: Pianificare architettura
2. **Seguire Convenzioni**: Rispettare code style
3. **Dependency Injection**: Registrare nuovi servizi in `Program.cs`
4. **Database Changes**: Creare migration Entity Framework
5. **UI Consistency**: Seguire design pattern esistente
6. **Documentare**: Creare/aggiornare documentazione

### Red Flags da Evitare:
- ❌ Hardcoded credentials o secrets
- ❌ SQL injection vulnerabilities
- ❌ Blocking calls in async methods
- ❌ Catch generico senza logging
- ❌ Modifiche database senza migration
- ❌ Breaking changes senza versioning
- ❌ Codice duplicato invece di refactoring

## 🚀 Roadmap Futura

### Feature in Pianificazione:
- [x] Supporto file Excel/CSV avanzato (Completato - Gennaio 2026)
- [ ] Sistema di notifiche (email, webhook)
- [ ] Dashboard analytics avanzato
- [ ] Multi-tenant support
- [ ] API REST pubblica
- [ ] Plugin system per connectors custom
- [ ] Machine learning per mapping suggeriti
- [ ] Real-time data sync
- [ ] Lettura fogli Excel multipli
- [ ] Supporto file remoti (HTTP, FTP, Azure Blob)

### Miglioramenti Tecnici:
- [ ] Migrazione a .NET 10 (quando disponibile)
- [ ] Caching distribuito (Redis)
- [ ] Message queue (RabbitMQ/Azure Service Bus)
- [ ] Elasticsearch per log search
- [ ] Prometheus/Grafana per monitoring

---

**Versione**: 2.1  
**Ultimo Aggiornamento**: 25 Gennaio 2026  
**Framework**: .NET 9.0  
**Sviluppatore**: Alessio Dalsanto  
**Repository**: https://github.com/AlessioDalsi/Data-Coupler