diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..4a46459 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,430 @@ +# 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 + +#### 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 + +#### File Chiave: +- `Data_Coupler/Services/DeletionSyncService.cs` + +### 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. 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 +- `develop`: Sviluppo attivo +- `feature/*`: Nuove feature +- `hotfix/*`: Fix urgenti + +### 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 +- **DOCKER_DEPLOYMENT.md**: Guida deployment Docker +- **WINDOWS_SERVICE_DEPLOYMENT.md**: Deploy come Windows Service + +## 🎓 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: +- [ ] Supporto file Excel/CSV avanzato +- [ ] 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 + +### 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.0 +**Ultimo Aggiornamento**: 22 Gennaio 2026 +**Framework**: .NET 9.0 +**Sviluppatore**: Alessio Dalsanto +**Repository**: https://github.com/AlessioDalsi/Data-Coupler diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 3f48edc..f3f33db 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -4,7 +4,7 @@ on: push: branches: - main - - dev + - development - staging workflow_dispatch: inputs: