135 lines
6.8 KiB
Markdown
135 lines
6.8 KiB
Markdown
<!-- file: crates/ksp-app-config-desk/README.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# `ksp-app-config-desk`
|
|
|
|
`ksp-app-config-desk` est l'application desktop spécialisée de management et de validation de la configuration KSP.
|
|
|
|
La crate est un package Tauri mixte :
|
|
|
|
```text
|
|
package : ksp-app-config-desk
|
|
lib : ksp_app_config_desk_lib
|
|
bin : ksp-app-config-desk
|
|
```
|
|
|
|
## Responsabilités
|
|
|
|
L'application reste une couche d'interface/composition. Les responsabilités de parsing, validation, profils, environnement, `.env`, secrets et persistence restent dans `ksp-config-lib`; le runtime Logging restera possédé par `ksp-logging-lib`.
|
|
|
|
Le gabarit desktop actif fournit maintenant :
|
|
|
|
- le verrou single-instance ;
|
|
- l'assemblage Tauri centralisé dans `src/tauri.rs` ;
|
|
- les fenêtres `splash` et `main`, orchestrées par `tw_splash.rs` et `tw_main.rs` ;
|
|
- le frontend Vanilla TypeScript + Vite sous `frontend/` ;
|
|
- SCSS, Bootstrap et Font Awesome ;
|
|
- SimpleBar + `resize-observer-polyfill` pour le scrolling du shell ;
|
|
- `tauri-plugin-tracing` côté Rust et `@fltsci/tauri-plugin-tracing` côté frontend ;
|
|
- les ports dédiés `1430` pour Vite HTTP et `1431` pour le WebSocket de développement ;
|
|
- la destination frontend externe commune à Tauri et Vite;
|
|
- le bootstrap Config/Logging réel, un `AppState` durable et le premier contrat Tauri/TS-RS `get_app_snapshot`;
|
|
- le bridge de logging frontend KSP `frontend_log.ts`, routé par `emit_frontend_log` vers des targets statiques whitelistés de `ksp-logging-lib` ;
|
|
- le lifecycle configurable `splash -> main` avec navigation monofenêtre et instrumentation `debug`/`trace` des interactions frontend.
|
|
|
|
## Layout frontend
|
|
|
|
```text
|
|
frontend/
|
|
├── imgs/
|
|
├── sass/
|
|
│ ├── _app.scss
|
|
│ ├── _bootswatch.scss
|
|
│ ├── _fontawesome.scss
|
|
│ ├── _simplebar.scss
|
|
│ ├── _variables.scss
|
|
│ ├── main.scss
|
|
│ └── splash.scss
|
|
├── ts/
|
|
│ ├── frontend_log.ts
|
|
│ ├── invoke.ts
|
|
│ ├── main.ts
|
|
│ └── splash.ts
|
|
├── main.html
|
|
└── splash.html
|
|
```
|
|
|
|
Les premiers bindings TS-RS sont générés par les tests `ts-rs` sous :
|
|
|
|
```text
|
|
frontend/ts/bindings/ksp_app_config_desk/...
|
|
```
|
|
|
|
Les DTO Rust applicatifs restent la source de vérité et les bindings générés ne sont pas versionnés.
|
|
|
|
## Artefacts frontend
|
|
|
|
Les artefacts frontend construits ne sont pas versionnés. `tauri.conf.json` fixe :
|
|
|
|
```text
|
|
../../builds/khadhroony-solana-project/ksp-app-config-desk/dist
|
|
```
|
|
|
|
`vite.config.ts` résout cette même destination depuis la racine de la crate, ce qui maintient `dist` hors du workspace source et l'aligne avec la stratégie `.cargo/config.toml` pour les artefacts Rust.
|
|
|
|
## Ports desktop
|
|
|
|
`ksp-app-config-desk` utilise :
|
|
|
|
```text
|
|
Vite HTTP : 1430
|
|
Vite WS : 1431
|
|
```
|
|
|
|
Le port HTTP est strict. Les futures applications desk utilisent les couples suivants `1432/1433`, `1434/1435`, etc.
|
|
|
|
## Dépendances frontend
|
|
|
|
Les bibliothèques consommées par le bundle applicatif sont déclarées sous `dependencies` : `@fltsci/tauri-plugin-tracing`, `@fortawesome/fontawesome-free`, `@tauri-apps/api`, `bootstrap`, `simplebar` et `resize-observer-polyfill`.
|
|
|
|
Les outils de compilation/développement et déclarations de types appartiennent à `devDependencies`, notamment `@tauri-apps/cli`, `@types/bootstrap`, `@types/node`, `sass-embedded`, `typescript` et `vite`. Les commandes npm directes sont réservées à l'installation ou à la mise à jour de ces dépendances ; le cycle normal de développement et de build est lancé depuis la racine du workspace par Tauri avec la configuration explicite de l'application.
|
|
|
|
|
|
## Logging frontend KSP
|
|
|
|
Le frontend utilise `frontend/ts/frontend_log.ts`. Les helpers `frontendTrace`, `frontendDebug`, `frontendInfo`, `frontendWarn` et `frontendError`, ainsi que le bridge `console.*`, invoquent la commande Tauri `emit_frontend_log`.
|
|
|
|
Le payload ne transporte pas de target tracing libre. Il utilise uniquement les identifiants logiques :
|
|
|
|
```text
|
|
frontend -> ksp-app-config-desk.frontend
|
|
main -> ksp-app-config-desk.frontend.main
|
|
splash -> ksp-app-config-desk.frontend.splash
|
|
```
|
|
|
|
Rust valide le niveau et le `targetId`, choisit un callsite statique puis émet exclusivement via les macros de `ksp-logging-lib`. Le package applicatif n'importe pas directement `tracing`. Le panneau manuel de test Logging, ses targets `test.*` et ses domaines personnalisables restent une surface distincte prévue plus tard.
|
|
|
|
## Bootstrap Config et Logging
|
|
|
|
Au démarrage, l'application construit `ConfigBootstrapOptions`, `ConfigFileRegistry`, `ConfigDocumentEngine` et `ConfigManagement` à partir des arguments complets du processus. Elle tente ensuite de résoudre le profil Logging par défaut avec un snapshot `ConfigEnvironment` frais.
|
|
|
|
Si le document Logging, sa résolution environnementale ou l'initialisation du runtime configuré échoue avant installation du subscriber, Config Desk installe un fallback **transitoire** en mémoire : console stderr, niveau `Info`, aucun fichier, aucun span lifecycle. Ce fallback n'est jamais persisté et son diagnostic frontend est limité à `domain`, `code` et `message`.
|
|
|
|
Le `LoggingGuard` est conservé dans `AppState` pour préparer le hot reload ultérieur.
|
|
|
|
## Lifecycle des fenêtres
|
|
|
|
`tw_splash.rs` valide l'origine de `splash_frontend_ready`, ignore les readiness dupliquées et orchestre le passage à `main`. Les timings sont résolus par `ksp-config-lib` depuis :
|
|
|
|
```text
|
|
KSP_DESK_SPLASH_MINIMUM_MS=1200
|
|
KSP_DESK_SPLASH_FADE_MS=300
|
|
```
|
|
|
|
Après la durée minimale, le splash reçoit son fade-out, `tw_main.rs` affiche/focalise `main`, puis le splash est détruit. Une valeur splash invalide ne bloque pas le manager : des timings de fallback sûrs restent en mémoire afin que la future surface `.env` puisse permettre la réparation.
|
|
|
|
Le shell principal expose les cinq routes de référence `Vue d'ensemble`, `Documents`, `Profils`, `Environnement / .env` et `Logging`. Les routes non encore fonctionnelles affichent un placeholder sans réimplémenter les services prévus par les prereleases suivantes.
|
|
|
|
## Traçabilité frontend
|
|
|
|
Les actions utilisateur significatives et changements d'état sont journalisés en `debug`; les opérations plus fines (rendu/remplacement DOM, étapes IPC, animations et événements fréquents) en `trace`. Le wrapper `invoke.ts` trace début/fin des commandes sans journaliser leurs arguments, afin de ne pas créer ultérieurement de fuite de valeurs sensibles.
|
|
|
|
## Police du splash
|
|
|
|
Le splash utilise `DOS_Amazigh.ttf` (`font-family: Dos Amazigh`) pour son titre, via le `@font-face` déclaré dans `frontend/sass/splash.scss`. Le répertoire `frontend/fonts/` documente la provenance et l'empreinte de l'asset de référence. Le lifecycle du splash est désormais actif et utilise cette police pendant la transition vers la fenêtre principale.
|