khadhroony-bot3/kb-app-demo-desktop/USAGE.md

<!-- 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.