67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# Architecture du stockage
|
||
|
||
## 1. Responsabilité de `kb-store`
|
||
|
||
`kb-store` réunit :
|
||
|
||
- les contrats store-neutral ;
|
||
- les DTO et entités persistées ;
|
||
- la pagination et les rapports de santé ;
|
||
- les traits de repositories ;
|
||
- l’implémentation PostgreSQL ;
|
||
- les migrations, requêtes et mécanismes de replay associés.
|
||
|
||
La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL.
|
||
|
||
## 2. Frontières
|
||
|
||
### 2.1 Contrats store-neutral
|
||
|
||
Les contrats ne doivent pas dépendre des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages et erreurs nécessaires aux consommateurs.
|
||
|
||
### 2.2 Adaptateur PostgreSQL
|
||
|
||
Le module PostgreSQL possède :
|
||
|
||
- la connexion et l’initialisation ;
|
||
- l’application idempotente des migrations ;
|
||
- les requêtes typées ;
|
||
- les diagnostics ;
|
||
- les opérations de replay et de sélection de candidats.
|
||
|
||
### 2.3 Modèles partagés
|
||
|
||
Les modèles métier communs restent dans `kb-lib` lorsqu’ils dépassent la seule persistance. `kb-store` ne doit pas créer une seconde définition concurrente d’un contrat partagé.
|
||
|
||
## 3. Catégories de données
|
||
|
||
Le stockage couvre plusieurs niveaux :
|
||
|
||
- données brutes acquises ;
|
||
- transactions et instructions canoniques ;
|
||
- événements de décodage et diagnostics ;
|
||
- matérialisations ;
|
||
- états de campagne et candidats de replay ;
|
||
- informations opérationnelles et de santé.
|
||
|
||
Les noms de tables, contrats de replay et APIs publiques sont documentés dans `kb-store/USAGE.md` à partir des exports et migrations actuels.
|
||
|
||
## 4. Propriétés attendues
|
||
|
||
- initialisation idempotente ;
|
||
- pagination bornée ;
|
||
- traçabilité des campagnes ;
|
||
- absence de double effet lors des replays ;
|
||
- validation stricte des entrées ;
|
||
- erreurs explicites ;
|
||
- séparation entre données brutes, résultats de décodage et matérialisations.
|
||
|
||
La série `0.5.3` réauditera cette fondation avant l’arrivée des protocoles trading. Cet audit doit notamment distinguer les timestamps observés sur la blockchain des timestamps d’insertion et de mise à jour locaux, normaliser la structure interne de `kb-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans casser les contrats de replay existants.
|
||
|
||
## 5. Données de test
|
||
|
||
Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont nécessaires aux tests.
|