Data-Coupler/README.md

# Data-Coupler

## Panoramica

Data-Coupler è una soluzione integrata per la gestione di connessioni dati e credenziali, composta da tre progetti principali:

- **CredentialManager**: Libreria per la gestione sicura delle credenziali
- **DataConnection**: Libreria per connessioni a database e API REST
- **Data_Coupler**: Applicazione Blazor Server per l'interfaccia utente

### 🆕 Novità Recenti (Febbraio 2026)
- ✅ **Salesforce Batch Describe via Composite API**: I metadati degli SObject vengono ora recuperati in batch (25 per chiamata) invece di N chiamate singole, riducendo drasticamente il consumo di API durante la discovery
- ✅ **Discovery REST Parallela**: `DiscoverEntitySummariesAsync` e `DiscoverEntitiesAsync` vengono eseguite in parallelo; la lista entità diventa interattiva quasi subito, i dettagli arrivano in background
- ✅ **Fix Scheduler External ID Relationships**: Corretti due bug nello schedulatore — `ExternalIdRelationshipsJson` e `DefaultValuesJson` venivano azzerati al re-salvataggio del profilo; i campi sorgente usati nelle relazioni External ID non venivano esclusi dal mapping normale

### 🆕 Novità Recenti (Gennaio 2026)
- ✅ **Schedulazione File CSV/Excel**: Supporto completo per schedulare trasferimenti da file
- ✅ **Validazione Percorsi**: Validazione file prima del salvataggio profili
- ✅ **Deletion Sync Configurabile**: Controllo granulare sincronizzazione eliminazioni
- ✅ **Doppia Modalità File**: Caricamento browser (preview) + percorso manuale (schedulazione)

## Architettura

### CredentialManager
Libreria responsabile per:
- Gestione sicura delle credenziali (Database, REST API)
- Crittografia dei dati sensibili
- Persistenza su database SQLite
- Validazione delle credenziali

### DataConnection
Libreria per connessioni dati che include:
- Supporto per database: SQL Server, MySQL, PostgreSQL, Oracle, SQLite, DB2, SAP HANA
- Gestione connessioni REST API
- Integrazione con CredentialManager per l'autenticazione
- Factory pattern per la gestione di diversi provider

### Data_Coupler
Applicazione Blazor Server che fornisce:
- Interfaccia web per la gestione delle credenziali
- CRUD completo per credenziali database e REST API
- Test delle connessioni
- Validazione form integrata

## Configurazione

### 1. Database delle Credenziali

L'applicazione utilizza SQLite per memorizzare le credenziali. Il database viene automaticamente creato in:
```
Data_Coupler/wwwroot/data/credentials.db
```

### 2. Registrazione Servizi

Nel `Program.cs` di Data_Coupler:

```csharp
// Add CredentialManager services
builder.Services.AddDataConnectionCredentialManagement("Data Source=wwwroot/data/credentials.db");
```

## Utilizzo

### Gestione Credenziali via Web Interface

1. Avviare l'applicazione Data_Coupler
2. Navigare su `/credentials`
3. Utilizzare l'interfaccia per:
   - Aggiungere nuove credenziali (Database/REST API)
   - Modificare credenziali esistenti
   - Testare le connessioni
   - Eliminare credenziali

### Utilizzo Programmatico

```csharp
// Iniettare il servizio
@inject IDataConnectionCredentialService CredentialService

// Ottenere opzioni per connessione database
var dbOptions = await CredentialService.GetDbManagerOptionsAsync("MyDatabase");

// Ottenere opzioni per API REST
var apiOptions = await CredentialService.GetRestServiceOptionsAsync("MyApi");

// Gestire credenziali
var credential = new DatabaseCredential
{
    Name = "Test",
    DatabaseType = DatabaseType.SqlServer,
    Host = "localhost",
    Port = 1433,
    DatabaseName = "TestDB",
    Username = "user",
    Password = "password"
};

await CredentialService.SaveDatabaseCredentialAsync(credential);
```

## Struttura dei Progetti

```
Data-Coupler/
├── CredentialManager/              # Gestione credenziali
│   ├── Data/                       # DbContext e configurazioni
│   ├── Models/                     # Modelli per credenziali
│   └── Services/                   # Servizi core
├── DataConnection/                 # Connessioni dati
│   ├── CredentialManagement/       # Integrazione con CredentialManager
│   │   ├── Interfaces/             # Interfacce servizi
│   │   ├── Models/                 # Extension methods e conversioni
│   │   └── Services/               # Implementazione servizi
│   ├── DB/                         # Gestione database
│   └── REST/                       # Gestione API REST
└── Data_Coupler/                   # Applicazione Blazor
    ├── Pages/                      # Pagine Blazor
    │   └── CredentialManagement.razor
    ├── Shared/                     # Componenti condivisi
    └── wwwroot/data/               # Database SQLite
```

## Build e Deployment

### Prerequisiti
- .NET 9.0 SDK
- Visual Studio 2022 o VS Code
- Docker (opzionale, per deployment containerizzato)

### Build Locale
```bash
dotnet build Data_Coupler.sln
```

### Esecuzione Locale
```bash
dotnet run --project Data_Coupler/Data_Coupler.csproj
```

L'applicazione sarà disponibile su:
- HTTP: http://localhost:7550

## 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)
- **Schedulazione**: ✅ Supportato con percorso file manuale

### 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)
- **Schedulazione**: ✅ Supportato con percorso file manuale

### Modalità Caricamento File

#### 1. Caricamento Browser (Preview)
- Carica file tramite browser per configurare mapping
- Processato in memoria, **non salvato sul server**
- Ideale per setup iniziale profilo

#### 2. Percorso Manuale (Schedulazione) ⭐
- Specifica percorso completo file sul server
- **Obbligatorio** per profili schedulati
- Sistema valida esistenza e leggibilità
- Esempi: `C:\Data\products.csv`, `/data/customers.xlsx`

### 🐳 Deployment Docker

**Quick Start con Docker:**
```bash
# Pull e run (immagine pubblica)
docker run -d -p 7550:7550 -v data-coupler-data:/var/lib/Data_Coupler ghcr.io/alessiodalsi/data-coupler:latest

# Con Docker Compose
docker-compose up -d
```

**Build Locale:**
```bash
# Linux
docker build -t data-coupler:local -f Dockerfile .

# Windows
docker build -t data-coupler:local-windows -f Dockerfile.windows .

# Script automatico (PowerShell)
.\build-docker.ps1 -Target all -Test

# Script automatico (Bash)
./build-docker.sh all
```

**Immagini Disponibili:**
- **Linux/Multi-platform**: `ghcr.io/alessiodalsi/data-coupler:latest`
- **Windows**: `ghcr.io/alessiodalsi/data-coupler:latest-windows`
- **Development**: `ghcr.io/alessiodalsi/data-coupler:development-latest`
- **Dev**: `ghcr.io/alessiodalsi/data-coupler:dev-latest`
- **Staging**: `ghcr.io/alessiodalsi/data-coupler:staging-latest`

**Note**: Il tag `latest` viene automaticamente aggiornato sia dal branch `main` che dal branch `development` per garantire che le ultime funzionalità siano sempre disponibili. Il tag `development-latest` è specifico per il branch development.

📚 **Documentazione Docker Completa**: Vedi [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md) e [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md)

### 🔄 CI/CD Pipeline

Il progetto supporta pipeline CI/CD automatiche su:

**GitHub Actions** (`.github/workflows/docker-build.yml`):
- Build automatica su push ai branch `main`, `development`, `staging`
- Pubblicazione su GitHub Container Registry (`ghcr.io`)
- Multi-platform manifest (Linux + Windows)

**Gitea Actions** (`.gitea/workflows/docker-build.yml`):
- Stessa configurazione di GitHub Actions
- Pubblicazione su Gitea Container Registry (`gitea.home-nas-ds.org`)
- Istanza Gitea self-hosted con registry abilitato
- Configurazione: `.gitea/workflows/README.md`

**Immagini su Gitea** (self-hosted):
```bash
# Pull da Gitea Container Registry
docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest

# Versioni disponibili
docker pull gitea.home-nas-ds.org/alessio/data-coupler:development-latest
docker pull gitea.home-nas-ds.org/alessio/data-coupler:staging-latest
```

📚 **Setup Gitea**: Vedi [.gitea/workflows/README.md](.gitea/workflows/README.md)

## Caratteristiche di Sicurezza

- **Crittografia**: Le password vengono crittografate prima del salvataggio
- **Validazione**: Validazione completa dei dati in input
- **Isolamento**: Ogni progetto ha responsabilità specifiche
- **Type Safety**: Uso di tipi forti per evitare errori
- **Validazione File**: Verifica esistenza e leggibilità file prima del salvataggio
- **Deletion Sync Sicuro**: 
  - Disabilitato di default per prevenire eliminazioni accidentali
  - Disponibile solo nelle schedulazioni con configurazione esplicita
  - Warning chiaro nell'interfaccia utente per operazioni critiche
- **Percorsi File Validati**: Controllo permessi e accessibilità per schedulazioni

## Testing

L'applicazione include funzionalità di test per:
- Connessioni database
- Chiamate API REST
- Validazione credenziali

Il testing può essere eseguito direttamente dall'interfaccia web.

## Log e Monitoring

I servizi utilizzano ILogger per tracciare:
- Operazioni CRUD sulle credenziali
- Test di connessione
- Errori e eccezioni

## Contributi

Per contribuire al progetto:
1. Fork del repository
2. Creare un branch per la feature
3. Implementare i cambiamenti
4. Testare thoroughly
5. Creare una Pull Request

## Licenza

[Specificare la licenza del progetto]