80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
<!-- file: docs/guides/CONFIGURATION.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Guide de configuration
|
||
|
||
## Objectif
|
||
|
||
Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste `kb-config/USAGE.md`.
|
||
|
||
## Fichiers actifs
|
||
|
||
- `config/example.config.json` : exemple utilisateur complet ;
|
||
- `config/schema.config.json` : contrat JSON formel ;
|
||
- `.env` et variantes locales : valeurs d’environnement non versionnées ;
|
||
- `.env.example` : noms de variables attendues sans secrets.
|
||
|
||
Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.
|
||
|
||
## Séquence de chargement
|
||
|
||
1. charger les fichiers d’environnement autorisés avec `load_workspace_environment` ;
|
||
2. lire le fichier JSON ;
|
||
3. résoudre les placeholders `${NAME}` ou `${NAME:-fallback}` ;
|
||
4. parser avec `load_config_from_str` ou `load_config_from_path` ;
|
||
5. valider le schéma et les invariants typés ;
|
||
6. sélectionner le profil actif avec `active_profile`.
|
||
|
||
## Exemple opérateur
|
||
|
||
```rust
|
||
let environment = match kb_config::load_workspace_environment(
|
||
std::path::Path::new("."),
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
|
||
let config = match kb_config::load_config_from_path(
|
||
std::path::Path::new("config/example.config.json"),
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
|
||
let profile = match kb_config::active_profile(&config) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
|
||
println!("loaded environment files={}", environment.loaded_files.len());
|
||
println!("active profile={}", profile.name);
|
||
```
|
||
|
||
## Invariants
|
||
|
||
- aucun secret ne doit être ajouté à l’exemple versionné ;
|
||
- les placeholders non résolus doivent provoquer un diagnostic explicite ;
|
||
- le schéma embarqué et `config/schema.config.json` doivent rester identiques ;
|
||
- une sérialisation publique doit être précédée d’une validation ;
|
||
- les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
|
||
|
||
## Diagnostic
|
||
|
||
Pour isoler une erreur :
|
||
|
||
1. afficher la liste des fichiers d’environnement chargés ;
|
||
2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
|
||
3. valider le schéma ;
|
||
4. valider le modèle typé ;
|
||
5. vérifier le profil actif ;
|
||
6. vérifier les rôles HTTP, WebSocket, stockage et logging.
|
||
|
||
## Références
|
||
|
||
- `kb-config/README.md` ;
|
||
- `kb-config/USAGE.md` ;
|
||
- `kb-config/TODO.md` ;
|
||
- `config/README.md` ;
|
||
- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.
|