Persistance Database¶

Status: CURRENT

Rôle¶

La persistance conserve durablement les états produits par CMonChoix Platform. Elle matérialise des données d'import, des états intermédiaires, des résultats métier, des projections et des états techniques.

Elle n'est pas une couche de décision. Le sens d'une donnée persistée vient du composant qui l'a produite et du contrat associé à cette structure.

Position dans l'architecture¶

Sources marchandes
      ↓
Pipeline
      ↓
Domain Core / Vertical Modules
      ↓
Résultats métier
      ↓
Builders de projection
      ↓
Write Services
      ↓
Persistance
      ↓
Read Services / Runtime / Frontend

Le point important est la séparation entre calculer et écrire : le composant qui décide du contenu n'est pas nécessairement celui qui effectue l'écriture technique.

Ce qui peut être persisté¶

Données d'import et Stage¶

Elles permettent la traçabilité, l'audit et la reprise.

Elles restent proches des sources marchandes et ne doivent pas être interprétées comme un résultat métier final.

États intermédiaires¶

Certaines étapes de normalisation, enrichissement ou résolution peuvent conserver un état de travail pour rendre le traitement explicable et reprenable.

Un état intermédiaire peut être valide pour son étape sans être directement consommable par le Frontend.

Résultats métier¶

Lorsque des décisions du Domain Core sont persistées, la base conserve leur état ; elle ne les redécide pas.

Les statuts resolved, unknown, ambiguous et conflict doivent rester explicites lorsqu'ils font partie du contrat concerné.

Projections¶

Les projections sont des vues dérivées destinées à la lecture. Leur persistance doit passer par les Write Services ou mécanismes officiels prévus pour cette famille.

Elles doivent rester reconstruisibles à partir d'une source amont autoritative.

États techniques¶

Sont également persistés, selon les besoins du Runtime :

états de run ;
informations de reprise ;
options techniques ;
locks ;
caches ;
versions de schéma ;
métriques et historiques.

Ces données ne doivent pas être confondues avec la vérité produit.

Règle d'écriture¶

Une écriture persistante doit être :

explicite ;
attribuable ;
bornée par un périmètre ;
mesurable ;
vérifiable après exécution.

Le chemin recommandé est :

Observation
   ↓
Audit / simulation
   ↓
Décision validée
   ↓
Write Service ou mécanisme technique dédié
   ↓
Persistance
   ↓
Nouvel audit / vérification

Frontend et persistance¶

Le Frontend ne doit pas écrire directement dans les structures métier ou de projection pendant le rendu d'une requête publique.

Il consomme des projections et délègue toute action persistante explicite à une façade ou un service adapté.

Un update_option(), une requête $wpdb ou un rebuild exécuté depuis un renderer public est un signal d'architecture à examiner.

Runtime et persistance¶

Le Runtime peut déclencher des écritures techniques ou orchestrer des Write Services, mais il ne doit pas devenir l'endroit où la règle métier est décidée.

Le Runtime orchestre ; il ne remplace ni Domain Core ni Write Service.

Reconstruction¶

Une structure reconstruisible doit avoir une source amont identifiable.

Pour une projection :

identifier la vérité source ou les données amont ;
vérifier leur cohérence ;
exécuter le Builder approprié ;
persister via le Write Service ;
relire et auditer le résultat.

Modifier directement les lignes d'une projection contourne cette chaîne et crée un état non reproductible.

Idempotence et reprise¶

Les opérations d'écriture importantes doivent, lorsque le cas le permet :

reconnaître les lignes déjà conformes ;
éviter les duplications au rejeu ;
publier les compteurs changed, unchanged, skipped, failed ou équivalents ;
permettre de reprendre un batch interrompu ;
conserver suffisamment de contexte pour expliquer une exécution partielle.

Rollback et récupération¶

Avant une opération large ou destructive, déterminer explicitement :

si les données sont reconstruisibles ;
si une sauvegarde est nécessaire ;
comment annuler ou restaurer ;
quel état permettra de vérifier le retour à la normale.

Pour les opérations d'exploitation générales, les commandes canoniques documentées restent notamment :

make backup
make backup-verify
make restore-check

Elles ne remplacent pas un plan de rollback métier spécifique à une migration ou à une réparation.

Diagnostic d'une persistance incohérente¶

Quand une valeur persistée semble incorrecte :

identifier la table et sa responsabilité ;
identifier le writer ou service qui l'alimente ;
vérifier si l'entrée du writer était correcte ;
comparer avec la couche amont ;
vérifier le run, la version et les filtres ;
déterminer si l'erreur vient du calcul, de l'écriture ou d'une donnée périmée ;
ne corriger qu'après avoir trouvé la couche fautive.

Erreurs fréquentes¶

« La valeur est dans la base donc elle est vraie »¶

Faux : elle peut être intermédiaire, périmée, dérivée ou issue d'un ancien run.

« Je peux corriger la projection à la main »¶

La correction sera perdue au rebuild et masque la cause.

« Une migration SQL peut décider une nouvelle identité »¶

Une migration peut déplacer ou transformer une représentation persistée ; la décision métier doit rester dans la couche métier appropriée.

« Un dry-run signifie forcément zéro écriture »¶

Pas sans vérification du comportement réel. Certains outils historiques peuvent avoir des effets techniques même sous des noms rassurants.

Invariants¶

Toute donnée persistée possède une origine identifiable.
La persistance ne crée pas de vérité métier.
Les écritures sont explicites et traçables.
Les projections restent dérivées et reconstruisibles.
Le Frontend public ne modifie pas silencieusement l'état persistant.
Les opérations larges possèdent un plan de reprise ou de récupération.
La vérification après écriture est obligatoire.