77 lines
4.3 KiB
Markdown
77 lines
4.3 KiB
Markdown
<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
|
||
<!-- version: 7 -->
|
||
|
||
# Architecture du stockage
|
||
|
||
## 1. Responsabilité de `ks-store`
|
||
|
||
`ks-store` réunit :
|
||
|
||
- la façade publique backend-agnostique `Store` et ses options d'ouverture ;
|
||
- les contrats store-neutral ;
|
||
- les DTO et entités persistées ;
|
||
- la pagination, le replay et les rapports de santé ;
|
||
- les traits de repositories ;
|
||
- les résumés runtime/init sanitisés ;
|
||
- l’implémentation PostgreSQL privée ;
|
||
- les migrations et requêtes appartenant au backend actif.
|
||
|
||
Depuis `0.5.3-pre.002`, les consommateurs ne construisent plus un backend concret. `ks-store` possède la connexion et le dispatch interne ; `PostgresStore`, `PgPool` et SQLx ne traversent plus sa frontière publique.
|
||
|
||
## 2. Frontières
|
||
|
||
### 2.1 Contrats store-neutral
|
||
|
||
Les contrats ne dépendent pas des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages, diagnostics et erreurs nécessaires aux consommateurs. `StoreOpenOptions` transporte un code backend et un objet d'options opaque ; seul `ks-store` interprète le moteur sélectionné.
|
||
|
||
Le résumé runtime expose des modèles logiques et des compteurs d'objets par catégorie sans publier les noms physiques. PostgreSQL peut ainsi exposer des compteurs `table`/`index`, tandis qu'un futur backend peut utiliser d'autres catégories sans modifier le desktop.
|
||
|
||
### 2.2 Adaptateur PostgreSQL
|
||
|
||
Le module PostgreSQL possède :
|
||
|
||
- la validation de ses options ;
|
||
- la connexion et l’initialisation ;
|
||
- l’application idempotente des migrations ;
|
||
- les requêtes typées ;
|
||
- les diagnostics physiques ;
|
||
- les opérations de replay et de sélection de candidats ;
|
||
- le target de tracing canonique `ks-store`, enrichi des champs `backend="postgres"`, `domain="ks-store.pg"` et `action` pour les opérations PostgreSQL.
|
||
|
||
Les détails physiques restent privés. Les erreurs et résumés traversant la façade ne doivent pas divulguer de DSN, password ou option sensible.
|
||
|
||
### 2.3 Modèles partagés
|
||
|
||
Les modèles métier communs restent dans `ks-lib` lorsqu’ils dépassent la seule persistance. `ks-store` ne doit pas créer une seconde définition concurrente d’un contrat partagé.
|
||
|
||
## 3. Catégories de données
|
||
|
||
Le stockage distingue quatre niveaux durables :
|
||
|
||
- **N1** — acquisition et raw canonique ;
|
||
- **N2** — Core Solana canonique ;
|
||
- **N3** — decode/materialization générique et journaux versionnés ;
|
||
- **N4** — projections spécialisées/queryables additives.
|
||
|
||
N1/N2/N3 constituent la fondation fortement gelée après `0.5.3`, sous réserve d'une urgence ou d'une omission structurelle majeure. N4 reste plus évolutif. Les replays N1 -> N2, N2 -> N3 et N3 -> N4 doivent pouvoir être exécutés indépendamment et de manière idempotente.
|
||
|
||
Les noms de tables, contrats de replay et APIs publiques sont documentés dans `ks-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` normalisera cette fondation avant l’arrivée des protocoles trading. Elle doit notamment distinguer `slot`, `block_time` et les timestamps d’acquisition/persistance, normaliser la structure interne de `ks-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans perdre les contrats de provenance et d’idempotence.
|
||
|
||
La même migration remplace le préfixe historique des tables Solana `kb_sol_*` par `k_sol_*`. La base peut encore être reconstruite ou migrée proprement avant `0.6.x`, il n’est donc pas nécessaire de conserver indéfiniment l’ancien préfixe. Le préfixe `kb_*` est réservé aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot, pas aux faits Solana simplement consommés par le bot.
|
||
|
||
## 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.
|