139 lines
6.8 KiB
Markdown
139 lines
6.8 KiB
Markdown
<!-- file: crates/ksp-app-config-desk/USAGE.md -->
|
|
<!-- version: 8 -->
|
|
|
|
# Utilisation de `ksp-app-config-desk`
|
|
|
|
## État actuel
|
|
|
|
Le gabarit Rust/Tauri et le frontend Vite/TypeScript/SCSS sont présents. Le backend initialise désormais Config, le runtime Logging et `AppState`; les panneaux métier Config restent volontairement absents à ce stade.
|
|
|
|
La fenêtre `splash` est visible au démarrage. Après readiness du frontend et temporisation résolue par Config, l'application effectue le fade-out, affiche/focalise `main` puis détruit `splash`. La fenêtre principale expose immédiatement la navigation monofenêtre de référence.
|
|
|
|
## Première installation des dépendances frontend
|
|
|
|
Depuis :
|
|
|
|
```text
|
|
crates/ksp-app-config-desk
|
|
```
|
|
|
|
installer les dépendances déclarées avec la commande de gestion prévue par le projet :
|
|
|
|
```bash
|
|
npm i -D
|
|
cd ../../
|
|
```
|
|
|
|
`npm i -D` sans nom de package installe les dépendances déclarées du package ; la classification `dependencies` / `devDependencies` reste celle de `package.json`. Les lockfiles frontend restent ignorés et ne sont pas versionnés. Après cette installation, les commandes Cargo/Tauri sont exécutées depuis la racine du workspace.
|
|
|
|
## Développement normal
|
|
|
|
Le frontend n'est pas lancé directement avec npm. KSP est un workspace Rust multi-app : depuis la racine du workspace, la configuration Tauri de l'application doit être sélectionnée explicitement :
|
|
|
|
```bash
|
|
cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json
|
|
```
|
|
|
|
Tauri exécute alors le hook :
|
|
|
|
```text
|
|
npm run dev
|
|
```
|
|
|
|
Vite écoute strictement sur :
|
|
|
|
```text
|
|
HTTP : 1430
|
|
WS : 1431
|
|
```
|
|
|
|
Si le port HTTP est déjà occupé, le démarrage doit échouer au lieu de sélectionner silencieusement un autre port.
|
|
|
|
## Build frontend
|
|
|
|
Le build de l'application passe également par Tauri. Depuis la racine du workspace :
|
|
|
|
```bash
|
|
cargo tauri build -c crates/ksp-app-config-desk/tauri.conf.json
|
|
```
|
|
|
|
`beforeBuildCommand` déclenche :
|
|
|
|
```text
|
|
npm run build
|
|
```
|
|
|
|
Vite construit les pages `main.html` et `splash.html` vers :
|
|
|
|
```text
|
|
../../builds/khadhroony-solana-project/ksp-app-config-desk/dist
|
|
```
|
|
|
|
Cette destination est résolue depuis la racine de la crate dans `vite.config.ts` et correspond au `frontendDist` de `tauri.conf.json`.
|
|
|
|
## Tracing desktop
|
|
|
|
`tauri-plugin-tracing` est enregistré côté Rust et la capability contient `tracing:default`. Le package frontend associé reste disponible comme adaptateur Tauri, sans installer de subscriber concurrent.
|
|
|
|
Les logs techniques du frontend passent maintenant par `frontend/ts/frontend_log.ts` puis la commande Tauri `emit_frontend_log`. Les identifiants de target autorisés sont :
|
|
|
|
```text
|
|
frontend
|
|
main
|
|
splash
|
|
```
|
|
|
|
Ils sont convertis côté Rust vers des targets KSP statiques `ksp-app-config-desk.frontend*` et émis uniquement via `ksp-logging-lib`. Un niveau différent de `trace`, `debug`, `info`, `warn` ou `error`, ou un `targetId` non whitelisté, est rejeté avec un `CommandErrorDto` sûr.
|
|
|
|
`main.ts` et `splash.ts` installent aussi le bridge `console.*`; l'échec éventuel d'un `invoke` est écrit uniquement sur la console WebView originale afin d'éviter une boucle de logging. Ce bridge conserve donc les messages JavaScript dans la console WebKit et les transmet vers Rust, mais il ne reflète pas encore les événements Rust généraux dans cette console. `attachConsole()` du package officiel nécessite que le subscriber Rust publie vers une `WebviewLayer`; cette couche devra être raccordée plus tard à l'ownership de `ksp-logging-lib` plutôt que d'installer un subscriber Tauri parallèle.
|
|
|
|
## Bindings TS-RS
|
|
|
|
Le layout cible est :
|
|
|
|
```text
|
|
frontend/ts/bindings/ksp_app_config_desk/...
|
|
```
|
|
|
|
Les bindings sont générés au premier DTO Tauri réel ; aucune structure factice n'est ajoutée uniquement pour créer le répertoire.
|
|
|
|
|
|
## Bootstrap backend
|
|
|
|
Les arguments `--cfgpath`, `--schemapath` et `--filemap=...` sont transmis tels quels à `ksp-config-lib`. En build debug, le launcher replace le current working directory Rust à la racine du workspace avant ce bootstrap afin que les defaults relatifs `config/`, `config/schemas/` et `.env` désignent les ressources racine même lorsque Tauri lance `cargo run` depuis la crate de l'application. Le launcher ne lit pas ces ressources lui-même. Le profil Logging initial est le `default_profile` de `std.logging.json`.
|
|
|
|
Si cette configuration ne peut pas être utilisée, l'application doit rester démarrable pour permettre sa réparation : elle utilise alors un fallback Logging console/stderr en mémoire. Le fallback n'écrit aucun fichier de configuration et n'écrase aucune valeur utilisateur.
|
|
|
|
La commande Tauri `get_app_snapshot` expose un état sûr du bootstrap. Ses types TypeScript sont générés par `cargo test -p ksp-app-config-desk` sous `frontend/ts/bindings/`.
|
|
|
|
## Lifecycle et timings du splash
|
|
|
|
Les variables communes sont :
|
|
|
|
```text
|
|
KSP_DESK_SPLASH_MINIMUM_MS=1200
|
|
KSP_DESK_SPLASH_FADE_MS=300
|
|
```
|
|
|
|
La priorité est celle de Config : process > `.env` > fallback. Les valeurs sont lues uniquement via `ksp-config-lib`. Une valeur non numérique ou hors borne déclenche un fallback runtime en mémoire plutôt qu'un refus de démarrer Config Desk.
|
|
|
|
Le frontend `splash.ts` installe son listener puis appelle `splash_frontend_ready`. Le backend vérifie que l'appel provient réellement de la WebView `splash`; une readiness dupliquée (par exemple après reload Vite) est ignorée. La durée minimale commence à cette readiness : Rust émet le fade-in, attend `minimum`, émet le fade-out, attend `fade`, puis active `main`. Ainsi `KSP_DESK_SPLASH_MINIMUM_MS=12000` et `KSP_DESK_SPLASH_FADE_MS=3000` donnent environ `15000 ms` de lifecycle backend. Des logs `debug` indiquent source des deux valeurs, attentes configurées/réelles et durée totale afin de vérifier ce contrat.
|
|
|
|
## Navigation principale
|
|
|
|
La barre principale contient :
|
|
|
|
```text
|
|
Vue d'ensemble
|
|
Documents
|
|
Profils
|
|
Environnement / .env
|
|
Logging
|
|
```
|
|
|
|
Seule la vue d'ensemble consomme déjà `get_app_snapshot`; les autres routes restent des placeholders jusqu'à leurs tranches fonctionnelles. Le header affiche `Config Desk — <vue active>` : le logo fournit déjà l'identité KSP. Les commandes principales peu nombreuses utilisent des pills/tabs alignées à droite ; une application plus chargée devra préférer un dropdown. Chaque clic de tab est tracé en `trace`, l'activation utilisateur significative reste tracée en `debug`, et chaque remplacement/rendu de section en `trace`. Les appels Tauri partagés utilisent `frontend/ts/invoke.ts`, qui journalise le début et la fin d'une commande sans journaliser ses arguments.
|
|
|
|
## Asset font du splash
|
|
|
|
La police bot3 de référence est `DOS_Amazigh.ttf`. Vérifier l'asset local contre l'empreinte documentée dans `frontend/fonts/README.md` ; `frontend/sass/splash.scss` l'applique au titre du splash.
|