v0.1.0-pre.071

kb-app-demo-desktop/USAGE.md

@@ -0,0 +1,246 @@
+<!-- file: kb-app-demo-desktop/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de kb-app-demo-desktop
+
+## Objectif
+
+L’application expose une interface opérateur pour diagnostiquer, simuler et valider les couches de bot3.
+
+## Lancer le desktop
+
+Depuis la racine du workspace :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+Le binaire applique un verrou d’instance locale. Une deuxième instance doit échouer proprement.
+
+## API Rust publique
+
+La bibliothèque expose uniquement `run()` :
+
+```rust
+fn launch_desktop() -> kb_core::Result<()> {
+    return kb_app_demo_desktop_lib::run();
+}
+```
+
+Le binaire `kb-app-demo-desktop` appelle cette fonction et convertit son résultat en `ExitCode`.
+
+## Fenêtres initiales
+
+La configuration Tauri crée :
+
+- `splash` ;
+- `main`.
+
+Les autres fenêtres sont ouvertes par les commandes Tauri dédiées :
+
+- backfill ;
+- HTTP ;
+- WebSocket ;
+- diagnostics SQL ;
+- candidats replay ;
+- configuration ;
+- extraction Core ;
+- decode replay ;
+- exécution Solana Core ;
+- exécution SPL.
+
+## Interface Tauri publique
+
+Les commandes Tauri constituent l’interface applicative frontend/backend. Elles ne sont pas des APIs Rust publiques pour les autres crates.
+
+### Ouvrir une fenêtre
+
+```typescript
+import { invoke } from "@tauri-apps/api/core";
+
+await invoke("open_demo_http_window");
+await invoke("open_demo_ws_window");
+await invoke("open_demo_decode_replay_window");
+```
+
+### Charger les options HTTP
+
+```typescript
+const options = await invoke("demo_http_options");
+console.log(options);
+```
+
+### Exécuter une requête HTTP de démonstration
+
+```typescript
+const result = await invoke(
+  "demo_http_execute_request",
+  {
+    request: {
+      role: "standard",
+      method: "getHealth",
+      paramsJson: "[]"
+    }
+  }
+);
+
+console.log(result);
+```
+
+Les champs exacts du payload doivent rester synchronisés avec les types TS-RS générés.
+
+### Gérer une session WebSocket
+
+```typescript
+const status = await invoke("demo_ws_status");
+console.log(status);
+
+await invoke("demo_ws_connect", {
+  request: {
+    role: "standard",
+    method: "logsSubscribe",
+    paramsJson: "[]"
+  }
+});
+
+await invoke("demo_ws_unsubscribe");
+await invoke("demo_ws_disconnect");
+```
+
+La fermeture de la fenêtre ne doit pas être assimilée à une demande de déconnexion.
+
+### Lancer un backfill
+
+```typescript
+const options = await invoke("demo_backfill_options");
+console.log(options);
+
+const summary = await invoke(
+  "demo_backfill_execute",
+  {
+    request: {
+      profileName: "devnet",
+      address: "11111111111111111111111111111111",
+      limit: 100
+    }
+  }
+);
+
+console.log(summary);
+```
+
+### Extraction Core
+
+```typescript
+const options = await invoke(
+  "demo_core_extraction_options"
+);
+
+const summary = await invoke(
+  "demo_core_extraction_execute",
+  {
+    request: {
+      profileName: "devnet",
+      limit: 1000
+    }
+  }
+);
+
+console.log(options, summary);
+```
+
+Une campagne longue peut être annulée avec `demo_core_extraction_cancel`.
+
+### Decode replay
+
+```typescript
+const options = await invoke(
+  "demo_decode_replay_options"
+);
+
+const summary = await invoke(
+  "demo_decode_replay_execute",
+  {
+    request: {
+      profileName: "devnet",
+      limit: 1000,
+      materialize: true
+    }
+  }
+);
+
+console.log(options, summary);
+```
+
+Les diagnostics et annotations sont accessibles par des commandes séparées.
+
+### Scénarios Devnet
+
+Les commandes couvrent notamment :
+
+- `demo_execution_solana_core_execute` ;
+- `demo_execution_spl_memo_execute` ;
+- `demo_execution_spl_token_execute` ;
+- `demo_execution_spl_ata_execute` ;
+- `demo_execution_spl_token_2022_execute`.
+
+```typescript
+const scenarios = await invoke(
+  "demo_execution_spl_validation_scenarios"
+);
+
+console.log(scenarios);
+```
+
+La simulation et l’envoi doivent rester explicitement distingués dans les requêtes.
+
+### Diagnostics PostgreSQL
+
+```typescript
+const diagnostics = await invoke(
+  "load_demo_sql_diag"
+);
+const rawTables = await invoke(
+  "load_demo_sql_pg_raw"
+);
+const coreTables = await invoke(
+  "load_demo_sql_pg_core"
+);
+
+console.log(diagnostics, rawTables, coreTables);
+```
+
+## Capabilities Tauri
+
+Les fenêtres autorisées sont listées dans `capabilities/default.json`. La capability active doit inclure au minimum les permissions Tauri Core et tracing nécessaires aux fenêtres déclarées.
+
+Toute nouvelle fenêtre ou commande sensible doit être auditée avant ajout de permissions.
+
+## Erreurs et invariants
+
+- une simulation ne doit jamais envoyer une transaction ;
+- une soumission nécessite une confirmation opérateur explicite ;
+- les secrets de wallet ne doivent jamais être sérialisés vers le frontend ;
+- les résultats frontend doivent refléter les validations réellement exécutées ;
+- l’état WebSocket appartient à l’application, pas à la durée de vie de la fenêtre ;
+- les commandes Tauri adaptent les APIs réutilisables sans dupliquer leur logique.
+
+## Tests de référence
+
+- tests des options et payloads HTTP ;
+- tests de cycle de vie WebSocket ;
+- tests de sélection de profil Devnet ;
+- tests de System Transfer et Memo ;
+- tests ATA, SPL Token et Token-2022 ;
+- tests de backfill, extraction Core et decode replay ;
+- tests de diagnostics SQL et exports CSV ;
+- tests de journalisation frontend ;
+- test du verrou d’état applicatif et de la séquence splash.
+
+La base validée de `pre.062` contient 117 tests pour cette crate.
+
+## Limites durables
+
+- le desktop est une application de démonstration et validation, pas le worker de production ;
+- les payloads Tauri sont une API applicative spécifique au frontend ;
+- l’application nécessite un environnement graphique pour sa validation complète.