182 lines
17 KiB
Markdown
182 lines
17 KiB
Markdown
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
|
<!-- version: 11 -->
|
|
|
|
# Profil du projet Knowledge
|
|
|
|
## Baseline autoritaire
|
|
|
|
La stable produit depuis laquelle `0.0.2` est ouverte est :
|
|
|
|
```text
|
|
Knowledge stable tag v0.0.1
|
|
Knowledge stable commit 98ec46fe73bd50dacbe6be220650d87dd2000b74
|
|
Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
|
|
Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
|
|
Knowledge start prompt prompts/002-V0_0_2_START_PROMPT.md
|
|
```
|
|
|
|
La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`.
|
|
|
|
Le démarrage de `0.0.2` vérifie puis adopte la stable PGR courante :
|
|
|
|
```text
|
|
PGR stable tag v0.1.3
|
|
PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
|
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
|
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
|
|
```
|
|
|
|
L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP, `290` fichiers, `42` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Son rapport post-tag indique `48/48` tests Python et les audits Markdown propres.
|
|
|
|
Cette prévalidation ne remplace aucune gate opérateur Knowledge.
|
|
|
|
## Nature de l'adoption
|
|
|
|
Knowledge n'est plus un nouveau dépôt à instancier : `0.0.2-alpha.1` migre un projet existant de la baseline PGR `v0.1.1` vers `v0.1.3`.
|
|
|
|
L'owner PGR `230-ADOPTION` devient applicable à cette migration ; son contrat est instancié localement par les décisions suivantes :
|
|
|
|
- partir d'une baseline autoritaire observée ;
|
|
- sélectionner uniquement les owners réellement applicables ;
|
|
- classifier `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ;
|
|
- préserver les décisions locales compatibles ;
|
|
- ne pas réécrire les commits, deltas, histories ou documents historiques pour simuler une conformité rétroactive ;
|
|
- valider proportionnellement la migration.
|
|
|
|
Les classifications locales restent :
|
|
|
|
- `ADOPT` — contrat PGR applicable retenu ;
|
|
- `KEEP-LOCAL` — choix propre à Knowledge, compatible et non possédé par un owner PGR plus spécifique ;
|
|
- `OVERRIDE` — règle PGR applicable remplacée ou raffinée localement avec justification ;
|
|
- `DEFER` — choix volontairement reporté avec condition de reprise.
|
|
|
|
## Owners et skeletons applicables
|
|
|
|
| Élément | Décision courante | État Knowledge | Motif |
|
|
|----------------------------------------------|------------------------------------|-----------------|---------------------------------------------------------------|
|
|
| `200-GOVERNANCE` | `ADOPT` | actif | lifecycle/version locale |
|
|
| `210-WORKFLOW` | `ADOPT` | actif | plan/delta/history/handoff |
|
|
| `220-SKELETONS` | `ADOPT` comme référence | actif | les skeletons existants ne sont pas réappliqués mécaniquement |
|
|
| `230-ADOPTION` | `ADOPT` | `0.0.2-alpha.1` | migration explicite PGR `v0.1.1 -> v0.1.3` |
|
|
| `300-DOCUMENTATION` | `ADOPT` | actif | rôles documentaires et taxonomie |
|
|
| `400-VALIDATION` | `ADOPT` | actif | preuves proportionnées et autorité opérateur |
|
|
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | actif | backend Rust/workspace Cargo strict |
|
|
| `530-TYPESCRIPT` | `ADOPT` | actif | frontend durable TypeScript |
|
|
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | actif | npm/lockfile/scripts explicites |
|
|
| `550-VITE` | `ADOPT` | actif | dev server/build/cache/outputs/manifest |
|
|
| `560-CSS_SASS` | `ADOPT` | actif | CSS/Sass et outputs |
|
|
| `700-FRAMEWORKS` | `ADOPT` | actif | cadre générique des frameworks |
|
|
| `710-TAURI` | `DEFER` / non applicable | inchangé | aucun host desktop/mobile Tauri |
|
|
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` comme référence historique | matérialisé | fondation locale existante |
|
|
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` comme référence historique | matérialisé | workspace Rust existant |
|
|
| skeleton `003-WEB_FRONTEND` | `ADOPT` comme référence historique | matérialisé | frontend indépendant du host |
|
|
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | actif | restore/typecheck/build/smoke proportionnés |
|
|
|
|
Les owners Java/Maven/Gradle restructurés dans PGR `0.1.2`, le profil Android réévalué en `0.1.3` et les autres technologies absentes ne sont pas sélectionnés. Leur évolution n'entraîne donc aucune migration de code Knowledge.
|
|
|
|
Aucun `OVERRIDE` n'est requis par l'adoption `v0.1.3`.
|
|
|
|
## Matrice des décisions importantes
|
|
|
|
| Décision | Classification | Contrat retenu / condition de reprise |
|
|
|----------------------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------------------|
|
|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
|
|
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
|
|
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
|
|
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
|
|
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
|
|
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
|
|
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
|
|
| Implémentation Git de `0.0.2` | `KEEP-LOCAL` | processus `git` contrôlé derrière `knowledge-git-api` ; décision réévaluable derrière le contrat |
|
|
| Configuration physique Git | `KEEP-LOCAL` | `knowledge-git-lib` matérialisée en `0.0.2-alpha.2` ; source locale/remote + racine d'état ; pas dans le domaine |
|
|
| Copies Git générées | `KEEP-LOCAL` | racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision |
|
|
| Partage du cache Git entre processus | `DEFER` | état root exclusif à une instance backend en `0.0.2` ; reprendre avec verrouillage inter-processus réel |
|
|
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
|
|
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
|
|
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/périodique convergent vers le même cas d'usage ; hooks/webhooks restent accélérateurs |
|
|
| Scheduler périodique concret | `DEFER` | créer seulement lorsque son owner runtime/lifecycle est démontré |
|
|
| Dernière révision observée en `0.0.2` | `KEEP-LOCAL` | fournie par l'appelant et retournée par le cas d'usage ; pas de pseudo-persistance locale |
|
|
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée future pour état transversal/projections ; jamais vérité du contenu Git publié |
|
|
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
|
|
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo déjà matérialisé |
|
|
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; manifests Cargo versionnés |
|
|
| Actix Web | `KEEP-LOCAL` | trois launchers existants et composition partagée dans `knowledge-web-lib` |
|
|
| Maud | `KEEP-LOCAL` | rendu SSR commun dans `knowledge-web-lib` |
|
|
| TypeScript | `ADOPT` | owner `530` |
|
|
| Package manager frontend | `KEEP-LOCAL` | npm ; `package-lock.json` versionné |
|
|
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview de références et manifest consommé par Maud |
|
|
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source et assets réellement servis |
|
|
| Bootstrap | `KEEP-LOCAL` | framework CSS local Knowledge, jamais règle PGR universelle |
|
|
| Racine frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` |
|
|
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; rendu runtime Maud |
|
|
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` |
|
|
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
|
|
| Migrations PostgreSQL | `DEFER` | reprendre avec le premier schéma réel |
|
|
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif lorsque ce scope sera engagé |
|
|
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
|
|
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte différée |
|
|
| Quatrième application d'administration | `DEFER` | agréger seulement si une responsabilité transverse apparaît |
|
|
| Modèle rôles/capabilities | `DEFER` | reprendre avec les cas d'usage d'autorisation réels |
|
|
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel |
|
|
| Autres noms de crates | `DEFER` | créer uniquement lorsque l'ownership est démontré |
|
|
|
|
## Nomenclature de crates
|
|
|
|
Les packages matérialisés sont :
|
|
|
|
```text
|
|
knowledge-domain-lib types métier stables de famille/source
|
|
knowledge-git-api contrat passif GitRepository provider-neutral
|
|
knowledge-git-lib implémentation Git générique + configuration physique + état local contrôlé
|
|
knowledge-sync-api contrat passif RepositoryEventSource
|
|
knowledge-web-lib composition Actix/Maud/Vite partagée
|
|
knowledge-pgr-server launcher PGR mince
|
|
knowledge-howtos-server launcher HOWTOs mince
|
|
knowledge-snippets-server launcher snippets mince
|
|
```
|
|
|
|
`knowledge-git-lib` devient réelle en `0.0.2-alpha.2`. `knowledge-app-lib` reste seulement l'owner candidat du cas d'usage de synchronisation partagé et ne sera matérialisée que si l'orchestration réelle démontre cette responsabilité.
|
|
|
|
Les responsabilités suivantes restent candidates et non matérialisées :
|
|
|
|
```text
|
|
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
|
|
knowledge-forge-gitea-lib adapter Gitea optionnel
|
|
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
|
|
```
|
|
|
|
Règles de création :
|
|
|
|
- ne pas créer une crate uniquement pour refléter un diagramme ;
|
|
- ne pas utiliser `-api` sans frontière de contrat indépendante réellement nécessaire ;
|
|
- garder le domaine indépendant d'Actix, Gitea, Git process et PostgreSQL ;
|
|
- garder les adapters/implémentations dépendants des contrats, jamais l'inverse ;
|
|
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
|
|
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
|
|
|
|
## Corpus auth/admin étudié en 0.0.1
|
|
|
|
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` restent des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
|
|
|
|
Elles justifient de conserver séparées l'identité/authentification partagée, l'autorisation privilégiée propre à chaque application et une éventuelle façade transverse ultérieure. Elles ne justifient toujours pas de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA pendant `0.0.2`.
|
|
|
|
## Résultat de l'adoption PGR 0.1.3
|
|
|
|
L'adoption est bornée aux évolutions réellement applicables :
|
|
|
|
- `230-ADOPTION` devient applicable parce que Knowledge est désormais un projet existant ;
|
|
- les owners déjà adoptés restent actifs ;
|
|
- les changements PGR Java/Maven/Gradle/Android ne s'appliquent pas ;
|
|
- le `DEFER` Tauri reste inchangé ;
|
|
- les skeletons servent de références de comparaison et ne sont pas réinstanciés ;
|
|
- les anciennes gates/deltas/histories `0.0.1` conservent leur contexte historique, y compris les états `FAIL` et anciennes décisions corrigées plus tard ;
|
|
- aucune règle produit Git/process n'est promue en règle PGR générale.
|
|
|
|
## Décisions à rouvrir
|
|
|
|
La release `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture.
|
|
|
|
Restent différés : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, écriture/publication Git et partage concurrent de la même racine Git entre plusieurs processus.
|
|
|
|
Un changement de scope produit, un besoin mesuré ou une contrainte d'exploitation peut déclencher un REPLAN ; il ne justifie pas un choix anticipé.
|