8.5 KiB
Règles SaseDev Knowledge
Scope
Ce document gouverne le workspace applicatif sasedev-knowledge et sert de point d'entrée normatif local.
Le contenu éditorial publié par PGR, HOWTOs et snippets vit dans des dépôts Git distincts et conserve sa propre gouvernance. Les règles de ce dépôt ne transforment pas ces contenus en sous-modules normatifs de l'application.
Baseline PGR
La fondation 0.0.1 est cadrée à partir de la stable PGR v0.1.1, vérifiée par son rapport post-tag publish.001 PASS.
Empreinte de l'archive PGR autoritaire utilisée pour ce cadrage :
SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
Les contrats PGR adoptés sont instanciés localement dans ce dépôt. PGR n'est pas une dépendance runtime ou build de Knowledge.
Owners PGR applicables
La fondation retient les owners suivants dans leur scope réel :
200 gouvernance et lifecycle
210 workflow plan/delta/history/handoff
220 composition des skeletons pendant l'instanciation
300 documentation
400 validation proportionnée
500 famille langage/écosystème
510 Rust/Cargo
530 TypeScript
540 écosystème de packages JavaScript
550 Vite lorsque Vite est sélectionné
560 CSS/Sass
700 famille framework pour les frameworks réellement utilisés
Les skeletons 001-PROJECT_GOVERNANCE_FOUNDATION, 002-RUST_CARGO_WORKSPACE et 003-WEB_FRONTEND sont les spécialisations retenues pour 0.0.1, avec matérialisation progressive selon le plan.
Le profil 710-TAURI n'est pas applicable au produit Web actuel. Aucun skeleton Tauri n'est adopté.
Les profils Java/Maven/Gradle, Android et les autres technologies absentes du projet restent hors scope.
Priorité et décisions locales
Les obligations PGR réellement adoptées priment sur une préférence locale de Knowledge dans le même scope.
Les choix propres au produit restent locaux lorsqu'aucun owner PGR plus spécifique ne les impose. C'est notamment le cas de l'architecture Git/forge/PostgreSQL, du choix Actix Web/Maud, de Bootstrap, de la topologie à trois applications Web et de la topologie des dépôts de contenu.
Aucun OVERRIDE PGR n'est établi par 0.0.1-alpha.1.fix.1.
Les décisions différées sont explicites dans docs/architecture/001-PROJECT_PROFILE.md. Une valeur différée ne doit pas être remplacée par un choix arbitraire provenant d'un autre projet.
Version et workflow
VERSION est le repère canonique simple de la release unit applicative.
Knowledge adopte le workflow PGR :
delta -> application -> gate opérateur -> history observé -> application du history -> commit/push -> delta suivant
Une prévalidation par l'assistant ne constitue jamais un PASS opérateur.
Les FAIL, PARTIAL et BLOCKED observés sont conservés. Une correction limitée à la tranche courante utilise .fix.N.
Aucun history n'est créé avant réception de preuves opérateur réelles.
Politique Eclipse et fichiers locaux
Les métadonnées Eclipse propres à une machine restent ignorées, notamment .project, .classpath et les préférences non partagées.
L'exception versionnée est :
.settings/org.eclipse.core.resources.prefs
Elle fixe l'encodage UTF-8 du projet et doit rester traquée par Git. Le .gitignore doit donc ignorer .settings/* puis réautoriser explicitement ce fichier.
Topologie applicative
Le workspace possède trois applications serveur distinctes :
knowledge-pgr-server
knowledge-howtos-server
knowledge-snippets-server
Chaque package exécutable reste une couche de composition mince conformément au profil Rust/Cargo PGR. La logique partagée appartient aux crates -lib appropriées et ne doit pas être dupliquée entre les trois main.rs.
Les trois applications peuvent être déployées, redémarrées et dimensionnées séparément. Cette séparation de launchers ne constitue pas une autorisation à fragmenter arbitrairement le domaine en microservices.
Chaque application serveur MUST pouvoir protéger une surface d'administration propre à son domaine. Cette exigence porte sur la frontière d'autorisation et non sur un chemin HTTP particulier : les routes telles que /admin, /login, /adminapi ou toute alternative restent DEFER tant que le routage Web n'est pas matérialisé.
Une éventuelle quatrième application d'administration MAY agréger plus tard des fonctions transversales. Elle MUST NOT devenir l'unique point de contrôle des opérations privilégiées : les trois applications conservent l'autorisation côté serveur de leurs propres cas d'usage d'administration.
Le modèle détaillé des rôles, permissions, scopes ou capabilities reste DEFER. L'interface cliente ou la visibilité d'un lien d'administration ne constitue jamais à elle seule une preuve d'autorisation.
Git, forge et contenu
Git est la source autoritaire du contenu versionné publié.
Le domaine MUST pouvoir fonctionner avec un dépôt Git local ou un remote Git générique sans API de forge.
La baseline prévoit au minimum trois sources de contenu indépendantes : pgr, howtos et snippets. Une famille MAY ultérieurement agréger plusieurs repositories ; le nombre trois n'est donc pas codé comme limite du domaine.
Les capacités spécifiques d'une forge — webhooks, pull/merge requests, issues, releases, permissions et métadonnées similaires — MUST rester derrière des adapters optionnels.
Une proposition externe MUST conserver la révision Git de base et MUST NOT écrire directement dans le contenu publié.
La synchronisation générique MUST disposer d'une voie indépendante des webhooks. Les hooks et webhooks MAY accélérer une synchronisation qui converge vers le même cas d'usage interne.
PostgreSQL
PostgreSQL est destiné à l'état applicatif : comptes, sessions, propositions, revues, audit applicatif, index, recherche, synchronisation et jobs.
La baseline de fondation retient une base PostgreSQL logique partagée par les trois applications afin de conserver un état transversal cohérent et de permettre les relations entre PGR, HOWTOs et snippets. Une séparation physique ultérieure reste possible seulement si une contrainte observée la justifie.
Le texte et les métadonnées éditoriales qui constituent le contenu publié restent autoritaires dans Git. Une copie ou projection PostgreSQL de ces données est dérivée et reconstructible.
Le choix du driver, de l'ORM ou de la stratégie de migration reste différé jusqu'à une tranche qui en a réellement besoin.
Frontières documentaires
Knowledge distingue au minimum :
PGR connaissance normative
HOWTO guidance procédurale et explicative
snippet exemple court et contextualisé
project-local décision instanciée dans un projet précis
Une référence entre ces familles ne change pas leur force normative.
Un HOWTO ou snippet MAY référencer une règle/owner PGR. Une règle PGR MAY référencer une guidance externe uniquement comme ressource facultative ; PGR doit rester intelligible sans elle.
Stack locale de départ
Sous réserve des décisions différées et de la matérialisation par tranche, Knowledge retient comme intentions locales :
- Rust stable, édition 2024 et workspace Cargo ;
- trois launchers Actix Web distincts pour PGR, HOWTOs et snippets ;
- Maud pour le SSR lorsque pertinent ;
- Vite + TypeScript pour les assets et interactions frontend ;
- Sass ;
- Bootstrap ;
- PostgreSQL partagé pour l'état applicatif transversal.
Ces choix ne sont pas présentés comme des règles PGR universelles.
Rust et crates
Le préfixe de crate retenu est knowledge-.
Les responsabilités candidates sont documentées dans l'architecture. Une crate n'est matérialisée que lorsqu'elle possède une responsabilité réelle. Le suffixe -api n'est pas utilisé par anticipation.
Le profil Rust strict PGR s'appliquera aux crates matérialisées, notamment Rust 2024, unsafe interdit par défaut, lints stricts, exports publics maîtrisés et chemins explicites.
Secrets et configuration locale
Les secrets, tokens, mots de passe, clés privées et credentials Git/forge/database ne doivent pas être versionnés ni journalisés.
Une configuration locale sensible doit être ignorée ; un fichier .example MAY documenter uniquement des valeurs factices lorsqu'il devient utile.
Langue
Les noms techniques, chemins, crates, identifiants et code sont en anglais. La documentation normative et explicative principale est en français.