Invariants de la base de données¶

Status: CONTRACT

Rôle¶

Les invariants Database sont les propriétés qui doivent rester vraies malgré les évolutions de schéma, de Pipeline, de projections, de Runtime et de Frontend.

Ils servent de garde-fous pour éviter qu'une optimisation locale transforme la base en seconde source de vérité ou en couche métier implicite.

Invariants fondamentaux¶

1. La base persiste, elle ne décide pas¶

La Database conserve des états produits ailleurs. Elle ne décide ni de l'identité, ni de la qualité, ni de la résolution d'un conflit.

La vérité métier est portée par le Domain Core et les Vertical Modules selon leurs contrats.

2. Une projection est dérivée¶

Une projection reste une représentation reconstruisible optimisée pour la lecture.

Elle ne devient jamais une source primaire simplement parce qu'elle est facile à interroger.

3. Les statuts d'incertitude restent visibles¶

resolved, unknown, ambiguous et conflict sont des résultats métier distincts.

Une évolution Database ne doit pas transformer silencieusement les trois derniers en resolved, ni les masquer pour améliorer artificiellement un KPI.

4. Les traitements restent déterministes¶

À entrées, configuration et version identiques, le résultat logique doit rester stable.

Une reconstruction ne doit pas dépendre d'un ordre SQL implicite, d'un cache non identifié ou d'un état manuel impossible à reproduire.

5. Toute donnée significative est traçable¶

Il doit être possible de relier un état important à son origine : run, snapshot, source, version de code, projection ou opération d'écriture selon le cas.

6. Les responsabilités restent séparées¶

Les familles de données ont des rôles différents :

Famille	Rôle principal
Source / import	conserver ce qui vient de l'extérieur
Stage / intermédiaire	permettre traitement, audit et reprise
Métier	porter les résultats consolidés produits par les couches autorisées
Projection	servir la lecture et le Frontend
Historique	conserver la traçabilité
Technique	exécution, locks, caches, queue, monitoring, schéma

Une table ou structure peut évoluer, mais son rôle doit rester explicite.

7. Les écritures sont explicites¶

Une mutation persistante doit appartenir à un Write Service, une migration, un mécanisme d'infrastructure ou un Runtime action explicitement identifié.

Un bootstrap, un renderer, un audit ou un Read Service ne doit pas écrire silencieusement.

8. Les audits restent read-only¶

Un audit observe, compare et explique. Il ne corrige pas ce qu'il observe.

Un outil nommé audit ou dry-run n'est pas automatiquement read-only : les effets réels doivent être vérifiés.

9. Les projections restent reconstruisibles¶

Une projection ne doit pas contenir une information impossible à retrouver ou recalculer à partir des sources et contrats prévus.

Si une projection doit être corrigée régulièrement à la main, le design est probablement mauvais.

10. Les consommateurs restent découplés¶

Le Frontend et les adapters consomment des projections ou contrats de lecture. Ils ne reconstruisent pas la vérité métier à partir des tables internes.

Comment vérifier ces invariants avant une évolution¶

Avant tout changement Database, répondre au minimum à ces questions :

Quelle famille de données est concernée ?
Cette structure est-elle source, intermédiaire, métier, projection ou technique ?
Qui a le droit de l'écrire ?
Qui a le droit de la lire ?
Peut-elle être reconstruite ?
Le changement modifie-t-il un contrat de lecture ?
Les statuts unknown, ambiguous et conflict restent-ils explicitement représentables ?
Le rejeu avec les mêmes entrées reste-t-il déterministe ?
Existe-t-il un rollback ou une stratégie de récupération ?
Un audit indépendant permet-il de vérifier le résultat ?

Violations typiques¶

Écriture directe dans une projection¶

C'est une violation si elle contourne le Builder et le Write Service prévus.

SQL métier dans un renderer¶

Le Frontend ne doit pas décider de l'identité, du meilleur candidat ou d'un conflit à partir de requêtes ad hoc.

Cache utilisé comme vérité¶

Un cache est dérivé et reconstruisible. Il ne doit pas devenir la seule copie d'une décision métier.

Valeur manuelle impossible à reconstruire¶

Une correction manuelle non traçable casse le déterminisme et rend les audits futurs peu fiables.

Mutation pendant un audit¶

Un audit qui écrit mélange observation et action. Les deux étapes doivent être séparées.

Dépendance à un préfixe SQL codé en dur¶

Le Runtime actuellement documenté utilise wp_3888956, mais ce préfixe est un contexte d'environnement, pas un invariant architectural.

Les accès doivent utiliser les mécanismes de résolution de préfixe prévus par l'environnement lorsque cela s'applique.

Reconstruction et reprise¶

Une reconstruction sûre suit la logique :

état amont vérifié
→ Builder déterministe
→ Write Service explicite
→ compteurs réconciliés
→ audit de validation

Pour la famille Product Models actuellement documentée :

Product Models
→ Variants
→ Specifications
→ Gallery

Cet ordre est un contrat architectural documenté ; la présence exacte des services et commandes doit être vérifiée dans le code et le Runtime avant exécution.

Tests attendus¶

Les changements Database significatifs doivent couvrir :

déterminisme ;
idempotence des writes ;
réconciliation des compteurs ;
absence d'écriture dans les Read Services ;
conservation des statuts métier explicites ;
reprise après interruption ;
compatibilité des projections ;
comportement sur données manquantes, ambiguës ou conflictuelles.

Checklist de revue¶

Une évolution Database est suspecte si elle nécessite :

un UPDATE manuel récurrent ;
un calcul métier dans SQL uniquement ;
un renderer qui connaît les tables internes ;
une projection impossible à reconstruire ;
une écriture déclenchée au bootstrap ;
une suppression d'état unknown ou conflict sans nouvelle preuve métier ;
une dépendance à une valeur d'environnement codée en dur.