112 lines
3.0 KiB
Markdown
112 lines
3.0 KiB
Markdown
<!-- file: docs/rules/SCENARIO_CONVENTION.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Convention des scenarios KSP
|
|
|
|
## Objet
|
|
|
|
KSP n'impose pas actuellement de `ksp-scenario-api`.
|
|
|
|
Ce document définit les conventions minimales permettant aux crates `ksp-scenario-<domain>-lib` de rester cohérentes sans les enfermer dans un trait Rust universel.
|
|
|
|
## Source de vérité
|
|
|
|
La logique fonctionnelle du scenario appartient à :
|
|
|
|
```text
|
|
ksp-scenario-<domain>-lib
|
|
```
|
|
|
|
Une application desktop demo, un CLI, un test ou une CI appelle cette bibliothèque et ne recrée pas le workflow.
|
|
|
|
## Indépendance de l'interface
|
|
|
|
Une crate scenario :
|
|
|
|
- ne dépend pas de Tauri ;
|
|
- ne contient pas de DTO TS-RS spécifiques à une UI ;
|
|
- ne suppose pas qu'une fenêtre desktop existe ;
|
|
- reste appelable depuis un test ou autre interface.
|
|
|
|
## Environnement
|
|
|
|
Un scenario indique explicitement l'environnement/réseau attendu lorsqu'il est contraint.
|
|
|
|
Une app demo dont l'environnement est imposé suit la nomenclature :
|
|
|
|
```text
|
|
ksp-app-scenario-<domain>-<environment>-desk-demo
|
|
```
|
|
|
|
## Configuration et ressources
|
|
|
|
Le scenario utilise les bibliothèques KSP propriétaires de :
|
|
|
|
- configuration ;
|
|
- wallet ;
|
|
- transport ;
|
|
- Program ;
|
|
- execution ;
|
|
- Store lorsque le scenario en a réellement besoin.
|
|
|
|
Il ne contourne pas ces frontières avec des dépendances protocolaires/Solana externes directes.
|
|
|
|
Les endpoints, wallets et autres ressources utilisées doivent être résolus explicitement ; ils ne sont pas cachés dans l'UI.
|
|
|
|
## Execution policy
|
|
|
|
Lorsqu'un scenario exécute une opération réelle, il fournit une policy explicite conforme à `ksp-execution-policy-api`.
|
|
|
|
Une policy Devnet peut être propre à la crate scenario.
|
|
|
|
La policy ne fuit pas dans `ksp-program-lib`.
|
|
|
|
## Résultat
|
|
|
|
Un scenario doit produire un résultat exploitable par son caller.
|
|
|
|
Le résultat devrait permettre selon le besoin de distinguer :
|
|
|
|
- succès/échec fonctionnel ;
|
|
- étapes exécutées ;
|
|
- identités blockchain utiles ;
|
|
- validations/evidence ;
|
|
- warnings ;
|
|
- données de diagnostic non sensibles.
|
|
|
|
Le type exact reste spécifique au domaine tant qu'un vrai contrat commun ne justifie pas `ksp-scenario-api`.
|
|
|
|
## Validation
|
|
|
|
Le scenario contient la logique de validation fonctionnelle nécessaire pour déterminer si son objectif a été atteint.
|
|
|
|
L'application demo affiche cette validation mais ne la réimplémente pas.
|
|
|
|
## Logging
|
|
|
|
La crate scenario utilise `ksp-logging-lib`.
|
|
|
|
Les logs peuvent couvrir `error`, `warn`, `info`, `debug` et `trace` selon pertinence.
|
|
|
|
Aucun secret, seed, clé privée ou donnée sensible ne doit être loggé.
|
|
|
|
## Réutilisation
|
|
|
|
Une même crate scenario doit pouvoir être utilisée par plusieurs callers sans duplication :
|
|
|
|
```text
|
|
desktop demo
|
|
test
|
|
future CLI/tool
|
|
CI/integration
|
|
|
|
|
v
|
|
ksp-scenario-<domain>-lib
|
|
```
|
|
|
|
## Evolution
|
|
|
|
Une convention peut être enrichie au fil des scenarios réels.
|
|
|
|
`ksp-scenario-api` ne sera introduit que si plusieurs implementations démontrent un contrat commun stable et utile.
|