-Creata documentazione riguardante il progetto

2025-09-11 11:41:03 +02:00
parent ce359a12bc
commit 78676d4485
2 changed files with 591 additions and 0 deletions
@@ -0,0 +1,591 @@
 # Data-Coupler: Documentazione Completa del Progetto
 ## Indice
 1. [Descrizione Generale del Progetto](#descrizione-generale-del-progetto)
 2. [Architettura e Struttura del Progetto](#architettura-e-struttura-del-progetto)
 3. [Mappatura dei Progetti della Soluzione](#mappatura-dei-progetti-della-soluzione)
 4. [Funzionalità Dettagliate](#funzionalità-dettagliate)
 5. [Mappa delle Funzioni e Procedure](#mappa-delle-funzioni-e-procedure)
 6. [Riferimenti Esterni e Percorsi](#riferimenti-esterni-e-percorsi)
 7. [Interconnessioni tra Componenti](#interconnessioni-tra-componenti)
 8. [Stato delle Implementazioni](#stato-delle-implementazioni)
 9. [Utilizzo e Configurazione](#utilizzo-e-configurazione)
 ---
 ## Descrizione Generale del Progetto
 **Data-Coupler** è un sistema avanzato per l'accoppiamento e sincronizzazione di dati tra diverse fonti di dati e destinazioni. Il progetto è sviluppato in .NET 9.0 utilizzando Blazor Server e fornisce un'interfaccia web intuitiva per configurare, gestire ed eseguire operazioni di trasferimento dati.
 ### Funzionalità Principali
 - **Connessione Multi-Database**: Supporta SQL Server, MySQL, PostgreSQL, Oracle, SQLite, DB2, SAP HANA
 - **Integrazione REST API**: Supporta API generiche, Salesforce, SAP Business One Service Layer
 - **Elaborazione File**: Gestisce file Excel (.xlsx, .xls) e CSV
 - **Sistema di Mapping**: Mappatura intelligente dei campi tra sorgenti e destinazioni
 - **Gestione Associazioni**: Sistema di tracking delle chiavi per evitare duplicati
 - **Gestione Profili**: Salvataggio e riutilizzo di configurazioni
 - **Background Services**: Servizi in background per operazioni periodiche
 - **Sicurezza**: Crittografia delle credenziali cross-platform
 ### Caratteristiche Tecniche
 - **Framework**: .NET 9.0, Blazor Server
 - **Database**: SQLite con Entity Framework Core
 - **UI**: Bootstrap 5, Font Awesome
 - **Architettura**: Modulare con separazione delle responsabilità
 - **Cross-Platform**: Windows, Linux, macOS
 ---
 ## Architettura e Struttura del Progetto
 Il progetto segue un'architettura modulare con separazione chiara delle responsabilità:
 ```
 Data-Coupler/
 ├── Data_Coupler/          # Applicazione principale Blazor Server
 ├── DataConnection/        # Libreria per connessioni dati
 ├── CredentialManager/     # Gestione sicura delle credenziali
 ├── Components/           # Componenti UI riutilizzabili
 └── Documentation/        # File di documentazione
 ```
 ### Principi Architetturali
 1. **Separation of Concerns**: Ogni progetto ha responsabilità specifiche
 2. **Dependency Injection**: Utilizzo estensivo di DI per loose coupling
 3. **Factory Pattern**: Per la creazione di connessioni database e REST
 4. **Repository Pattern**: Per l'accesso ai dati
 5. **Service Layer**: Logica business separata dalla presentazione
 ---
 ## Mappatura dei Progetti della Soluzione
 ### 1. Data_Coupler (Progetto Principale)
 **Tipo**: Applicazione Web Blazor Server  
 **Tecnologie**: .NET 9.0, Blazor Server, Bootstrap 5  
 **Responsabilità**: Interfaccia utente principale e orchestrazione
 #### Strutture Principali:
 - **Pages/**: Pagine Blazor per le diverse funzionalità
  - `DataCoupler.razor(.cs)`: Pagina principale per il trasferimento dati
  - `ProfilesManagement.razor(.cs)`: Gestione dei profili salvati
  - `CredentialManagement.razor`: Gestione delle credenziali
  - `KeyAssociations.razor`: Gestione delle associazioni chiavi
 - **Extensions/DataCoupler/**: Metodi estesi per funzionalità specifiche
  - `DatabaseMethod.cs`: Metodi per connessioni database
  - `RESTMethod.cs`: Metodi per connessioni REST API
 - **Services/**: Servizi dell'applicazione
  - `DataConnectionFactory.cs`: Factory per connessioni dati
 - **Models/**: Modelli di dati specifici dell'app
  - `DataCouplerModels.cs`: Modelli per risultati trasferimenti
 - **BackgroundServices/**: Servizi in background
  - `BackgroundServices.cs`: Servizi periodici (attualmente placeholder)
 ### 2. DataConnection (Libreria Core)
 **Tipo**: Class Library  
 **Responsabilità**: Gestione connessioni database e REST API
 #### Strutture Principali:
 - **DB/**: Gestione database
  - **Interfaces/**: Interfacce per abstraction layer
    - `IDatabaseManager.cs`: Interfaccia principale per database
    - `IDatabaseSchemaProvider.cs`: Provider per schema discovery
    - `IDatabaseDiscovery.cs`: Discovery di database disponibili
  - **EF/**: Implementazioni Entity Framework
    - `EFCoreDatabaseManager.cs`: Manager EF Core per database esistenti
    - **DatabaseDiscovery/**: Discovery specifiche per DB type
 - **REST/**: Gestione REST API
  - **Interfaces/**: Interfacce REST
  - **Implementations/**: Implementazioni specifiche (Salesforce, Generic)
  - **Models/**: Modelli per richieste/risposte REST
 - **CredentialManagement/**: Integrazione con CredentialManager
 ### 3. CredentialManager (Gestione Credenziali)
 **Tipo**: Class Library  
 **Responsabilità**: Gestione sicura delle credenziali
 #### Strutture Principali:
 - **Data/**: Contesto Entity Framework
  - `CredentialDbContext.cs`: DbContext per credenziali
 - **Models/**: Modelli di dati
  - `CredentialModels.cs`: DTOs per credenziali
  - `CredentialEntity.cs`: Entità database
  - `KeyAssociation.cs`: Modello per associazioni chiavi
  - `DataCouplerProfile.cs`: Modello per profili salvati
 - **Services/**: Servizi di gestione
  - `CredentialService.cs`: Servizio principale per credenziali
  - `DataCouplerProfileService.cs`: Gestione profili
 - **Utilities/**: Utilità varie
  - `EncryptionService.cs`: Crittografia cross-platform
 - **Integration/**: Helper per integrazione
  - `DataConnectionHelper.cs`: Utilità per DataConnection
 ### 4. Components (Componenti UI)
 **Tipo**: Razor Class Library  
 **Responsabilità**: Componenti UI riutilizzabili
 #### Componenti Principali:
 - `ProfileManagement.razor(.cs)`: Componente per gestione profili
 - `ProfileSelector.razor(.cs)`: Selettore di profili
 - `ProfileSaver.razor(.cs)`: Componente per salvare profili
 ---
 ## Funzionalità Dettagliate
 ### 1. Gestione Sorgenti Dati
 #### Connessioni Database
 - **Supporto Multi-DB**: SQL Server, MySQL, PostgreSQL, Oracle, SQLite, DB2, SAP HANA
 - **Schema Discovery**: Automatic discovery di tabelle, colonne e metadati
 - **Query Custom**: Supporto per query SQL personalizzate
 - **Connection String Generation**: Generazione automatica connection string
 - **Test Connessioni**: Validazione connessioni prima dell'uso
 #### Elaborazione File
 - **Formati Supportati**: Excel (.xlsx, .xls), CSV
 - **Multi-Sheet**: Gestione fogli multipli in Excel
 - **Preview Data**: Anteprima dati con paginazione
 - **Encoding Detection**: Rilevamento automatico encoding
 #### Connessioni REST API
 - **API Generiche**: Supporto per REST API standard
 - **Salesforce**: Integrazione specifica con autenticazione OAuth
 - **SAP B1 Service Layer**: Integrazione con SAP Business One
 - **Composite API**: Ottimizzazione per operazioni batch (Salesforce)
 ### 2. Sistema di Mapping
 #### Mapping Campi
 - **Drag & Drop**: Interfaccia intuitiva per mapping
 - **Auto-Detection**: Rilevamento automatico campi simili
 - **Validazione**: Controllo compatibilità tipi dati
 - **Preview**: Anteprima risultati mapping
 #### Gestione Chiavi
 - **Chiavi Sorgente**: Identificazione univoca record sorgente
 - **Chiavi Destinazione**: Tracking ID destinazione
 - **Associazioni**: Sistema di associazioni per evitare duplicati
 - **Hash Verification**: Controllo modifiche tramite hash dati
 ### 3. Trasferimento Dati
 #### Modalità di Trasferimento
 - **Insert**: Creazione nuovi record
 - **Update**: Aggiornamento record esistenti
 - **Upsert**: Insert o update automatico
 - **Batch Processing**: Elaborazione in lotti per performance
 #### Gestione Errori
 - **Logging Dettagliato**: Log completi di ogni operazione
 - **Error Handling**: Gestione granulare degli errori
 - **Rollback**: Possibilità di rollback operazioni
 - **Report Risultati**: Report dettagliati successi/errori
 ### 4. Gestione Profili
 #### Salvataggio Configurazioni
 - **Profili Completi**: Salvataggio di tutte le configurazioni
 - **Metadati**: Nome, descrizione, data creazione/utilizzo
 - **Versioning**: Gestione versioni profili
 - **Export/Import**: Esportazione profili in JSON
 #### Gestione Profili
 - **Lista Profili**: Visualizzazione tutti i profili salvati
 - **Filtri**: Ricerca per nome, tipo, utilizzo
 - **Statistiche**: Dashboard con statistiche utilizzo
 - **Eliminazione**: Soft delete profili
 ---
 ## Mappa delle Funzioni e Procedure
 ### Data_Coupler.Pages.DataCoupler
 #### Metodi di Gestione Stato
 - `OnInitializedAsync()`: Inizializzazione componente
 - `LoadCredentials()`: Caricamento credenziali database/REST
 - `LoadProfiles()`: Caricamento profili disponibili
 - `ResetAllState()`: Reset completo stato applicazione
 #### Metodi Database (DatabaseMethod.cs)
 - `ConnectToDatabase()`: Connessione database principale
 - `ConnectToDatabaseWithSpecificDatabase(string)`: Connessione a DB specifico
 - `ConnectToDatabaseWithSchema(string)`: Connessione con schema specifico
 - `LoadTablesFromConnectedDatabase()`: Caricamento tabelle
 - `LoadAvailableDatabases()`: Discovery database disponibili
 - `SelectTable(string)`: Selezione tabella e caricamento schema
 - `ValidateCustomQuery()`: Validazione query personalizzate
 - `LoadQueryPreview()`: Anteprima risultati query
 #### Metodi REST (RESTMethod.cs)
 - `ConnectToRestService()`: Connessione servizio REST
 - `LoadRestMetadata()`: Caricamento metadati REST
 - `TestRestConnection()`: Test connessione REST API
 #### Metodi File
 - `ProcessFileUpload()`: Elaborazione file caricati
 - `LoadFileData()`: Lettura dati da file
 - `ParseExcelFile()`: Parsing file Excel
 - `ParseCsvFile()`: Parsing file CSV
 #### Metodi Mapping
 - `MapField(string, string)`: Mapping singolo campo
 - `RemoveMapping(string)`: Rimozione mapping
 - `ClearAllMappings()`: Reset tutti i mapping
 - `ValidateMapping()`: Validazione configurazione mapping
 - `AutoMapFields()`: Auto-mapping campi simili
 #### Metodi Trasferimento
 - `StartDataTransfer()`: Avvio trasferimento standard
 - `StartDataTransferWithComposite()`: Trasferimento con Composite API
 - `ProcessRecord()`: Elaborazione singolo record
 - `CreateAssociationAsync()`: Creazione associazione chiave
 - `UpdateAssociationHashAsync()`: Aggiornamento hash associazione
 #### Metodi Profili
 - `OnProfileLoaded()`: Caricamento profilo salvato
 - `ApplyProfileConfiguration()`: Applicazione configurazione profilo
 - `SaveCurrentProfile()`: Salvataggio profilo corrente
 ### DataConnection.EF.EFCoreDatabaseManager
 #### Metodi Core
 - `TestConnectionAsync()`: Test connessione database
 - `GetDatabaseSchemaAsync()`: Recupero schema completo
 - `GetAvailableDatabasesAsync()`: Lista database disponibili
 - `ChangeDatabaseAsync(string)`: Cambio database corrente
 #### Metodi CRUD Generici
 - `GetAsync<T>()`: Query generiche con filtri
 - `GetByIdAsync<T>(object)`: Recupero per ID
 - `CreateAsync<T>(T)`: Creazione entity
 - `UpdateAsync<T>(T)`: Aggiornamento entity
 - `DeleteAsync<T>(T)`: Eliminazione entity
 #### Metodi SQL Raw
 - `ExecuteRawSqlAsync(string, object[])`: Esecuzione SQL raw
 - `ExecuteCommandAsync(string, object[])`: Comandi SQL
 ### CredentialManager.Services.CredentialService
 #### Gestione Credenziali Database
 - `SaveDatabaseCredentialAsync()`: Salvataggio credenziali DB
 - `GetDatabaseCredentialAsync()`: Recupero credenziali DB
 - `GetAllDatabaseCredentialsAsync()`: Lista tutte credenziali DB
 - `TestDatabaseConnectionAsync()`: Test connessione DB
 #### Gestione Credenziali REST
 - `SaveRestApiCredentialAsync()`: Salvataggio credenziali REST
 - `GetRestApiCredentialAsync()`: Recupero credenziali REST
 - `GetAllRestApiCredentialsAsync()`: Lista tutte credenziali REST
 - `TestRestConnectionAsync()`: Test connessione REST
 #### Gestione Associazioni Chiavi
 - `SaveKeyAssociationAsync()`: Salvataggio associazione
 - `FindKeyAssociationByValueAsync()`: Ricerca per valore chiave
 - `UpdateKeyAssociationAsync()`: Aggiornamento associazione
 - `GetKeyAssociationsAsync()`: Lista associazioni
 ### CredentialManager.Services.DataCouplerProfileService
 #### Gestione Profili
 - `SaveProfileAsync()`: Salvataggio nuovo profilo
 - `UpdateProfileAsync()`: Aggiornamento profilo esistente
 - `GetAllProfilesAsync()`: Lista tutti i profili
 - `GetProfileByIdAsync()`: Recupero profilo per ID
 - `GetProfileByNameAsync()`: Recupero profilo per nome
 - `DeleteProfileAsync()`: Eliminazione profilo (soft delete)
 - `UpdateLastUsedAsync()`: Aggiornamento ultimo utilizzo
 #### Utilità Profili
 - `ProfileExistsAsync()`: Verifica esistenza profilo
 - `SerializeFieldMappings()`: Serializzazione mapping
 - `DeserializeFieldMappings()`: Deserializzazione mapping
 - `ToDto()`: Conversione a DTO
 - `FromDto()`: Conversione da DTO
 ---
 ## Riferimenti Esterni e Percorsi
 ### Database SQLite Principale
 **Percorso**: 
 - **Windows**: `%ProgramData%\Data_Coupler\credentials.db`
 - **Linux**: `/var/lib/Data_Coupler/credentials.db`
 - **macOS**: `/Library/Application Support/Data_Coupler/credentials.db`
 ### Tabelle Database
 1. **Credentials**: Memorizzazione credenziali crittografate
 2. **KeyAssociations**: Associazioni chiavi sorgente-destinazione
 3. **DataCouplerProfiles**: Profili di configurazione salvati
 ### File di Configurazione
 - `appsettings.json`: Configurazione generale
 - `appsettings.Development.json`: Configurazione sviluppo
 - `nuget.config`: Configurazione pacchetti NuGet
 ### Dipendenze Esterne Principali
 - **Microsoft.EntityFrameworkCore**: ORM per database
 - **ExcelDataReader**: Lettura file Excel
 - **System.Data.SqlClient**: SQL Server
 - **MySqlConnector**: MySQL
 - **Npgsql**: PostgreSQL
 - **Oracle.ManagedDataAccess**: Oracle
 - **IBM.Data.Db2**: DB2
 ### Porte di Default
 - **Applicazione Web**: `http://localhost:7550`
 - **SQL Server**: 1433
 - **MySQL**: 3306
 - **PostgreSQL**: 5432
 - **Oracle**: 1521
 ---
 ## Interconnessioni tra Componenti
 ### Flusso di Dipendenze
 ```
 Data_Coupler (App)
 ├── CredentialManager (Gestione Credenziali)
 ├── DataConnection (Connessioni Dati)
 ├── Components (UI Components)
 └── Background Services
 ```
 ### Interazioni Principali
 #### 1. Caricamento Credenziali
 ```
 Data_Coupler → CredentialManager.CredentialService → SQLite Database
 ```
 #### 2. Connessione Database
 ```
 Data_Coupler → DataConnectionFactory → DataConnection.EF.EFCoreDatabaseManager → Database Target
 ```
 #### 3. Connessione REST
 ```
 Data_Coupler → DataConnectionFactory → DataConnection.REST.Implementations → REST API
 ```
 #### 4. Gestione Profili
 ```
 Data_Coupler → CredentialManager.DataCouplerProfileService → SQLite Database
 ```
 ### Pattern di Comunicazione
 #### Dependency Injection
 Tutti i servizi sono registrati nel container DI e iniettati dove necessario:
 ```csharp
 // Program.cs
 builder.Services.AddDataConnectionCredentialManagement(dbPath);
 builder.Services.AddScoped<IDataConnectionFactory, DataConnectionFactory>();
 ```
 #### Factory Pattern
 Le connessioni sono create tramite factory per garantire configurazione corretta:
 ```csharp
 var dbManager = await ConnectionFactory.CreateDatabaseManagerAsync(credentialName);
 var restClient = await ConnectionFactory.CreateRestServiceClientAsync(credentialName);
 ```
 #### Service Layer
 La logica business è incapsulata in servizi dedicati:
 - `CredentialService`: Gestione credenziali
 - `DataCouplerProfileService`: Gestione profili
 - `DataConnectionFactory`: Creazione connessioni
 ---
 ## Stato delle Implementazioni
 ### ✅ Funzionalità Completamente Implementate
 #### Gestione Credenziali
 - ✅ Salvataggio/recupero credenziali database
 - ✅ Salvataggio/recupero credenziali REST API
 - ✅ Crittografia cross-platform
 - ✅ Test connessioni
 - ✅ Validazione credenziali
 #### Connessioni Database
 - ✅ Supporto multi-database (SQL Server, MySQL, PostgreSQL, etc.)
 - ✅ Schema discovery automatico
 - ✅ Query personalizzate
 - ✅ Gestione connection string
 #### Connessioni REST
 - ✅ API generiche
 - ✅ Integrazione Salesforce completa
 - ✅ Salesforce Composite API per performance
 - ✅ Autenticazione OAuth
 #### Elaborazione File
 - ✅ Lettura Excel (.xlsx, .xls)
 - ✅ Lettura CSV
 - ✅ Preview dati con paginazione
 - ✅ Gestione multi-sheet
 #### Sistema Mapping
 - ✅ Mapping manuale campi
 - ✅ Auto-detection campi simili
 - ✅ Validazione mapping
 - ✅ Preview risultati
 #### Gestione Associazioni
 - ✅ Tracking chiavi sorgente-destinazione
 - ✅ Prevenzione duplicati
 - ✅ Hash verification per rilevare modifiche
 - ✅ Gestione update vs insert intelligente
 #### Gestione Profili
 - ✅ Salvataggio configurazioni complete
 - ✅ Caricamento profili salvati
 - ✅ Lista e gestione profili
 - ✅ Statistiche utilizzo
 - ✅ Export/import JSON
 ### 🔄 Funzionalità Parzialmente Implementate
 #### Background Services
 - 🔄 **Struttura base**: Implementata ma placeholder
 - 🔄 **Servizi specifici**: Da implementare funzionalità specifiche
 - 🔄 **Scheduling**: Da aggiungere scheduling operazioni
 #### Gestione Errori Avanzata
 - 🔄 **Logging base**: Implementato
 - 🔄 **Error recovery**: Parziale
 - 🔄 **Rollback automatico**: Da implementare
 #### Performance Optimization
 - 🔄 **Batch processing**: Implementato per Salesforce
 - 🔄 **Parallelizzazione**: Parziale
 - 🔄 **Caching**: Base implementato
 #### Security Features
 - 🔄 **Autenticazione utente**: Da implementare
 - 🔄 **Autorizzazione**: Da implementare
 - 🔄 **Audit trail**: Parziale
 ### ❌ Funzionalità Da Implementare
 #### Integrazione Database Avanzata
 - ❌ **Supporto Stored Procedures**: Da implementare
 - ❌ **Triggers**: Da implementare
 - ❌ **Views materialized**: Da implementare
 #### API Extensions
 - ❌ **GraphQL**: Da implementare
 - ❌ **SAP B1 Service Layer completo**: Struttura presente ma da completare
 - ❌ **Altri ERP**: Da aggiungere
 #### Data Transformation
 - ❌ **Trasformazioni custom**: Da implementare
 - ❌ **Formule/Calcoli**: Da implementare
 - ❌ **Data cleansing**: Da implementare
 #### Monitoring & Analytics
 - ❌ **Dashboard performance**: Da implementare
 - ❌ **Metriche dettagliate**: Da implementare
 - ❌ **Alerting**: Da implementare
 #### Advanced Features
 - ❌ **Real-time sync**: Da implementare
 - ❌ **Conflict resolution**: Da implementare
 - ❌ **Multi-tenant**: Da implementare
 - ❌ **REST API del Data Coupler**: Da implementare
 ---
 ## Utilizzo e Configurazione
 ### Configurazione Iniziale
 1. **Compilazione e Avvio**:
   ```bash
   dotnet run --project Data_Coupler/Data_Coupler.csproj
   ```
 2. **Accesso Web Interface**:
   - URL: `http://localhost:7550`
   - L'applicazione inizializza automaticamente il database SQLite
 ### Workflow Tipico
 #### 1. Configurazione Credenziali
 - Accedere alla sezione "Gestione Credenziali"
 - Aggiungere credenziali database e/o REST API
 - Testare le connessioni
 #### 2. Configurazione Trasferimento
 - Selezionare tipo sorgente (Database/File)
 - Configurare connessione sorgente
 - Configurare destinazione REST API
 - Definire mapping campi
 - Configurare gestione chiavi
 #### 3. Esecuzione Trasferimento
 - Avviare trasferimento dati
 - Monitorare progresso
 - Verificare risultati
 #### 4. Gestione Profili (Opzionale)
 - Salvare configurazione come profilo
 - Riutilizzare profili per operazioni ricorrenti
 ### Configurazioni Avanzate
 #### Database Path Personalizzato
 Modificare `Program.cs` per percorso custom:
 ```csharp
 string customDbPath = "/path/to/custom/credentials.db";
 builder.Services.AddDataConnectionCredentialManagement($"Data Source={customDbPath}");
 ```
 #### Logging Personalizzato
 Configurare logging in `Program.cs`:
 ```csharp
 builder.Logging.AddConsole();
 builder.Logging.SetMinimumLevel(LogLevel.Debug);
 ```
 #### Performance Tuning
 - **Batch Size**: Configurabile nel codice per operazioni batch
 - **Timeout**: Configurabile per connessioni database/REST
 - **Memory**: Gestione automatica, configurabile per file grandi
 ### Troubleshooting
 #### Problemi Comuni
 1. **Database Lock**: Riavviare applicazione
 2. **Credenziali non funzionanti**: Verificare test connessione
 3. **File non leggibili**: Verificare formato e permissions
 4. **API Rate Limiting**: Configurare delays appropriati
 #### Log Files
 I log sono disponibili nella console dell'applicazione e possono essere configurati per output su file.
 ---
 ## Conclusioni
 Data-Coupler rappresenta una soluzione robusta e flessibile per l'integrazione di dati tra diverse piattaforme. L'architettura modulare consente estensioni future, mentre le funzionalità già implementate coprono la maggior parte dei casi d'uso comuni.
 Il progetto è in uno stato maturo per quanto riguarda le funzionalità core, con spazio per miglioramenti in aree come monitoring, security avanzata e funzionalità enterprise.
 ### Prossimi Sviluppi Consigliati
 1. Implementazione sistema di autenticazione utenti
 2. Dashboard analytics e monitoring
 3. API REST per automazione
 4. Supporto trasformazioni dati avanzate
 5. Integrazione con sistemi di workflow
 ---
 **Versione Documentazione**: 1.0  
 **Data**: 11 Settembre 2025  
 **Autore**: Sistema di Documentazione Automatica Data-Coupler