139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
<!-- file: crates/ksp-app-config-desk/USAGE.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# 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.
|
|
|
|
## 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`. 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.
|
|
|
|
## 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. Chaque clic de navigation est tracé 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.
|