# Implementazione Salesforce Composite API nel Data Coupler

## Panoramica

Questo documento descrive l'implementazione delle chiamate Composite API di Salesforce nel DataCoupler, che sostituiscono le chiamate REST singole con operazioni batch più efficienti.

## Modifiche Implementate

### 1. SalesforceServiceClient.cs

#### Nuove Classi
- `CompositeOperationResult`: Risultato di un'operazione composite
- `SalesforceCompositeRequest`: Struttura della richiesta composite
- `SalesforceCompositeSubRequest`: Sotto-richiesta all'interno del batch
- `SalesforceCompositeResponse`: Risposta della chiamata composite
- `SalesforceCompositeSubResponse`: Risposta di ogni singola operazione

#### Nuovi Metodi
- `BatchCreateEntitiesAsync(string entityName, List<Dictionary<string, object>> entityDataList)`: 
  - Esegue creazioni multiple usando Composite API
  - **Batching automatico**: Suddivide automaticamente le operazioni in batch da max 25 (limite Salesforce)
  - Ritorna lista di risultati per ogni operazione
  
- `BatchUpdateEntitiesAsync(string entityName, Dictionary<string, Dictionary<string, object>> updateData)`:
  - Esegue aggiornamenti multipli usando Composite API
  - **Batching automatico**: Gestisce automaticamente il limite di 25 operazioni per batch
  - Accetta dictionary con entityId come chiave e dati da aggiornare come valore

#### Metodi di Supporto per Batching
- `ExecuteCreateBatchAsync()`: Esegue un singolo batch di creazioni (max 25)
- `ExecuteUpdateBatchAsync()`: Esegue un singolo batch di aggiornamenti (max 25)

### 2. DataCoupler.razor.cs

#### Nuovo Metodo Principale
- `StartDataTransferWithComposite()`: Versione ottimizzata del trasferimento dati che:
  1. Recupera tutti i dati dalla sorgente
  2. Analizza le associazioni per determinare create vs update
  3. Suddivide i record in batch separati per create e update
  4. Esegue le chiamate composite in parallelo
  5. Processa i risultati e crea/aggiorna le associazioni

#### Metodi di Supporto
- `CreateAssociationAsync()`: Crea una nuova associazione per record creati
- `UpdateAssociationVerificationAsync()`: Aggiorna la data di verifica associazione
- `HandleFailedUpdateAsync()`: Gestisce associazioni non valide dopo update falliti
- `ShowTransferResults()`: Mostra i risultati del trasferimento

#### Modifiche al Metodo Originale
- `StartDataTransfer()`: Modificato per utilizzare automaticamente `StartDataTransferWithComposite()` quando il client è Salesforce

## Vantaggi dell'Implementazione

### 1. Performance
- **Riduzione chiamate API**: Da N chiamate singole a 2 chiamate batch (una per create, una per update)
- **Esecuzione parallela**: Le operazioni di create e update vengono eseguite contemporaneamente
- **Efficienza di rete**: Riduce drasticamente il numero di round-trip HTTP

### 2. Affidabilità
- **Gestione errori granulare**: Ogni operazione nel batch può avere successo o fallire indipendentemente
- **Rollback parziale**: Le operazioni riuscite rimangono valide anche se altre falliscono
- **Logging dettagliato**: Tracciamento completo di ogni operazione

### 3. Scalabilità
- **Supporto batch parallelo**: Gestione automatica del limite di 25 operazioni con esecuzione parallela
- **Gestione memoria efficiente**: Elaborazione in stream dei risultati
- **Compatibilità**: Fallback automatico al metodo originale per client non-Salesforce

## Flusso di Lavoro

```
1. Verifica Client Salesforce
   ↓
2. Recupera dati sorgente
   ↓
3. Trasforma record e analizza associazioni
   ↓
4. Suddivide in batch:
   - Record da creare (nuovi)
   - Record da aggiornare (con associazione esistente)
   ↓
5. Esecuzione parallela:
   - BatchCreateEntitiesAsync()
   - BatchUpdateEntitiesAsync()
   ↓
6. Processamento risultati:
   - Crea associazioni per nuovi record
   - Aggiorna timestamp associazioni esistenti
   - Gestisce errori e associazioni non valide
   ↓
7. Report finale con statistiche
```

## Compatibilità

- **Backward Compatible**: Il sistema continua a funzionare con il metodo originale per client non-Salesforce
- **Configurazione**: Nessuna configurazione aggiuntiva richiesta
- **Associazioni**: Piena compatibilità con il sistema di associazioni esistente

## Logging e Debug

Il sistema include logging dettagliato con prefisso "COMPOSITE:" per tracciare:
- Analisi delle associazioni
- Suddivisione dei batch
- Risultati delle operazioni composite
- Creazione/aggiornamento associazioni
- Gestione errori

## Limitazioni e Gestione Automatica

### Limite Salesforce: 25 Operazioni per Composite Request
Salesforce limita le Composite API a massimo 25 operazioni per singola richiesta. La nostra implementazione gestisce questo limite automaticamente:

- **Batching Automatico**: Le operazioni vengono suddivise automaticamente in chunk da max 25
- **Esecuzione Parallela**: I batch vengono eseguiti simultaneamente per massimizzare le performance
- **Aggregazione Risultati**: I risultati di tutti i batch vengono combinati in un unico risultato
- **Fallback Trasparente**: Se il numero di operazioni è <= 25, viene eseguita una singola richiesta

### Altre Limitazioni
1. **Solo Salesforce**: Le ottimizzazioni composite funzionano solo con Salesforce
2. **Dipendenze**: Richiede le nuove classi composite nel SalesforceServiceClient
3. **Gestione Errori**: Errori a livello di batch vengono propagati immediatamente

## Testing

Per testare l'implementazione:
1. Configurare una connessione Salesforce
2. Preparare dati sorgente con mix di record nuovi e esistenti (>25 per testare il batching)
3. Osservare i log per confermare l'uso delle chiamate composite con batching automatico
4. Verificare che le associazioni vengano create/aggiornate correttamente
5. Testare con grandi dataset per verificare la gestione automatica dei batch

## Considerazioni Future

1. **Throttling Automatico**: Implementare rate limiting intelligente per evitare limiti API
2. **Retry Logic con Exponential Backoff**: Aggiungere retry automatico per singoli batch falliti
3. **Metrics e Performance**: Raccogliere metriche sulla performance delle operazioni parallele
4. **Configurabilità**: Permettere configurazione del livello di parallelismo 
5. **Altri Provider**: Estendere il pattern ad altri provider REST che supportano batch operations