Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.1-alpha.3.fix.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 23:00:24 +02:00
parent 6b6bdcfc71
commit fd3d363bff
17 changed files with 625 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Documentation SaseDev Knowledge
@@ -15,6 +15,7 @@
## Études
- [`studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](studies/001-AUTH_ADMIN_CORPUS_STUDY.md) — analyse des fonctionnalités auth/admin présentes ou seulement préparées dans deux archives historiques inachevées.
- [`studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — analyse du pattern Vite manifest / Actix / Maud de `actix-auth-app` et contrat de reprise ciblée pour Knowledge.
## Plans

12
docs/architecture/001-PROJECT_PROFILE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Profil du projet Knowledge
@@ -74,10 +74,12 @@ Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont p
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine(s) frontend | `DEFER` | décider dans la tranche Web selon le partage réel entre les trois applications |
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview des templates et assets de référence ; manifest de production consommé par l’intégration Maud |
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source de la chaîne de validation Web et des assets réellement servis par les pages Maud |
| Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle |
| Racine(s) frontend | `DEFER` | décider en `alpha.4` selon le partage réel entre les trois applications et leurs templates de référence |
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud |
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | mapping d’assets hashés requis en production ; API Rust exacte différée jusqu’à la composition serveur |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |

30
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Architecture de fondation Knowledge
@@ -238,6 +238,34 @@ Actix Web et Maud sont des choix de composition/rendu locaux. Vite gère les ass
La stratégie exacte de partage des assets/frontend entre les trois applications reste `DEFER` jusqu'à la tranche Web : un package commun n'est créé que si du code/assets sont réellement communs.
### Pipeline Web de référence et rendu runtime
Le frontend Web n’est pas une SPA concurrente du SSR Maud. Il possède deux responsabilités distinctes :
```text
Vite + TypeScript + Sass + Bootstrap
-> assets construits et templates statiques de référence
-> typecheck/build/preview/smoke indépendants du backend
Actix Web + Maud
-> markup runtime des trois applications
-> consommation des mêmes contrats d’assets
```
Les templates statiques de référence permettent de travailler rapidement sur le HTML, le responsive, les classes Bootstrap, les comportements TypeScript et les styles Sass sans démarrer les serveurs Rust. Ils sont ensuite adaptés en composants/templates Maud pour le rendu runtime. Cette adaptation ne doit pas créer deux produits UI indépendants : la tranche Web devra définir les invariants vérifiables qui empêchent la dérive entre référence statique et rendu Maud.
Le build production Vite doit exposer un manifest permettant au backend de convertir une clé d’entrée stable en URL d’asset hashé. Le corpus `actix-auth-app` montre un pattern utile : manifest Vite activé, entrées TypeScript/Sass explicites, loader Rust et sélection dev-server versus manifest en fonction du mode. Knowledge retient le **contrat d’intégration**, pas l’implémentation historique telle quelle.
En particulier, Knowledge ne doit pas hériter mécaniquement :
- d’un origin Vite `localhost:5173` codé en dur ;
- d’un préfixe `/res` universel ;
- d’un `panic!` lorsque le manifest est absent ou invalide ;
- d’une arborescence d’assets spécifique au corpus ;
- de dépendances TypeScript `@types/*` non justifiées par les packages réellement consommés.
`alpha.4` possède le frontend indépendant et la production du manifest. `alpha.5` possède l’intégration Actix/Maud et doit décider si le loader d’assets devient une crate/lib partagée entre les trois serveurs.
## 10. Administration
L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité.

26
docs/plans/001-V0_0_1_FOUNDATION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/001-V0_0_1_FOUNDATION_PLAN.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Plan 0.0.1 — fondation SaseDev Knowledge
@@ -126,7 +126,13 @@ Le skeleton `002-RUST_CARGO_WORKSPACE` est matérialisé avec `knowledge-domain-
### alpha.3 — contrats domaine/Git/synchronisation
Introduire uniquement les premiers contrats/types nécessaires aux frontières `GitRepository`, source/famille de contenu et synchronisation, avec tests ciblés. Le modèle doit supporter au moins les trois sources initiales sans coder une limite à trois.
Statut opérateur initial : **FAIL**.
La gate valide la structure et les audits puis échoue dans `knowledge-domain-lib` : `SourceId::new` tente de construire le tuple struct privé via le re-export crate-root depuis son sous-module. Le même défaut bloque `cargo check`, Clippy et les trois suites ciblées.
`alpha.3.fix.1` corrige ce défaut Rust, ajoute une régression directe de construction `SourceId` et précise la trajectoire Web/Maud fournie avant clôture de la tranche ; il ne démarre aucune implémentation frontend ou serveur.
Le scope fonctionnel de `alpha.3` reste : introduire uniquement les premiers contrats/types nécessaires aux frontières `GitRepository`, source/famille de contenu et synchronisation, avec tests ciblés. Le modèle doit supporter au moins les trois sources initiales sans coder une limite à trois.
Matérialiser `knowledge-git-api` et `knowledge-sync-api` parce que ces frontières ont des implémentations réellement remplaçables/multiples. Garder ces crates passives ; ne pas créer `knowledge-git-lib`, worker, Gitea ou persistence par anticipation.
@@ -134,15 +140,19 @@ Adopter les audits Rust PGR de structure/façade désormais utiles avec les prem
Ne pas ajouter d'API Gitea ni de persistance PostgreSQL par anticipation.
### alpha.4 — baseline Web indépendante
### alpha.4 — baseline Web indépendante et templates de référence
Instancier le skeleton `003-WEB_FRONTEND` : choisir package manager et lockfile, TypeScript strict, Vite, Sass et Bootstrap réellement nécessaires, avec typecheck/build indépendants du backend.
Instancier obligatoirement le skeleton `003-WEB_FRONTEND` : choisir package manager et lockfile, TypeScript strict, Vite, Sass et Bootstrap, avec typecheck/build indépendants du backend.
Décider à cette tranche si les trois applications partagent un package d'assets/frontend ou possèdent des entrées séparées. Ne pas dupliquer par défaut, ne pas imposer non plus un frontend unique sans preuve de réutilisation.
Le frontend sert d’abord de laboratoire de templates statiques : développer et valider indépendamment le markup de référence, les comportements TypeScript, le responsive Bootstrap et les styles Sass avant adaptation du markup runtime en Maud. Les pages statiques ne deviennent pas une seconde UI de production.
### alpha.5 — composition des trois serveurs minimale
Activer le manifest de build Vite et définir des clés d’entrée stables pour les assets réellement destinés aux pages Maud. Les outputs restent générés/hors Git conformément à PGR.
Matérialiser le minimum Actix Web/Maud nécessaire pour prouver trois launchers minces :
Décider à cette tranche si les trois applications partagent un package d'assets/frontend ou possèdent des entrées séparées. Ne pas dupliquer par défaut, ne pas imposer non plus un frontend unique sans preuve de réutilisation. Définir également une preuve minimale contre la dérive entre templates statiques de référence et future adaptation Maud.
### alpha.5 — composition Actix/Maud et manifest Vite
Matérialiser le minimum Actix Web/Maud nécessaire pour prouver trois launchers minces et intégrer les assets produits par `alpha.4` :
```text
knowledge-pgr-server
@@ -152,6 +162,8 @@ knowledge-snippets-server
Ils doivent composer les mêmes contrats/bibliothèques lorsque la responsabilité est partagée et rester capables de recevoir des configurations de sources Git distinctes.
Le HTML runtime est rendu avec Maud. En développement, la composition MAY cibler le dev server Vite configuré ; en production, elle MUST résoudre les assets hashés via le manifest Vite ou un mapping équivalent produit par la chaîne Web. Le pattern de `actix-auth-app` est à adapter sous les règles Knowledge, notamment sans `panic!` et sans origin/port codé en dur.
La tranche ne doit pas introduire admin complète, auth complète, persistance métier complète ni forge obligatoire.
### beta.1 — réconciliation de fondation

119
docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md Normal file
View File

@@ -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.

20
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Matrice de validation Knowledge
@@ -89,7 +89,9 @@ STYLES preuve séparée uniquement si le build ne prouve pas déjà la compilati
SMOKE navigateur seulement lorsqu'une propriété runtime le justifie
```
La gate frontend reste exécutable indépendamment du backend autant que la topologie réelle le permet.
La gate frontend reste exécutable indépendamment du backend autant que la topologie réelle le permet. Les templates statiques de référence appartiennent à cette gate : leur rôle est de prouver le design/markup/assets côté Web avant adaptation Maud, pas de prouver le rendu Actix.
Lorsque Vite est sélectionné pour les assets réellement servis par Maud, la gate de production doit également prouver l’émission d’un manifest parsable et la présence des clés d’entrée attendues. Une gate d’intégration Actix/Maud distincte prouve ensuite que ces clés sont résolues sans coder les noms hashés.
Si plusieurs entrées/frontend existent pour PGR, HOWTOs et snippets, la gate doit couvrir chacune des entrées modifiées sans forcer trois builds identiques lorsqu'un package commun possède réellement les assets partagés.
@@ -180,3 +182,17 @@ La tranche doit prouver :
- hygiène Git et headers documentaires/code applicables.
L'audit `audit_rust_const_blocks.py` n'appartient pas à la gate globale de cette tranche.
## Gate de `0.0.1-alpha.3.fix.1`
Le fix doit prouver :
- `VERSION = 0.0.1-alpha.3.fix.1` et version workspace identique ;
- history `alpha.3` `FAIL` committé avant application du fix ;
- construction valide de `SourceId` depuis son module sans contourner la visibilité du tuple struct ;
- test de régression direct `SourceId::new("pgr")` + tests précédents ;
- audits Rust PGR sélectionnés propres ;
- `cargo check`, Clippy strict et les trois suites ciblées `PASS` ;
- aucune dépendance ou crate fonctionnelle Web/Actix/PostgreSQL/Gitea ajoutée ;
- trajectoire Web documentée : skeleton Web PGR obligatoire en `alpha.4`, templates statiques de référence, rendu runtime Maud, manifest Vite produit côté frontend et intégration Actix/Maud seulement en `alpha.5` ;
- hygiène Git et documentation propres.