objets_metier_rs 1.0.2

//! Trait pour la synchronisation d'entités
//!
//! Ce trait standardise les méthodes de synchronisation permettant de récupérer
//! les entités modifiées ou supprimées depuis une date/heure donnée.

use crate::errors::SageResult;

/// Trait pour les factories supportant la synchronisation
///
/// Ce trait fournit une interface commune pour synchroniser les données entre
/// un système externe et Sage. Il permet de récupérer uniquement les entités
/// qui ont été modifiées ou supprimées depuis la dernière synchronisation.
///
/// # Type Parameter
///
/// * `T` - Le type d'entité synchronisé
///
/// # Workflow de synchronisation
///
/// 1. Sauvegarder la date/heure de dernière synchro
/// 2. Appeler `query_synchro()` pour récupérer les entités modifiées
/// 3. Appeler `query_synchro_removed()` pour récupérer les entités supprimées
/// 4. Mettre à jour le système externe
/// 5. Sauvegarder la nouvelle date/heure de synchro
///
/// # Exemple
///
/// ```rust,ignore
/// use objets_metier_rs::wrappers::cpta::traits::FactorySyncable;
/// use chrono::Utc;
///
/// fn synchroniser<F, T>(factory: &F) -> SageResult<()>
/// where
///     F: FactorySyncable<T>,
///     T: std::fmt::Debug,
/// {
///     // Récupérer les entités modifiées
///     let modifiees = factory.query_synchro()?;
///     println!("Entités modifiées : {}", modifiees.len());
///     
///     // Récupérer les entités supprimées
///     let supprimees = factory.query_synchro_removed()?;
///     println!("Entités supprimées : {}", supprimees.len());
///     
///     // Traiter les modifications...
///     
///     Ok(())
/// }
/// ```
pub trait FactorySyncable<T> {
    /// Récupère les entités modifiées depuis la dernière synchronisation
    ///
    /// Cette méthode retourne toutes les entités qui ont été créées ou modifiées
    /// depuis la dernière synchronisation. La date de référence est gérée
    /// automatiquement par Sage en fonction du paramétrage de synchronisation.
    ///
    /// # Returns
    ///
    /// Un vecteur contenant toutes les entités modifiées
    ///
    /// # Errors
    ///
    /// Retourne une erreur si :
    /// - La connexion COM échoue
    /// - La requête de synchronisation échoue
    /// - Le dossier n'est pas configuré pour la synchronisation
    ///
    /// # Notes
    ///
    /// - La synchronisation doit être activée dans Sage
    /// - Sage mémorise la date de dernière synchro par utilisateur/poste
    /// - Les nouvelles entités sont considérées comme "modifiées"
    ///
    /// # Exemple
    ///
    /// ```rust,ignore
    /// // Récupérer tous les journaux modifiés
    /// let journaux_modifies = factory_journal.query_synchro()?;
    ///
    /// for journal in journaux_modifies {
    ///     println!("Journal modifié : {}", journal.intitule()?);
    ///     // Synchroniser avec le système externe...
    /// }
    /// ```
    fn query_synchro(&self) -> SageResult<Vec<T>>;

    /// Récupère les entités supprimées depuis la dernière synchronisation
    ///
    /// Cette méthode retourne toutes les entités qui ont été supprimées
    /// depuis la dernière synchronisation. Les entités supprimées ne contiennent
    /// généralement que les identifiants (numéro, code, etc.).
    ///
    /// # Returns
    ///
    /// Un vecteur contenant les références aux entités supprimées
    ///
    /// # Errors
    ///
    /// Retourne une erreur si :
    /// - La connexion COM échoue
    /// - La requête de synchronisation échoue
    /// - Le dossier n'est pas configuré pour la synchronisation
    ///
    /// # Notes
    ///
    /// - Les objets retournés peuvent avoir des propriétés limitées
    /// - Seuls les identifiants sont généralement disponibles
    /// - Les suppressions sont historisées pour la synchronisation
    ///
    /// # Exemple
    ///
    /// ```rust,ignore
    /// // Récupérer tous les comptes supprimés
    /// let comptes_supprimes = factory_compte_g.query_synchro_removed()?;
    ///
    /// for compte in comptes_supprimes {
    ///     let numero = compte.numero()?;
    ///     println!("Compte supprimé : {}", numero);
    ///     // Supprimer du système externe...
    /// }
    /// ```
    fn query_synchro_removed(&self) -> SageResult<Vec<T>>;
}

/// Extension du trait FactorySyncable avec synchronisation par OID
///
/// Certaines factories supportent une synchronisation plus fine basée sur
/// les Object IDs (OID) Sage. Ce trait optionnel permet une synchronisation
/// incrémentale plus efficace.
///
/// # Note
///
/// Ce trait n'est disponible que pour certaines entités spécifiques
/// (principalement les écritures comptables).
#[allow(dead_code)] // Sera utilisé dans les futures versions
pub trait FactorySyncableByOID<T>: FactorySyncable<T> {
    /// Récupère les entités modifiées par OID
    ///
    /// # Arguments
    ///
    /// * `last_oid` - Dernier OID synchronisé (0 pour tout récupérer)
    ///
    /// # Returns
    ///
    /// Un vecteur d'entités avec OID > last_oid
    fn query_synchro_oid(&self, last_oid: i64) -> SageResult<Vec<T>>;
}