93 lines
9.9 KiB
Markdown
93 lines
9.9 KiB
Markdown
<!-- file: README.md -->
|
|
<!-- version: 21 -->
|
|
|
|
# SaseDev Knowledge
|
|
|
|
SaseDev Knowledge est le workspace applicatif destiné à publier et administrer plusieurs familles de connaissance SaseDev sans transformer PGR en encyclopédie technique.
|
|
|
|
Le dépôt applicatif retenu est `sasedev-knowledge`. Le nom court du projet et le préfixe de crates sont `knowledge`.
|
|
|
|
## Statut
|
|
|
|
La version courante est définie par [`VERSION`](VERSION).
|
|
|
|
`0.0.1` est la première stable de fondation de SaseDev Knowledge. `0.0.2` est la stable du chemin Git générique de lecture, de l'autonomie normative locale et du cas d'usage partagé de synchronisation `Changed` / `Unchanged`.
|
|
|
|
`0.0.3-alpha.4` ferme maintenant le chemin Git générique d'écriture : après création locale d'un commit candidat isolé, `knowledge-git-lib` observe l'état réel de la branche distante puis effectue un push compare-and-exchange protégé par `--force-with-lease` contre l'état explicitement attendu. Une branche peut être créée uniquement lorsque son absence est attendue ; toute divergence devient un conflit récupérable avec l'état distant réellement observé et aucun écrasement silencieux. PostgreSQL, forge, workflow complet de proposition, rebase/merge automatique et auth/admin restent hors scope.
|
|
|
|
`knowledge-git-lib` implémente `knowledge-git-api::GitRepository` pour des sources physiques enregistrées : mirror contrôlé, refresh avec pruning, résolution d'une référence vers un commit et snapshot/worktree détaché adressé par révision. La création locale du candidat d'`alpha.3` reste séparée de cette sémantique de lecture. Les règles nécessaires au développement courant sont désormais possédées localement sous `docs/rules/`, et les futurs prompts Knowledge ne chargent pas PGR sauf réévaluation explicitement engagée. `knowledge-app-lib` compose maintenant refresh, résolution, comparaison avec la révision précédente et préparation de snapshot en un résultat explicite `Changed` / `Unchanged`, sans persister la dernière révision ni matérialiser de scheduler.
|
|
|
|
## Topologie produit de fondation
|
|
|
|
Le workspace héberge trois applications Web Actix distinctes, correspondant aux trois façades publiques prévues :
|
|
|
|
```text
|
|
knowledge-pgr-server -> pgr.sasedev.com
|
|
knowledge-howtos-server -> howtos.sasedev.com
|
|
knowledge-snippets-server -> snippets.sasedev.com
|
|
```
|
|
|
|
Ces trois launchers restent minces et réutilisent les mêmes crates communes lorsqu'une responsabilité est réellement partagée. Leur séparation de processus ne transforme pas le domaine en microservices et n'autorise pas la duplication de logique métier.
|
|
|
|
Chaque famille possède au minimum sa propre source Git autoritaire : dépôt `pgr`, dépôt `howtos` et dépôt `snippets`. La configuration doit permettre d'ajouter d'autres sources sans figer le système à exactement trois repositories.
|
|
|
|
PostgreSQL est mutualisable et constitue la baseline retenue pour l'état transversal de la plateforme : comptes, sessions, propositions, synchronisation, index et relations entre familles. Il ne remplace jamais les sources Git comme vérité du contenu publié.
|
|
|
|
Chaque application Web doit pouvoir exposer sa propre surface d'administration protégée pour son domaine. Les chemins HTTP exacts ne sont pas encore figés. Une éventuelle quatrième application d'administration pourra agréger des fonctions transversales, mais elle ne remplacera pas les contrôles d'autorisation propres aux trois serveurs.
|
|
|
|
Le workspace Rust matérialise neuf packages : les trois frontières de fondation `knowledge-domain-lib`, `knowledge-git-api` et `knowledge-sync-api`, le backend `knowledge-git-lib`, la couche application partagée `knowledge-app-lib`, la composition Web `knowledge-web-lib`, puis les trois launchers `knowledge-pgr-server`, `knowledge-howtos-server` et `knowledge-snippets-server`. Les deux crates `-api` restent passives et indépendantes d'Actix, Gitea et PostgreSQL.
|
|
|
|
## Frontend de référence et rendu Maud
|
|
|
|
Knowledge adopte le profil Web PGR comme partie obligatoire de la fondation. La stable `0.0.1` matérialise un package partagé de laboratoire sous `Web/knowledge-template-lab/` avec npm, TypeScript strict, Vite, Sass et Bootstrap.
|
|
|
|
Ce package sert à développer, prévisualiser et valider les assets et templates statiques de référence indépendamment des serveurs Actix. Il n'est pas une quatrième application produit ni une UI de production.
|
|
|
|
Les templates statiques sont un **harness de conception/validation**, pas le moteur de rendu de production. Le markup runtime des trois applications est adapté en Maud par `knowledge-web-lib`. Le build Vite active un manifest et possède une entrée stable `src/main.ts`; `knowledge-web-lib` résout cette entrée vers les assets hashés en production et utilise le dev server configuré en développement. Les URL publiques finales et routes admin/login restent différées.
|
|
|
|
Le mécanisme observé dans `actix-auth-app` est documenté comme corpus technique à adapter, pas comme code autoritaire à copier.
|
|
|
|
La stable `0.0.1` matérialise `knowledge-web-lib` et les trois launchers `knowledge-*-server`. La bibliothèque commune possède le rendu Maud, la sélection dev-server/manifest Vite et le service des assets de production ; les trois `main.rs` ne contiennent que la sélection de façade et du nom de variable d'environnement de bind.
|
|
|
|
Le runtime exige un bind configuré par launcher et l'une des deux sources d'assets suivantes : `KNOWLEDGE_VITE_DEV_ORIGIN` en développement ou `KNOWLEDGE_VITE_MANIFEST_PATH` en production. `KNOWLEDGE_ASSET_BASE_PATH` peut remplacer le préfixe `/` de production. Aucune route admin/login n'est matérialisée à ce stade.
|
|
|
|
## Invariants de fondation
|
|
|
|
- Git est la source autoritaire du contenu versionné.
|
|
- Une forge est une intégration optionnelle et ne constitue pas une dépendance du domaine.
|
|
- Les trois applications publiques sont déployables séparément mais composent des bibliothèques communes.
|
|
- PostgreSQL conserve l'état applicatif partagé et les projections ; il ne remplace pas Git comme vérité du contenu publié.
|
|
- Chaque serveur Web conserve une frontière d'administration protégée propre à son domaine, indépendamment d'une éventuelle façade d'administration transversale.
|
|
- La lecture publique doit pouvoir fonctionner depuis des copies Git locales et un index/cache applicatif sans appel à une forge pour chaque requête.
|
|
- PGR, HOWTOs, snippets et décisions `project-local` conservent des forces et responsabilités documentaires distinctes.
|
|
- Une proposition externe ne publie jamais directement du contenu et conserve la révision Git de base utilisée pour sa création.
|
|
|
|
## Entrées principales
|
|
|
|
- [`RULES.md`](RULES.md) — point d'entrée normatif local ;
|
|
- [`ROADMAP.md`](ROADMAP.md) — trajectoire macro engagée ;
|
|
- [`CHANGELOG.md`](CHANGELOG.md) — changements utiles par release ;
|
|
- [`docs/000-README.md`](docs/000-README.md) — index documentaire ;
|
|
- [`docs/objectives/001-PROJECT_OBJECTIVES.md`](docs/objectives/001-PROJECT_OBJECTIVES.md) — objectifs et non-objectifs ;
|
|
- [`docs/architecture/001-PROJECT_PROFILE.md`](docs/architecture/001-PROJECT_PROFILE.md) — baseline PGR, profils/skeletons et matrice de décisions ;
|
|
- [`docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md`](docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md) — architecture de fondation multi-app Git/forge/PostgreSQL et frontières de contenu ;
|
|
- [`docs/architecture/003-PGR_ADOPTION_MAP.md`](docs/architecture/003-PGR_ADOPTION_MAP.md) — mapping final de l'adoption PGR `v0.1.3` vers les owners locaux Knowledge ;
|
|
- [`docs/rules/000-README.md`](docs/rules/000-README.md) — index des règles normatives locales autonomes ;
|
|
- [`docs/templates/001-NEW_SESSION_PROMPT.md`](docs/templates/001-NEW_SESSION_PROMPT.md) — pattern de reprise d'une future session sans consultation PGR automatique ;
|
|
- [`docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](docs/studies/001-AUTH_ADMIN_CORPUS_STUDY.md) — étude des deux corpus historiques auth/admin et décisions de réutilisation conceptuelle ;
|
|
- [`docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — étude ciblée du pattern Vite manifest / Actix / Maud à adapter pour Knowledge ;
|
|
- [`docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`](docs/studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation `beta.1`, état matérialisé, DEFER conservés et revue d'horizon ;
|
|
- [`docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](docs/studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) — comparaison processus Git / `gix` / `git2` et décision d'implémentation de lecture ;
|
|
- [`docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md`](docs/studies/006-V0_0_3_GIT_WRITE_STUDY.md) — choix de la prochaine mission, stratégie de worktree d'écriture et invariants de push gardé ;
|
|
- [`docs/plans/001-V0_0_1_FOUNDATION_PLAN.md`](docs/plans/001-V0_0_1_FOUNDATION_PLAN.md) — plan historique de la fondation stable `0.0.1` ;
|
|
- [`docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md`](docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md) — plan historique de la stable `0.0.2`, gates et décisions de fermeture ;
|
|
- [`docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md`](docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md) — plan actif de l'écriture Git contrôlée et du push gardé ;
|
|
- [`docs/validation/001-VALIDATION_MATRIX.md`](docs/validation/001-VALIDATION_MATRIX.md) — matrice de validation ;
|
|
- [`prompts/001-V0_0_1_START_PROMPT.md`](prompts/001-V0_0_1_START_PROMPT.md) — prompt de démarrage autoritaire de la release.
|
|
- [`prompts/002-V0_0_2_START_PROMPT.md`](prompts/002-V0_0_2_START_PROMPT.md) — handoff historique exécuté pour ouvrir `0.0.2` depuis la stable `v0.0.1` vérifiée.
|
|
- [`prompts/003-V0_0_3_START_PROMPT.md`](prompts/003-V0_0_3_START_PROMPT.md) — prompt local de reprise de `0.0.3` depuis la stable `v0.0.2` publiée et vérifiée.
|
|
|
|
## Langue et nomenclature
|
|
|
|
Les noms de fichiers, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.
|