objets_metier_rs 1.0.2

//! Trait pour la création d'entités
//!
//! Ce trait standardise la méthode `create()` commune à la plupart des factories.

use crate::errors::SageResult;

/// Trait pour les factories supportant la création d'entités
///
/// Ce trait fournit une interface commune pour créer de nouvelles entités
/// dans Sage. Les entités créées sont initialement vides et doivent être
/// remplies avec des données avant d'appeler `write()`.
///
/// # Type Parameter
///
/// * `T` - Le type d'entité créé par la factory
///
/// # Workflow de création
///
/// 1. Appeler `create()` pour obtenir une nouvelle entité vide
/// 2. Définir les propriétés obligatoires de l'entité
/// 3. Appeler `write()` sur l'entité pour la sauvegarder
///
/// # Exemple
///
/// ```rust,ignore
/// use objets_metier_rs::wrappers::cpta::traits::FactoryCreate;
///
/// fn creer_nouveau<F, T>(factory: &F) -> SageResult<T>
/// where
///     F: FactoryCreate<T>,
/// {
///     let nouvelle_entite = factory.create()?;
///     // Remplir les propriétés de l'entité...
///     Ok(nouvelle_entite)
/// }
/// ```
///
/// # Exemple concret
///
/// ```rust,ignore
/// use objets_metier_rs::wrappers::cpta::factories::FactoryJournal;
/// use objets_metier_rs::wrappers::cpta::traits::FactoryCreate;
///
/// fn creer_journal_achats(factory: &FactoryJournal) -> SageResult<()> {
///     // Créer un nouveau journal
///     let journal = factory.create()?;
///     
///     // Définir les propriétés
///     journal.set_numero(5)?;
///     journal.set_intitule("Journal Achats")?;
///     journal.set_type(3)?; // Type = Achats
///     
///     // Sauvegarder
///     journal.write()?;
///     
///     Ok(())
/// }
/// ```
pub trait FactoryCreate<T> {
    /// Crée une nouvelle entité vide
    ///
    /// Cette méthode instancie une nouvelle entité non sauvegardée.
    /// L'entité retournée doit être configurée puis sauvegardée avec `write()`.
    ///
    /// # Returns
    ///
    /// Une nouvelle instance de l'entité, non encore persistée en base
    ///
    /// # Errors
    ///
    /// Retourne une erreur si :
    /// - La connexion COM échoue
    /// - La création de l'objet COM échoue
    /// - Les droits d'accès sont insuffisants
    ///
    /// # Notes
    ///
    /// - L'entité créée n'existe pas encore en base de données
    /// - Il faut appeler `write()` pour la persister
    /// - Certaines propriétés peuvent avoir des valeurs par défaut
    ///
    /// # Exemple
    ///
    /// ```rust,ignore
    /// // Créer un nouveau compte général
    /// let compte = factory_compte_g.create()?;
    /// compte.set_numero("411000")?;
    /// compte.set_intitule("Clients")?;
    /// compte.set_type(0)?; // Détail
    /// compte.write()?;
    /// println!("Compte créé avec succès");
    /// ```
    fn create(&self) -> SageResult<T>;
}