v0.2.12-pre.010

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

@@ -0,0 +1,149 @@
+<!-- file: crates/ksp-app-solprices-desk/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de `ksp-app-solprices-desk`
+
+## 1. Lancement de développement
+
+Depuis la racine du workspace :
+
+```bash
+(cd crates/ksp-app-solprices-desk && cargo tauri dev)
+```
+
+Le launcher debug normalise son current working directory vers la racine du workspace avant le bootstrap Config.
+
+Les ports réservés sont :
+
+```text
+Vite HTTP : 1434
+Vite WS   : 1435
+```
+
+## 2. Profil de prix
+
+Le composite `cfg.composite.ksp-app-solprices-desk` utilise `public_keyless` par défaut.
+
+Profils committed :
+
+```text
+public_keyless   providers utilisables sans secret
+all_free         modes gratuits avec credentials Config lorsqu'ils sont requis
+tests            composition de test
+```
+
+La sélection d'un autre profil appartient aux mécanismes Config ; l'interface ne demande jamais directement une API key et ne choisit pas d'endpoint provider.
+
+## 3. Vue Prices
+
+La vue `Prices` présente une row par provider du registry Off-chain.
+
+Les informations principales sont :
+
+- paire SOL/USD ;
+- sémantique de prix ;
+- mode d'authentification ;
+- availability ;
+- prix exact lorsqu'une observation existe ;
+- timestamp provider lorsqu'il est réellement fourni ;
+- timestamp de réception KSP ;
+- prochaine deadline `retry_at` lorsqu'elle existe.
+
+`Not supplied` signifie qu'un provider n'a pas fourni de timestamp exploitable. Cette absence n'est jamais remplacée artificiellement par le timestamp KSP.
+
+## 4. Refresh individuel
+
+Le bouton `Refresh` d'une row déclenche uniquement le provider correspondant via `MarketPriceService::refresh`.
+
+Pendant l'appel, la row passe temporairement à `Refreshing`. Le Desk ne garde aucun mutex de présentation pendant l'I/O réseau.
+
+Si le service ne produit pas de nouvelle observation, la dernière observation réussie peut rester visible tandis que l'availability/retry est actualisée.
+
+## 5. Refresh sélectionné
+
+Cocher une ou plusieurs rows puis utiliser :
+
+```text
+Refresh selected
+```
+
+La sélection est reconstruite dans l'ordre courant du registry. Les doublons, IDs inconnus, conflits `in_flight`, batch vide et batch supérieur à 64 IDs sont rejetés côté Rust avant dispatch partiel.
+
+Les contrôles :
+
+```text
+Select all providers
+Clear selection
+```
+
+ne déclenchent aucun accès réseau par eux-mêmes.
+
+## 6. Refresh global
+
+```text
+Refresh all
+```
+
+appelle la surface générique `MarketPriceService::refresh_all` et conserve l'ordre déterministe du service.
+
+Les providers disabled, en cooldown ou temporairement indisponibles restent classifiés par Off-chain Transport. Le frontend ne contourne jamais ces règles et n'implémente aucun retry local.
+
+## 7. Lecture des états
+
+Les états visibles sont provider-neutral, notamment :
+
+```text
+Ready
+Cooling down
+Authentication unavailable
+Disabled
+Misconfigured
+Quota unavailable
+Temporarily unavailable
+Refreshing
+```
+
+Le résumé en haut de la vue indique les nombres de providers, rows ready, observations disponibles, états nécessitant attention et refresh en cours.
+
+Aucune moyenne ou fusion de prix n'est calculée dans SOL Prices Desk.
+
+## 8. Diagnostics et sécurité
+
+La vue `Diagnostics` expose uniquement les informations sûres de composition/runtime.
+
+Le frontend :
+
+- ne fait aucun `fetch`/XHR provider ;
+- ne possède aucun endpoint ou header provider ;
+- ne stocke aucun secret dans `localStorage`/`sessionStorage` ;
+- n'utilise aucun scheduler ou polling prix ;
+- ne journalise aucun prix ou payload provider brut.
+
+Les actions utilisateur sont instrumentées via le bridge Logging KSP.
+
+## 9. Runtime packagé
+
+En build release, les documents Config et schemas enregistrés sont embarqués comme resources Tauri. `ksp-config-lib` prépare ensuite la racine KSP user-writable commune ; les Config utilisateur existantes sont conservées, les schemas sont resynchronisés et `.env` n'est jamais embarqué.
+
+La version de bundle est dérivée de Cargo. `package.json` reste un manifeste frontend privé.
+
+## 10. Validation de publication
+
+Avant le build :
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.12
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-app-solprices-desk
+cargo test --workspace
+cargo test -p ksp-app-solprices-desk --test market_price_composition_live_smoke -- --ignored --nocapture
+```
+
+Le build production est :
+
+```bash
+(cd crates/ksp-app-solprices-desk && cargo tauri build)
+```