Base de données — vue d’ensemble¶

Status: CURRENT

À quoi sert la couche Database ?¶

La couche Database fournit la persistance de CMonChoix Platform. Elle conserve durablement les données nécessaires au Pipeline, au Domain Core, aux projections, au Runtime et aux outils d’exploitation.

Elle n’est pas une couche métier autonome : la présence d’une valeur en base ne suffit jamais à en faire une vérité métier.

Sources marchandes
      ↓
Import / Stage
      ↓
Normalisation / enrichissement
      ↓
Domain Core + Vertical Modules
      ↓
Canonical Identity
      ↓
Projections
      ↓
Read Services / Frontend / Runtime

La base matérialise les états produits par ces différentes étapes afin qu’ils puissent être relus, audités, repris ou reconstruits.

Pourquoi plusieurs familles de données ?¶

Toutes les données persistées n’ont ni le même rôle ni la même durée de vie.

On distingue conceptuellement :

les données d’import ou de Stage, proches des sources marchandes ;
les données intermédiaires de normalisation et d’enrichissement ;
les données métier consolidées utilisées par les couches applicatives ;
les projections, dérivées et optimisées pour la lecture ;
les données techniques du Runtime, des synchronisations, des verrous, caches ou historiques.

Le mainteneur doit toujours identifier la famille de données avant d’interpréter une table ou une colonne.

Règle fondamentale : une table n’explique pas toute seule son sens¶

Avant toute intervention SQL, vérifier :

quel composant écrit cette structure ;
quel composant la lit ;
si elle est source, intermédiaire, projection ou état technique ;
si elle est reconstruisible ;
si une écriture officielle existe déjà ;
si une correction doit se faire ici ou plus en amont.

Modifier directement une projection parce qu’un écran est incorrect peut masquer le vrai défaut et perdre la correction au prochain rebuild.

Préfixe SQL du runtime actuel¶

Le runtime CMonChoix actuellement documenté utilise le préfixe WordPress :

wp_3888956

Il faut cependant éviter de coder ce préfixe en dur dans une nouvelle logique applicative lorsque WordPress fournit déjà le préfixe de table. Dans un diagnostic ou une commande opératoire, utiliser la valeur du runtime réellement observé.

Stage et import¶

Le Stage conserve un état proche de la donnée marchande afin de rendre les traitements observables et rejouables.

Il sert notamment à :

examiner ce que le marchand a réellement envoyé ;
comparer deux imports ;
diagnostiquer une normalisation ;
reprendre un traitement lorsque le contrat du Pipeline le permet.

Le Stage n’est pas la vérité produit et ne doit pas être lu directement par le Frontend public.

Données normalisées et enrichies¶

Après l’import, les données peuvent être transformées progressivement :

normalisation des identifiants ;
harmonisation des formats ;
enrichissements ;
préparation de la résolution ;
preuves et indicateurs de qualité.

Ces états sont utiles pour expliquer comment la Platform arrive à une décision. Ils ne doivent pas être confondus avec une projection finale.

Canonical Identity et vérité métier¶

La Canonical Identity représente l’identité métier construite à partir des preuves et des règles du Domain Core et, lorsque nécessaire, des Vertical Modules.

La base peut persister le résultat ou des éléments nécessaires à sa reconstruction, mais elle ne décide pas si une identité est resolved, unknown, ambiguous ou conflict.

Ces statuts sont des résultats métier. Une requête SQL ne doit pas les transformer silencieusement pour rendre les données « plus propres ».

Projections¶

Une projection est une représentation dérivée, déterministe et optimisée pour la lecture.

Elle sert à éviter que les consommateurs reconstruisent eux-mêmes :

les titres ;
les slugs ;
les meilleures offres ;
les agrégations ;
les relations de navigation ;
les autres décisions déjà prises en amont.

Une projection doit rester reconstruisible à partir d’un état amont suffisamment fiable.

Données techniques¶

La base contient également des états purement techniques :

synchronisations et runs ;
scheduling ;
verrous ;
caches ;
rate limits ;
options techniques ;
historiques d’exécution ;
éventuelles structures temporaires.

Ces données appartiennent au Runtime ou à l’Infrastructure, pas au Domain Core.

Une option WordPress ou un transient technique ne doit pas devenir une règle métier cachée.

Lecture et écriture¶

Read Services¶

Les Read Services peuvent lire les structures persistées nécessaires aux audits, comparaisons, dumps, previews et rapports.

Ils restent strictement read-only lorsqu’ils sont documentés comme tels.

Write Services¶

Une mutation durable doit passer par un Write Service, une façade applicative ou un mécanisme d’infrastructure explicitement prévu pour cette responsabilité.

Le principe est :

Observation
   ↓
Audit
   ↓
Simulation / dry-run
   ↓
Validation
   ↓
Write Service
   ↓
Persistance
   ↓
Vérification

Une modification SQL manuelle en production est une exception opératoire, pas un modèle d’architecture.

Comment diagnostiquer un problème de données¶

Si une donnée affichée semble fausse, suivre de préférence ce chemin :

observer la projection consommée ;
identifier le reader ou Read Service qui la fournit ;
remonter au Builder ou au service qui l’a construite ;
examiner l’état métier amont ;
examiner la normalisation et le Stage ;
comparer avec la source marchande ;
seulement ensuite décider où corriger.

Cette méthode évite deux erreurs classiques :

corriger la projection alors que la source amont est fausse ;
corriger le Stage alors que la règle de Domain Core est incorrecte.

Reconstruction¶

Une structure reconstruisible ne doit pas être réparée à la main si son état amont est correct.

Pour une projection :

vérifier la source amont ;
vérifier le Builder ;
vérifier le Write Service ;
reconstruire avec le mécanisme officiel ;
vérifier les compteurs et l’état final.

Une ancienne mutation destructive peut contaminer une projection historique. Dans ce cas, la projection doit être régénérée avant d’utiliser ses métriques comme baseline.

Sécurité avant intervention SQL¶

Avant toute écriture sensible :

identifier précisément le périmètre ;
mesurer le nombre de lignes concernées ;
vérifier si une commande ou un Write Service officiel existe ;
prendre une sauvegarde lorsque le risque le justifie ;
définir la procédure de rollback ou de reconstruction ;
effectuer une lecture avant/après ;
documenter les compteurs modifiés.

Les opérations de sauvegarde et de restauration sont documentées dans les pages Operations.

Erreurs fréquentes¶

« La colonne contient cette valeur, donc c’est la vérité »¶

Faux. Il faut identifier qui l’a produite et dans quelle couche elle appartient.

« Je peux corriger directement la projection »¶

À éviter. La prochaine reconstruction peut effacer la correction et le défaut amont restera présent.

« Le Frontend peut lire le Stage pour dépanner »¶

Non. Cela contourne la frontière projection-first et réintroduit de la logique de traitement côté lecture publique.

« Une table temporaire est forcément sans effet »¶

Non. Sa création reste un effet technique. Certaines commandes audit ou dry-run peuvent donc ne pas être strictement read-only.

« Le préfixe SQL est une constante du produit »¶

Non. wp_3888956 est la valeur documentée pour le runtime actuel ; elle ne doit pas devenir une hypothèse universelle dans le code.

Invariants¶

La Database persiste ; elle ne décide pas de la vérité métier.
Stage, états intermédiaires, projections et états techniques restent distinguables.
Une projection reste dérivée et reconstruisible.
Le Frontend public ne lit pas directement les structures internes du Pipeline.
Les statuts métier restent explicites, y compris unknown, ambiguous et conflict.
Une écriture durable passe par une frontière d’écriture explicite.
Les interventions SQL manuelles restent exceptionnelles, bornées et vérifiables.
Les données nécessaires aux audits et reconstructions ne sont pas supprimées sans politique explicite.