0.0.1-alpha.3.fix.1

docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md

@@ -0,0 +1,119 @@
+<!-- file: docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md -->
+<!-- version: 1 -->
+
+# Étude Actix/Maud/Vite — corpus `actix-auth-app`
+
+## Objet
+
+Cette étude extrait uniquement le pattern d’intégration frontend/backend observé dans l’archive historique inachevée :
+
+```text
+actix-auth-app-master.zip
+SHA-256 bcdf4c568c827b77c70ee476218c2b07ea0fca408ab87d2f044333309d19ab71
+```
+
+Le corpus n’est pas une baseline autoritaire et son code n’est pas copié tel quel. L’objectif est de cadrer la future composition Knowledge entre :
+
+- templates statiques et assets validés par le profil Web PGR ;
+- rendu SSR Maud ;
+- serveur Actix Web ;
+- assets Vite hashés en production.
+
+## Pattern effectivement observé
+
+### Build Vite
+
+Le fichier `frontend/vite.config.ts` observé :
+
+- utilise `frontend/` comme root ;
+- configure un dev server sur le port `5173` ;
+- utilise une base de production `/res` ;
+- produit dans `../public/res` ;
+- active `build.manifest = true` ;
+- déclare des entrées TypeScript et Sass explicites ;
+- produit des noms JS/CSS hashés ;
+- copie plusieurs familles d’assets statiques avec `vite-plugin-static-copy` ;
+- utilise `sass-embedded`.
+
+Ces choix prouvent qu’un build Vite peut servir de pipeline d’assets pour un backend SSR. Ils ne rendent ni `/res`, ni le port `5173`, ni cette arborescence normatifs pour Knowledge.
+
+### Loader Rust
+
+Le module `src/app/vite.rs` observé charge `.vite/manifest.json` en release et expose un `Loader::entry_url(entry_key, fallback)`. Une entrée stable du type `ts/main.ts` ou `sass/main.scss` est ainsi convertie vers un fichier hashé du build.
+
+Le loader existe aussi en debug, mais son manifest reste absent et `entry_url` renvoie alors un fallback. Les handlers choisissent de leur côté des URLs directes du dev server Vite en debug et la résolution par manifest en release.
+
+### Composition Maud
+
+Les handlers Actix construisent le markup avec Maud puis injectent les URLs CSS/JS selon le mode :
+
+```text
+dev     -> URL d’entrée Vite directe
+release -> entrée stable -> manifest Vite -> URL d’asset hashé
+```
+
+Le pattern démontre que Vite et Maud ne sont pas concurrents : Vite possède la chaîne d’assets/client, tandis que Maud possède le markup runtime.
+
+## Éléments à reprendre conceptuellement
+
+Knowledge retient pour ses futures tranches Web/serveur :
+
+1. un frontend validable indépendamment des serveurs Rust ;
+2. des templates statiques de référence pour travailler le markup et les assets ;
+3. TypeScript, Sass et Bootstrap consommés par la chaîne Vite sélectionnée ;
+4. un build de production avec manifest ;
+5. des clés d’entrée stables indépendantes des noms hashés ;
+6. un composant Rust commun capable de résoudre ces clés pour les pages Maud ;
+7. une voie de développement utilisant le dev server Vite lorsqu’elle est utile ;
+8. une gate d’intégration distincte prouvant que le backend résout réellement les sorties du build.
+
+## Éléments à ne pas copier mécaniquement
+
+Le corpus contient plusieurs décisions locales ou incompatibles avec les règles Knowledge :
+
+- `http://localhost:5173` est codé directement dans plusieurs fichiers ;
+- `/res` est traité comme convention locale ;
+- le loader panique en release lorsqu’un manifest est absent/invalide ;
+- l’arborescence et les copies d’assets sont spécifiques à l’application ;
+- `@types/node` et `@types/bootstrap` existent dans le package mais doivent être réévalués selon les usages TypeScript réels ;
+- le package utilise un alias npm `rolldown-vite`, choix qui n’est pas adopté automatiquement par Knowledge ;
+- la présence de plusieurs fallbacks statiques peut masquer une divergence si elle n’est pas testée explicitement.
+
+Knowledge devra donc adapter le pattern avec erreurs récupérables et observables, configuration explicite, tests et dépendances justifiées.
+
+## Contrat retenu pour `0.0.1`
+
+### `alpha.4`
+
+La tranche Web possède :
+
+- choix explicite du package manager et du lockfile ;
+- TypeScript strict et script `typecheck` ;
+- Vite ;
+- Sass ;
+- Bootstrap ;
+- templates statiques de référence ;
+- build de production ;
+- manifest Vite ;
+- preview/smoke navigateur seulement lorsqu’une propriété runtime le justifie.
+
+Elle ne possède pas encore le rendu Maud ni la lecture Rust du manifest.
+
+### `alpha.5`
+
+La tranche de composition serveur possède :
+
+- trois launchers Actix Web minces ;
+- rendu Maud ;
+- intégration avec les assets construits par `alpha.4` ;
+- résolution production par manifest ;
+- configuration de la voie dev Vite si conservée ;
+- tests/smokes ciblés de l’intégration.
+
+La décision de créer ou non un `knowledge-web-lib` commun dépendra du code réellement partagé entre les trois serveurs.
+
+## Source de vérité UI
+
+Les templates statiques sont des artefacts de **référence et validation**, pas une deuxième application à servir en production. Le markup runtime est Maud.
+
+La tranche Web devra définir une méthode proportionnée pour limiter la dérive entre les deux représentations : par exemple contrats de classes/attributs critiques, snapshots ciblés ou smokes navigateur. La méthode exacte reste `DEFER` jusqu’à `alpha.4`; PGR n’impose pas une duplication exhaustive ni un framework de test particulier.