objets_metier_rs 1.0.2

Bibliothèque Rust moderne et sûre pour l'API COM Objets Métier Sage 100c - Production Ready
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

//! Trait pour la gestion des informations libres
//!
//! Ce trait standardise l'accès aux champs d'informations libres (champs personnalisés)
//! disponibles sur certaines entités Sage.

use crate::com::ComInstance;
use crate::errors::SageResult;

/// Trait pour les factories supportant les informations libres
///
/// Ce trait fournit une interface commune pour accéder et créer des champs
/// d'informations libres. Les informations libres permettent d'ajouter des champs
/// personnalisés aux entités Sage sans modifier le schéma de base de données.
///
/// # Types d'informations libres
///
/// Sage supporte plusieurs types de champs personnalisés :
/// - Texte (chaîne de caractères)
/// - Numérique (entier ou décimal)
/// - Date
/// - Case à cocher (booléen)
/// - Table (liste de valeurs prédéfinies)
///
/// # Exemple
///
/// ```rust,ignore
/// use objets_metier_rs::wrappers::cpta::traits::InfoLibreCapable;
///
/// fn afficher_infos_libres<F>(factory: &F) -> SageResult<()>
/// where
///     F: InfoLibreCapable,
/// {
///     let fields = factory.info_libre_fields()?;
///     
///     // Parcourir les champs d'informations libres
///     let count = fields.get_property_i32("Count")?;
///     println!("Nombre de champs personnalisés : {}", count);
///     
///     Ok(())
/// }
/// ```
pub trait InfoLibreCapable {
    /// Retourne la collection des champs d'informations libres
    ///
    /// Cette méthode permet d'accéder aux définitions des champs personnalisés
    /// configurés dans Sage pour le type d'entité concerné.
    ///
    /// # Returns
    ///
    /// Une instance COM représentant la collection de champs (IBOInfoLibreFields)
    ///
    /// # Errors
    ///
    /// Retourne une erreur si :
    /// - La connexion COM échoue
    /// - L'accès aux informations libres est refusé
    /// - Aucune information libre n'est configurée
    ///
    /// # Propriétés de la collection
    ///
    /// - `Count` - Nombre de champs d'informations libres
    /// - `Item(index)` - Accès à un champ par index (1-based)
    ///
    /// # Propriétés d'un champ
    ///
    /// - `IL_Intitule` - Libellé du champ
    /// - `IL_Type` - Type du champ (0=Texte, 1=Numérique, 2=Date, 3=Case, 4=Table)
    /// - `IL_Valeur` - Valeur actuelle du champ
    ///
    /// # Exemple
    ///
    /// ```rust,ignore
    /// // Accéder aux informations libres d'un journal
    /// let fields = factory_journal.info_libre_fields()?;
    /// let count = fields.get_property_i32("Count")?;
    ///
    /// for i in 1..=count {
    ///     let field = fields.call_method("Item", &[i.into()])?;
    ///     let intitule = field.get_property_string("IL_Intitule")?;
    ///     let valeur = field.get_property_string("IL_Valeur")?;
    ///     println!("{} = {}", intitule, valeur);
    /// }
    /// ```
    fn info_libre_fields(&self) -> SageResult<ComInstance>;

    /// Crée une nouvelle information libre
    ///
    /// Cette méthode permet de créer un nouveau champ d'information libre
    /// pour l'entité. Le champ créé doit ensuite être configuré et ajouté
    /// à la collection.
    ///
    /// # Returns
    ///
    /// Une nouvelle instance COM représentant un champ vide (IBOInfoLibre)
    ///
    /// # Errors
    ///
    /// Retourne une erreur si :
    /// - La connexion COM échoue
    /// - La création du champ échoue
    /// - Les droits d'accès sont insuffisants
    ///
    /// # Workflow de création
    ///
    /// 1. Appeler `create_info_libre()` pour créer un champ vide
    /// 2. Définir les propriétés du champ (intitulé, type, valeur)
    /// 3. Ajouter le champ à la collection via `Add()`
    ///
    /// # Exemple
    ///
    /// ```rust,ignore
    /// // Créer une nouvelle information libre "Code projet"
    /// let info_libre = factory_journal.create_info_libre()?;
    ///
    /// // Configurer le champ
    /// info_libre.set_property("IL_Intitule", "Code projet")?;
    /// info_libre.set_property("IL_Type", 0)?; // Type texte
    /// info_libre.set_property("IL_Valeur", "PROJ-2024-001")?;
    ///
    /// // Ajouter à la collection
    /// let fields = factory_journal.info_libre_fields()?;
    /// fields.call_method("Add", &[info_libre.into()])?;
    /// ```
    ///
    /// # Notes
    ///
    /// - Le champ n'est pas automatiquement ajouté à la collection
    /// - Il faut appeler `write()` sur l'entité pour persister les modifications
    /// - Les informations libres doivent être configurées dans Sage
    fn create_info_libre(&self) -> SageResult<ComInstance> {
        Err(crate::errors::SageError::UnsupportedOperation(
            "create_info_libre not implemented for this factory".to_string(),
        ))
    }
}