feat: implementare SyncOrchestrationService per gestione state e retry sync

[artcava]

🎯 Obiettivo

Implementare un servizio di orchestrazione sync che gestisca lo stato di avanzamento delle operazioni di sincronizzazione (export/import), progress reporting, retry automatici e rollback parziali.

📋 Contesto

La sincronizzazione (#52, #53) coinvolge operazioni complesse:

• Export: selezione dati, serializzazione, cifratura, firma HMAC, salvataggio file
• Import: lettura file, verifica HMAC, decifratura, deserializzazione, conflict detection, merge dati

Problemi da risolvere:

• Progress reporting: utente deve vedere avanzamento operazione ("Esportazione 45% completata")
• Retry automatici: se import fallisce per errore transiente (file lock), riprovare
• Rollback parziale: se import di un pacchetto fallisce a metà, annullare modifiche già applicate
• Stato persistente: tracciare quali pacchetti sono stati importati/esportati con successo

📦 Servizio da Implementare

ISyncOrchestrationService + SyncOrchestrationService

Metodi principali (proposta):

public interface ISyncOrchestrationService
{
    // Export orchestration
    Task<SyncOperationResult> ExportPackageAsync(
        ExportRequest request,
        IProgress<SyncProgress>? progress = null,
        CancellationToken ct = default);
    
    // Import orchestration
    Task<SyncOperationResult> ImportPackageAsync(
        ImportRequest request,
        IProgress<SyncProgress>? progress = null,
        CancellationToken ct = default);
    
    // Stato sincronizzazione
    Task<IReadOnlyList<SyncHistoryEntry>> GetSyncHistoryAsync(
        DateTime? from = null,
        DateTime? to = null,
        CancellationToken ct = default);
    
    // Retry e rollback
    Task<SyncOperationResult> RetryFailedImportAsync(
        Guid syncOperationId,
        CancellationToken ct = default);
    
    Task RollbackImportAsync(
        Guid syncOperationId,
        CancellationToken ct = default);
}

public record ExportRequest(
    Guid OperatorId,
    DateTime FromDate,
    DateTime ToDate,
    string OutputPath
);

public record ImportRequest(
    string PackageFilePath,
    ConflictResolutionStrategy DefaultStrategy
);

public record SyncOperationResult(
    bool Success,
    Guid OperationId,
    string? ErrorMessage,
    int EntitiesProcessed,
    int ConflictsDetected,
    TimeSpan Duration
);

public record SyncProgress(
    int CurrentStep,
    int TotalSteps,
    string CurrentStepDescription,
    int PercentComplete
);

public record SyncHistoryEntry(
    Guid OperationId,
    SyncOperationType Type, // Export / Import
    DateTime StartedAt,
    DateTime? CompletedAt,
    SyncOperationStatus Status, // InProgress / Completed / Failed / RolledBack
    int EntitiesProcessed,
    int ConflictsResolved,
    string? ErrorMessage
);

public enum SyncOperationType
{
    Export,
    Import
}

public enum SyncOperationStatus
{
    InProgress,
    Completed,
    Failed,
    RolledBack
}

Modello Dati SyncOperation

public class SyncOperation
{
    public Guid Id { get; set; }
    public SyncOperationType Type { get; set; }
    public SyncOperationStatus Status { get; set; }
    
    public Guid PerformedBy { get; set; }
    public DateTime StartedAt { get; set; }
    public DateTime? CompletedAt { get; set; }
    
    public string? PackageFilePath { get; set; }
    public int EntitiesProcessed { get; set; }
    public int ConflictsDetected { get; set; }
    public int ConflictsResolved { get; set; }
    
    public string? ErrorMessage { get; set; }
    public string? ErrorStackTrace { get; set; }
    
    // Per rollback
    public string? SnapshotData { get; set; } // JSON con stato pre-import
}

📋 Tasks

• Creare entità SyncOperation in PTRP.Models/
• Creare enum SyncOperationType, SyncOperationStatus in PTRP.Models/Enums/
• Creare migration EF Core per tabella SyncOperations
• Definire ISyncOrchestrationService in PTRP.Services/Interfaces/
• Implementare SyncOrchestrationService in PTRP.Services/
• Implementare repository ISyncOperationRepository in PTRP.Data/
• Implementare logica di progress reporting con IProgress<T>
• Implementare retry con Polly (max 3 tentativi, backoff esponenziale)
• Implementare rollback:
  • Snapshot stato DB prima di import
  • Ripristino snapshot in caso di errore
• Integrare con servizi esistenti (Implementare crittografia AES-256 per database SQLite e payload di sincronizzazione #2, Gestione chiavi crittografiche (master key, HMAC key, rotazione) #3 per cifratura/firma)
• Registrare servizio in DI container
• Aggiungere unit tests per retry e rollback

🎯 UI Integration (FASE 3)

• Progress bar in SyncView (FASE 3 - Sync & Advanced: UI Sincronizzazione (Import/Export Pacchetti) #52) collegata a IProgress<SyncProgress>
• Lista "Storico Sincronizzazioni" con stato operazioni
• Bottone "Riprova" per operazioni fallite
• Bottone "Annulla Importazione" per rollback
• Snackbar con feedback su successo/errore sync

✅ Acceptance Criteria

• Export/Import mostrano progress in tempo reale (0-100%)
• In caso di errore transiente, sistema riprova automaticamente (max 3 volte)
• In caso di errore critico, rollback automatico annulla modifiche parziali
• Storico sincronizzazioni visibile in UI con filtri per data/tipo/stato
• Possibile riprovare manualmente un'importazione fallita
• Test coverage ≥ 70% per logiche retry/rollback

🔗 Riferimenti

• FASE 3 - Sync & Advanced: UI Sincronizzazione (Import/Export Pacchetti) #52 - UI Sincronizzazione
• FASE 3 - Sync & Advanced: Conflict Resolution UI #53 - Conflict Resolution UI
• Implementare crittografia AES-256 per database SQLite e payload di sincronizzazione #2 - Crittografia payload
• Gestione chiavi crittografiche (master key, HMAC key, rotazione) #3 - Gestione chiavi
• Implementare audit trail per entità cliniche e log di sincronizzazione #1 - Audit trail (logging sync operations)
• docs/PROGETTO_PTRP_SYNC.md - protocollo sincronizzazione

---

CLUSTER: Services & Orchestrazione (gap 5.2)
FASE: 3 - Sync & Advanced
PRIORITÀ: 🟡 ALTA
DIPENDENZE: #52, #2, #3
BLOCKING: UX robusta per sincronizzazione