150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
<!-- 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)
|
|
```
|