objets_metier_rs 1.0.2

# FAQ - Questions Fréquentes


## Table des matières


- [Installation et Configuration](#installation-et-configuration)
- [Connexion à Sage 100c](#connexion-à-sage-100c)
- [Utilisation des Factories](#utilisation-des-factories)
- [Gestion des Erreurs](#gestion-des-erreurs)
- [Performance](#performance)
- [Modules et Fonctionnalités](#modules-et-fonctionnalités)
- [Développement et Contribution](#développement-et-contribution)

---

## Installation et Configuration


### Q: Quelle version de Rust dois-je utiliser ?


**R:** La bibliothèque nécessite **Rust 1.70+** (édition 2021). Nous recommandons d'utiliser la dernière version stable :

```bash
rustup update stable
```

### Q: Comment installer la bibliothèque dans mon projet ?


**R:** Ajoutez la dépendance dans votre `Cargo.toml` :

```toml
[dependencies]
objets_metier_rs = "1.0.0"
```

Ou depuis crates.io :

```bash
cargo add objets_metier_rs
```

### Q: La bibliothèque fonctionne-t-elle sur Linux/macOS ?


**R:** **Non**, la bibliothèque est **exclusivement Windows** car elle utilise COM (Component Object Model) qui est une technologie native Windows. Sage 100c lui-même n'est disponible que sur Windows.

### Q: Dois-je installer Sage 100c pour utiliser la bibliothèque ?


**R:** **Oui**, vous devez avoir :
1. Sage 100c installé avec la DLL `objets100c.dll`
2. Une licence Sage 100c valide
3. Une base de données Sage accessible

La bibliothèque est un **wrapper** autour des objets COM Sage, elle ne peut pas fonctionner de manière autonome.

### Q: Comment enregistrer la DLL objets100c.dll ?


**R:** Exécutez cette commande en tant qu'**administrateur** :

```powershell
regsvr32 "C:\Program Files\Sage\Sage 100c\objets100c.dll"
```

Vérifiez le chemin exact selon votre installation Sage.

---

## Connexion à Sage 100c


### Q: Comment me connecter à une base Sage ?


**R:** Voici un exemple complet :

```rust
use objets_metier_rs::{CptaApplication, SageResult};

fn main() -> SageResult<()> {
    // 1. Créer l'application
    let app = CptaApplication::new("309DE0FB-9FB8-4F4E-8295-CC60C60DAA33")?;
    
    // 2. Définir la base
    app.set_name(r"D:\Sage\BIJOU.MAE")?;
    
    // 3. Authentification
    let loggable = app.loggable()?;
    loggable.set_user_name("<Administrateur>")?;
    loggable.set_user_password("")?;
    
    // 4. Ouvrir
    app.open()?;
    
    println!("✅ Connecté !");
    Ok(())
}
```

### Q: Quel est le CLSID pour le module Comptabilité ? Pour le Commercial ?


**R:** 
- **Comptabilité** : `309DE0FB-9FB8-4F4E-8295-CC60C60DAA33`
- **Commercial** : `ED0EC116-16B8-44CC-A68A-41BF6E15EB3F`

Utilisez-les avec `CptaApplication::new()` ou `CialApplication::new()`.

### Q: Comment gérer plusieurs bases en même temps ?


**R:** Créez plusieurs instances d'application :

```rust
let bijou = CptaApplication::new("309DE0FB-9FB8-4F4E-8295-CC60C60DAA33")?;
bijou.set_name(r"D:\Sage\BIJOU.MAE")?;
bijou.open()?;

let production = CptaApplication::new("309DE0FB-9FB8-4F4E-8295-CC60C60DAA33")?;
production.set_name(r"D:\Sage\PROD.MAE")?;
production.open()?;
```

Chaque instance est indépendante et gère sa propre connexion COM.

### Q: L'utilisateur `<Administrateur>` est-il obligatoire ?


**R:** Non, vous pouvez utiliser n'importe quel utilisateur Sage avec les droits appropriés. `<Administrateur>` est l'utilisateur par défaut avec tous les droits.

---

## Utilisation des Factories


### Q: Qu'est-ce qu'une Factory dans Sage 100c ?


**R:** Une **Factory** est un objet qui permet de créer, lire, modifier et supprimer des entités métier (comptes, écritures, tiers, articles, etc.). C'est l'équivalent d'un **Repository** en architecture logicielle.

### Q: Comment lister tous les journaux comptables ?


**R:**

```rust
let factory_journal = app.factory_journal()?;
let journaux = factory_journal.list()?;

for journal in journaux {
    println!("Code: {}, Intitulé: {}", 
             journal.jo_code()?, 
             journal.jo_intitule()?);
}
```

### Q: Quelle est la différence entre `list()` et `list_forward()` ?


**R:**
- **`list()`** : Charge toutes les entités en mémoire (plus lent mais plus simple)
- **`list_forward()`** : Utilise un curseur optimisé (plus rapide pour grandes collections)

Pour des collections < 1000 éléments, utilisez `list()`. Au-delà, préférez `list_forward()`.

### Q: Comment filtrer les résultats avec `query_predicate()` ?


**R:**

```rust
// Filtrer les comptes du type "Détail"
let comptes = factory_compte.query_predicate("[CG_Type] = 1")?;

// Filtrer les journaux de vente
let journaux_vente = factory_journal.query_predicate("[JO_Type] = 4")?;

// Filtrer les articles d'une famille
let articles = factory_article.query_predicate("[FA_CodeFamille] = 'MAT'")?;
```

La syntaxe est celle des **requêtes SQL WHERE**.

### Q: Comment créer une nouvelle entité ?


**R:**

```rust
// 1. Créer l'objet
let mut taxe = factory_taxe.create()?;

// 2. Définir les propriétés
taxe.set_ta_code("TVA20")?;
taxe.set_ta_intitule("TVA 20%")?;
taxe.set_ta_taux(20.0)?;
taxe.set_ta_type(1)?; // Collectée

// 3. Enregistrer (Write)
taxe.write()?;
```

### Q: Toutes les factories ont-elles les mêmes méthodes ?


**R:** Non, mais beaucoup partagent des **traits communs** :

| Trait | Méthodes | Factories |
|-------|----------|-----------|
| `FactoryRead<T>` | `list()`, `list_forward()`, `query_predicate()` | 37/38 CPTA, 38/38 CIAL |
| `FactoryReadByNumero<T>` | `read_numero()`, `exist_numero()` | Journal, Compte, Tiers, etc. |
| `FactoryReadByCode<T>` | `read_code()`, `exist_code()` | Taxe, Devise, etc. |
| `FactoryCreate<T>` | `create()` | 34/38 CPTA, 38/38 CIAL |
| `FactorySyncable<T>` | `query_synchro()`, `query_synchro_removed()` | 27/38 CPTA |

Consultez [TRAITS_GUIDE.md](TRAITS_GUIDE.md) pour plus de détails.

---

## Gestion des Erreurs


### Q: Comment gérer les erreurs proprement ?


**R:** Utilisez le type `SageResult<T>` et l'opérateur `?` :

```rust
use objets_metier_rs::{SageResult, SageError};

fn ma_fonction() -> SageResult<()> {
    let app = CptaApplication::new("...")?; // Propage l'erreur
    app.open()?;
    
    // Gestion spécifique
    match app.factory_journal() {
        Ok(factory) => {
            // Traitement
        },
        Err(SageError::ComError { code, message }) => {
            eprintln!("Erreur COM {}: {}", code, message);
        },
        Err(e) => {
            eprintln!("Autre erreur: {}", e);
        }
    }
    
    Ok(())
}
```

### Q: Quels sont les types d'erreurs possibles ?


**R:** La bibliothèque définit plusieurs types d'erreurs via `SageError` :

```rust
pub enum SageError {
    ComError { code: i32, message: String },      // Erreur COM/Sage
    ConversionError(String),                       // Conversion VARIANT
    MethodCall { method: String, id: i32, message: String },
    InternalError(String),                         // Erreur interne
    Utf16Error(String),                            // Encodage UTF-16
}
```

### Q: Comment logger les erreurs pour le débogage ?


**R:**

```rust
use log::{error, warn, info};

match app.open() {
    Ok(_) => info!("Base ouverte avec succès"),
    Err(e) => {
        error!("Impossible d'ouvrir la base: {}", e);
        // Traitement de l'erreur
    }
}
```

Utilisez `env_logger` ou `tracing` pour capturer les logs.

---

## Performance


### Q: Comment optimiser les performances de lecture ?


**R:**

1. **Utilisez `list_forward()` pour grandes collections** :
```rust
let articles = factory_article.list_forward()?; // Plus rapide
```

2. **Filtrez avec `query_predicate()` côté Sage** :
```rust
// ✅ Bon : filtrage côté Sage
let articles = factory.query_predicate("[AR_Sommeille] = 0")?;

// ❌ Mauvais : filtrage côté Rust
let articles = factory.list()?
    .into_iter()
    .filter(|a| a.ar_sommeille().unwrap() == 0)
    .collect();
```

3. **Utilisez le cache pour lectures répétées** :
```rust
use objets_metier_rs::cache::FactoryCache;

let cache = FactoryCache::new(Duration::from_secs(300));

// Premier appel : lecture Sage
let article = cached_read(&factory, &cache, "ART001")?;

// Appels suivants : depuis cache
let article = cached_read(&factory, &cache, "ART001")?; // Instantané
```

### Q: Combien d'entités puis-je traiter par seconde ?


**R:** Les benchmarks montrent (sur config moyenne) :

| Opération | Performance | Notes |
|-----------|-------------|-------|
| `list()` 100 items | ~100-200ms | Dépend de la complexité |
| `read_numero()` avec cache | ~1-5ms | Très rapide |
| `read_numero()` sans cache | ~20-50ms | Appel COM |
| `create()` + `write()` | ~50-100ms | Écriture en base |
| `query_predicate()` 1000 items | ~500-1000ms | Dépend du filtre |

Voir [benches/](../benches/) pour plus de détails.

### Q: Comment traiter de gros volumes de données ?


**R:**

```rust
// Traitement par batch
const BATCH_SIZE: usize = 100;

let articles = factory_article.list_forward()?;

for chunk in articles.chunks(BATCH_SIZE) {
    // Traiter le batch
    for article in chunk {
        // Traitement
    }
    
    // Pause optionnelle
    std::thread::sleep(Duration::from_millis(100));
}
```

---

## Modules et Fonctionnalités


### Q: Quels modules Sage sont supportés ?


**R:**

| Module | Status | Factories | Version |
|--------|--------|-----------|---------|
| 💼 **Comptabilité** | ✅ Complet | 37/38 (97%) | v1.0.0 |
| 🛒 **Commercial** | ✅ Complet | 38/38 (100%) | v1.0.0 |
| 💰 **Paie** | 📋 Planifié | 0% | v0.4.0+ |
| 📊 **Immobilisations** | 📋 Planifié | 0% | v0.5.0+ |
| 🏦 **Trésorerie** | 📋 Planifié | 0% | v0.6.0+ |

### Q: Comment créer une écriture comptable complète ?


**R:** Utilisez le processus **PMEncoder** :

```rust
// 1. Créer le processus
let process = app.create_process_encoder()?;

// 2. Configurer l'en-tête
let journal = factory_journal.read_numero(1)?;
process.set_journal(&journal)?;
process.set_date("2024-01-15")?;
process.set_ec_piece(&journal.next_ec_piece("2024-01-15")?)?;
process.set_ec_intitule("Facture client")?;

// 3. Ajouter les lignes
let factory_ecriture_in = process.factory_ecriture_in()?;

let mut ligne_debit = factory_ecriture_in.create()?;
ligne_debit.set_compte_g(&compte_client)?;
ligne_debit.set_ec_montant(1200.0)?;
ligne_debit.set_ec_sens(0)?; // Débit

let mut ligne_credit = factory_ecriture_in.create()?;
ligne_credit.set_compte_g(&compte_vente)?;
ligne_credit.set_ec_montant(1200.0)?;
ligne_credit.set_ec_sens(1)?; // Crédit

// 4. Valider
if process.can_process()? {
    process.process()?;
    println!("✅ Écriture enregistrée");
}
```

Consultez [PMENCODER_GUIDE.md](PMENCODER_GUIDE.md) pour plus de détails.

### Q: Comment travailler avec les documents commerciaux ?


**R:**

```rust
use objets_metier_rs::CialApplication;

let app = CialApplication::new("ED0EC116-16B8-44CC-A68A-41BF6E15EB3F")?;
app.set_name(r"D:\Sage\BIJOU.MAE")?;
app.open()?;

// Lister les devis clients
let factory_doc = app.factory_document_vente()?;
let devis = factory_doc.query_predicate("[DO_Type] = 0")?; // Type devis

for doc in devis {
    println!("Devis {} - Client: {} - Montant: {}", 
             doc.do_piece()?,
             doc.do_tiers()?,
             doc.do_totalttc()?);
}
```

### Q: Les traits Rust sont-ils supportés pour la programmation générique ?


**R:** **Oui !** La v1.0.0 introduit un système complet de traits. Exemple :

```rust
use objets_metier_rs::wrappers::cpta::traits::FactoryRead;

fn lister_entites<F, T>(factory: &F) -> SageResult<()>
where
    F: FactoryRead<T>,
    T: std::fmt::Debug,
{
    let items = factory.list()?;
    for item in items {
        println!("{:?}", item);
    }
    Ok(())
}

// Fonctionne avec n'importe quelle factory !
lister_entites(&factory_journal)?;
lister_entites(&factory_compte)?;
lister_entites(&factory_article)?;
```

Consultez [TRAITS_GUIDE.md](TRAITS_GUIDE.md).

---

## Développement et Contribution


### Q: Comment exécuter les tests ?


**R:**

```bash
# Tous les tests unitaires

cargo test

# Tests d'un module spécifique

cargo test --package objets_metier_rs --lib com

# Tests des exemples (nécessite Sage)

cargo test --examples

# Avec logs

RUST_LOG=debug cargo test
```

### Q: Comment lancer les exemples ?


**R:**

```bash
# Définir les variables d'environnement

$env:SAGE_DATABASE="D:\Sage\BIJOU.MAE"
$env:SAGE_USERNAME="<Administrateur>"
$env:SAGE_PASSWORD=""

# Lancer un exemple

cargo run --example sage_connection_demo
cargo run --example elegant_syntax
cargo run --example advanced_traits
```

### Q: Comment contribuer au projet ?


**R:** Consultez [CONTRIBUTING.md](../CONTRIBUTING.md) pour le guide complet :

1. Fork le projet
2. Créer une branche (`git checkout -b feature/ma-fonctionnalite`)
3. Coder avec les standards du projet (`cargo fmt`, `cargo clippy`)
4. Tester (`cargo test`)
5. Commit (`git commit -m 'Ajout nouvelle fonctionnalité'`)
6. Push (`git push origin feature/ma-fonctionnalite`)
7. Ouvrir une Pull Request

### Q: Comment générer la documentation ?


**R:**

```bash
# Documentation complète avec dépendances

cargo doc --open

# Documentation du projet uniquement

cargo doc --no-deps --open

# Documentation privée incluse

cargo doc --document-private-items --open
```

### Q: Où trouver plus d'aide ?


**R:**

- 📖 **Documentation** : [README.md](../README.md)
- 🐛 **Issues** : https://github.com/your-repo/objets_metier_rs/issues
- 💬 **Discussions** : https://github.com/your-repo/objets_metier_rs/discussions
- 📧 **Email** : support@your-domain.com
- 📚 **Guides** : [docs/](.)

---

## Questions non résolues ?


Si votre question n'est pas dans cette FAQ :

1. Consultez le [Guide de dépannage](troubleshooting.md)
2. Recherchez dans les [Issues fermées](https://github.com/your-repo/objets_metier_rs/issues?q=is%3Aissue+is%3Aclosed)
3. Ouvrez une [nouvelle Issue](https://github.com/your-repo/objets_metier_rs/issues/new)
4. Posez votre question dans [Discussions](https://github.com/your-repo/objets_metier_rs/discussions)

---

**Dernière mise à jour** : 2025-01-20 (v1.0.0)