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

12. Sistema di Versioning Automatizzato

Caratteristiche:

• Versioning Automatico: Generazione automatica della versione tramite Gitea Actions
• Display UI: Versione visibile nel NavMenu dell'applicazione
• Semantic Versioning: Segue il pattern MAJOR.MINOR.PATCH
• Metadati Build: Commit SHA, branch, data build, ambiente
• Fallback Intelligente: Versione di default se file non disponibile

Componenti:

• version.json: File generato automaticamente durante il build
• VersionInfo: Modello dati per informazioni versione
• VersionService: Servizio singleton per gestione versione
• NavMenu Integration: Display "Data_Coupler v2.1.0" nel navbar

Workflow:

1. Git Push → Gitea Actions triggered
2. Workflow genera version.json con versione da csproj
3. Docker build include il file version.json
4. VersionService carica al startup
5. NavMenu mostra versione nell'interfaccia

File Chiave:

• Data_Coupler/Models/VersionInfo.cs
• Data_Coupler/Services/VersionService.cs
• Data_Coupler/wwwroot/version.json
• .gitea/workflows/docker-build.yml
• VERSIONING_SYSTEM.md (documentazione completa)

🔐 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
• VERSIONING_SYSTEM.md: Sistema di versioning automatizzato (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:

• Supporto file Excel/CSV avanzato (Completato - Gennaio 2026)
• Sistema di versioning automatizzato (Completato - Febbraio 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: 2 Febbraio 2026
Framework: .NET 9.0
Sviluppatore: Alessio Dalsanto
Repository: https://github.com/AlessioDalsi/Data-Coupler