v0.3.8-pre.013

crates/ksp-app-store-desk/USAGE.md

@@ -0,0 +1,149 @@
+<!-- file: crates/ksp-app-store-desk/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de `ksp-app-store-desk`
+
+## 1. Lancement
+
+Depuis la racine du workspace :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri dev)
+```
+
+Le runtime charge le composite Store Desk via `ksp-config-lib`, initialise Logging puis ouvre le Store sélectionné via `ksp-store-lib`.
+
+## 2. Profil et readiness
+
+Le composite `cfg.composite.ksp-app-store-desk` sélectionne un profil Logging et un profil Store. Mainnet est le profil par défaut ; Devnet et Testnet sont également définis dans la configuration committed.
+
+La vue **Overview** expose notamment :
+
+```text
+Store open
+health state
+profile
+network
+backend kind
+migration version / pending migrations
+pool size / capacity / available / waiting
+```
+
+Ces informations sont des projections portables. Elles ne contiennent jamais URI PostgreSQL, credential, secret ou handle physique.
+
+## 3. RAW Transactions
+
+La vue **RAW Transactions** charge les données côté serveur via la façade d’inspection Store.
+
+Filtres disponibles :
+
+```text
+slot minimum
+slot maximum
+direction ascending / descending
+```
+
+La table affiche des summaries sans payload RAW complet. Les signatures et hashes longs restent copiables sans que leur valeur soit journalisée.
+
+Le bouton de détail recharge explicitement une seule Transaction. Le modal affiche les metadata canoniques, l’état de rétention et, lorsqu’un payload est encore retenu, un preview hexadécimal limité à 512 bytes avec taille exacte et indicateur de troncature.
+
+Un état `Purged` est présenté à partir du tombstone disponible. Aucune opération d’archive, purge ou force-rehydrate n’est proposée par l’application.
+
+## 4. RAW Accounts
+
+La vue **RAW Accounts** utilise le même modèle d’inspection server-side.
+
+Filtres disponibles :
+
+```text
+pubkey exacte
+slot minimum
+slot maximum
+direction ascending / descending
+```
+
+La table ne transporte pas les bytes Account. Elle expose seulement les metadata utiles : pubkey, slot, state hash, owner, lamports, executable, rent epoch et longueur de data.
+
+Le détail recharge exactement l’identité `(pubkey, slot, state_hash)` puis affiche un preview hexadécimal de data limité à 512 bytes, la longueur exacte et l’indicateur de troncature.
+
+## 5. Observations
+
+Les modals Transaction et Account contiennent une table **Observations** associée à l’entité actuellement ouverte.
+
+La table est server-side et expose uniquement de la provenance sûre : provider logique, protocole, méthode/origine d’acquisition, timestamps, endpoint/session/filter/commitment lorsqu’ils existent, hash/taille de source et metadata Account optionnelles admises.
+
+Les bytes du payload source ne traversent jamais IPC.
+
+## 6. Pagination DataTables
+
+Les tables Transactions, Accounts et Observations utilisent DataTables comme unique pager visible.
+
+Tailles disponibles :
+
+```text
+25
+50
+100
+```
+
+Le frontend mappe `start` vers l’offset Store et `length` vers la limite. Les counts exacts restent des chaînes décimales jusqu’à vérification du domaine `Number.MAX_SAFE_INTEGER`.
+
+La pagination d’inspection est distincte de la pagination cursor/keyset utilisée par les consumers machine du Store. Store Desk n’accepte ni cursor, ni search globale DataTables, ni tri arbitraire de colonnes.
+
+## 7. Rafraîchissement et filtres
+
+**Refresh** redessine la table concernée avec ses filtres Store explicites. Un changement de filtre repart de la première page.
+
+Les valeurs de filtre sont validées côté Rust : slots décimaux, pubkey canonique et direction autorisée. Elles ne sont pas injectées dans les logs frontend.
+
+## 8. Valeurs longues et copie
+
+Les valeurs longues sont affichées sous forme tronquée au centre. Le survol permet de consulter la valeur complète et le bouton de copie copie la valeur actuellement affichée par le frontend.
+
+Les événements de tracing de copie transportent uniquement un `fieldId` logique. Ils ne contiennent jamais signature, pubkey, owner, hash ou preview hex.
+
+## 9. Read-only et frontières
+
+Store Desk est un outil d’inspection. Il ne fournit aucune commande pour :
+
+```text
+écrire une entité RAW
+ajouter une observation
+archiver
+purger
+force-rehydrate
+démarrer un backfill
+démarrer un worker
+modifier la configuration Store
+```
+
+Ces responsabilités appartiennent aux composants KSP propriétaires.
+
+Le frontend ne reçoit jamais :
+
+```text
+URI Store
+credentials/secrets
+SQL
+handles backend/pool
+payload RAW complet
+data Account complète
+source payload bytes
+contexte d’erreur arbitraire
+```
+
+## 10. Fermeture
+
+La fermeture de la fenêtre principale bloque les nouvelles admissions puis ferme le Store de manière bornée avant de terminer le process.
+
+Le shutdown applicatif n’effectue aucune mutation métier de rétention ou de données.
+
+## 11. Build production
+
+Depuis la racine du workspace :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri build)
+```
+
+Le build frontend passe par TypeScript puis Vite avant le build Tauri. Les resources Config enregistrées sont packagées selon le contrat commun des applications Desk KSP.