Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.12-pre.010

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-27 19:11:07 +02:00
parent ca6af3d904
commit 4f71dbc62d
14 changed files with 457 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
crates/ksp-app-solprices-desk/README.md
View File

@@ -1,11 +1,11 @@
<!-- file: crates/ksp-app-solprices-desk/README.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# `ksp-app-solprices-desk`
`ksp-app-solprices-desk` est le Desk Tauri spécialisé destiné à visualiser les prix SOL/USD fournis par `ksp-offchain-transport-lib` sans exposer les détails propres aux providers au frontend.
`ksp-app-solprices-desk` est l'application desktop spécialisée de visualisation et de refresh manuel des prix SOL/USD fournis par `ksp-offchain-transport-lib`.
`0.2.12-pre.002` crée uniquement le **scaffold desktop**. La composition Off-chain, les DTO prix, la table provider-neutral et les commandes de refresh appartiennent aux tranches suivantes.
L'application reste une **HID provider-neutral** : elle consomme le registry, les observations, les disponibilités et les opérations génériques du service Off-chain sans connaître les endpoints, credentials, limites ou wire formats propres aux providers.
## Package
@@ -15,30 +15,93 @@ lib : ksp_app_solprices_desk_lib
bin : ksp-app-solprices-desk
```
Le binaire reste un launcher mince. La bibliothèque applicative possède l'assemblage Tauri, l'état de bootstrap, le bridge Logging et le lifecycle des fenêtres.
Le binaire reste un launcher mince. La bibliothèque applicative possède l'assemblage Tauri, le bootstrap Config/Logging/Off-chain, l'état de présentation en mémoire et les commands Tauri.
## Surface du scaffold
## Responsabilités
```text
splash
-> Config standard + Logging
-> main
-> Prices placeholder non fonctionnel en pre.002
-> Diagnostics identité/runtime Logging sûre
ksp-config-lib -> composite, profils, secrets et runtime packagé
ksp-offchain-transport-lib -> providers, HTTP, registry, availability, limits et refresh
ksp-logging-lib -> logging/tracing applicatif
ksp-app-solprices-desk -> orchestration Tauri + projections provider-neutral sûres
```
Le scaffold ne possède encore aucun `MarketPriceService`, aucun fetch prix, aucun provider, aucun endpoint, aucun credential et aucun scheduler.
Le Desk ne possède aucun client HTTP provider et ne réimplémente ni admission, ni cooldown, ni retry provider.
## Vues
### Prices
La vue `Prices` affiche l'inventaire SOL/USD dans l'ordre stable du registry et conserve chaque observation séparée.
La projection comprend notamment :
- identité/display provider et paire ;
- sémantique et mode d'authentification ;
- availability générique ;
- prix exact sous forme de `String` ;
- timestamp provider lorsqu'il existe ;
- timestamp de réception KSP ;
- `retry_at` lorsqu'il existe ;
- état `Refreshing` local à la présentation.
Aucune moyenne, aucun fallback automatique et aucun prix canonique ne sont produits par cette application.
Les actions manuelles sont :
```text
Refresh
Refresh selected
Refresh all
Select all providers
Clear selection
```
Le batch applicatif est borné à `1..=64` IDs opaques avant parsing/dispatch. Les doublons, IDs inconnus et conflits `in_flight` sont rejetés avant mutation partielle.
### Diagnostics
La vue `Diagnostics` expose uniquement des informations de runtime sûres : identité/version applicative, profils résolus et compte de providers. Aucun endpoint, header, API key, payload provider ou prix n'est journalisé comme diagnostic brut.
## Config et profils
Le composite dédié est :
```text
cfg.composite.ksp-app-solprices-desk
```
Il compose :
```text
logging
Off-chain Transport
```
Profils committed :
```text
public_keyless profil par défaut
all_free modes gratuits incluant les credentials Config requis
tests profil déterministe de composition
```
Le frontend ne sélectionne ni provider concret ni secret. La résolution des credentials reste entièrement possédée par Config.
## Frontières desktop
Le frontend utilise uniquement les capabilities :
Le frontend utilise uniquement :
```text
core:default
tracing:default
```
Aucun plugin dialog, filesystem, HTTP ou shell n'est accordé au WebView. Le bridge frontend Logging passe par des commandes Rust centralisées dans `tauri.rs`.
Il ne possède aucun accès direct filesystem, HTTP, shell ou persistence navigateur. Les refresh passent uniquement par les commands Rust centralisées dans `tauri.rs`.
Il n'existe aucun polling, auto-refresh ou scheduler prix dans le Desk. Les deadlines/cooldowns affichés proviennent de `ksp-offchain-transport-lib`.
## Ports et build
Les ports réservés sont :
@@ -47,32 +110,45 @@ Vite HTTP : 1434
Vite WS : 1435
```
Le port Vite est strict et le frontend build est isolé sous :
Le frontend build est isolé sous :
```text
builds/khadhroony-solana-project/ksp-app-solprices-desk/dist
```
## Config et packaging
La version du binaire et des bundles Tauri provient de la version Cargo résolue. `tauri.conf.json` ne duplique pas cette version ; `package.json` reste un manifeste frontend privé non autoritatif pour la release KSP.
Pendant `pre.002`, le Desk utilise le document Logging standard pour établir le gabarit commun. Le composite dédié `cfg.composite.ksp-app-solprices-desk` n'existe pas encore et reste réservé à `pre.003`.
## Runtime packagé
Le bundle embarque les dix ressources correspondant au registry Config courant. `pre.003` ajoutera atomiquement le onzième document composite et synchronisera les resources des Desks concernés.
Les onze resources Config/Schemas enregistrées sont embarquées dans le bundle. Au démarrage release, `ksp-config-lib` prépare la racine KSP user-writable commune, seed les documents absents, resynchronise les schemas et ne bundle jamais `.env`.
## Développement
Le cycle Tauri est crate-local :
## Développement et validation
```bash
(cd crates/ksp-app-solprices-desk && cargo tauri dev)
```
`-c/--config` n'est pas utilisé comme sélecteur d'application. En développement, le launcher normalise le current working directory vers la racine du workspace avant le bootstrap Config.
Gate Rust courant :
Le build production final sera exécuté dans le couloir de validation de la release :
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-app-solprices-desk
cargo test --workspace
```
Smoke live de composition opt-in :
```bash
cargo test -p ksp-app-solprices-desk --test market_price_composition_live_smoke -- --ignored --nocapture
```
Build production :
```bash
(cd crates/ksp-app-solprices-desk && cargo tauri build)
```
`USAGE.md` sera finalisé lorsque l'application sera fonctionnellement complète, conformément au workflow de clôture des applications KSP.
Voir également [`USAGE.md`](USAGE.md), [`../ksp-offchain-transport-lib/README.md`](../ksp-offchain-transport-lib/README.md) et [`../../docs/validation/015-V0_2_12_SOL_PRICES_DESK.md`](../../docs/validation/015-V0_2_12_SOL_PRICES_DESK.md).

149
crates/ksp-app-solprices-desk/USAGE.md Normal file
View File

@@ -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)
```