Dépendances de la couche Database¶

Status: CONTRACT

Rôle¶

Cette page décrit qui peut dépendre de la Database, par quelle frontière, et quelles dépendances doivent rester interdites.

La Database est un mécanisme de persistance. Elle ne doit pas devenir un raccourci universel permettant à chaque couche d'interroger ou de modifier n'importe quelle table.

Principe général¶

Les dépendances doivent rester explicites :

Domain Core / Vertical Modules
            ↓
Application / Builders / Services
            ↓
Repositories / Readers / Write Services
            ↓
Infrastructure SQL
            ↓
Database

Les consommateurs de lecture passent de préférence par des contrats de lecture ou des projections, et non par un couplage direct au schéma interne.

Domain Core¶

Le Domain Core ne dépend pas directement de SQL, de $wpdb, d'un préfixe de table ni d'une technologie de stockage.

Il manipule des concepts métier, Value Objects, entités, politiques et contrats.

Si une règle Domain Core exige une requête SQL précise pour fonctionner, la frontière est probablement mal placée.

Vertical Modules¶

Les Vertical Modules peuvent fournir des règles spécialisées, mais ne doivent pas transformer le schéma Database en extension implicite de leur logique métier.

Une verticale peut nécessiter des données spécifiques ; cette nécessité doit être modélisée par un contrat clair et non par des requêtes dispersées dans le code métier.

Pipeline¶

Le Pipeline lit et écrit les structures dont il est responsable via les composants prévus.

Il peut produire :

des états de Stage ;
des données normalisées ou enrichies ;
des entrées utilisées par les composants métier ;
des états techniques de traitement.

Il ne doit pas utiliser une projection Frontend comme source de vérité pour reconstruire son propre amont.

Read Services¶

Les Read Services consultent la Database pour observer, auditer, comparer ou produire des rapports.

Ils sont strictement read-only selon leur contrat.

Une requête utilisée par un Read Service peut être techniquement complexe, mais elle ne doit pas produire d'effet persistant.

Write Services¶

Les Write Services constituent la frontière explicite des mutations durables applicatives.

Ils peuvent notamment persister ou reconstruire des projections, appliquer un backfill, une migration ou une réparation validée.

Ils doivent rester séparés de la décision métier qui justifie l'écriture.

Runtime¶

Le Runtime orchestre l'exécution et peut déclencher des services qui lisent ou écrivent.

Il ne doit pas devenir propriétaire des règles métier ni contenir des corrections SQL ad hoc.

Le fait qu'un composant s'exécute dans le Runtime ne lui donne pas automatiquement le droit de modifier n'importe quelle structure.

Frontend¶

Le Frontend consomme des projections ou des Read Models.

Il ne doit pas :

lire directement le Stage ;
recalculer la Canonical Identity ;
résoudre unknown, ambiguous ou conflict ;
écrire dans des tables métier ou de projection pendant le rendu public.

Le SQL de compatibilité encore nécessaire appartient à un Reader ou Adapter explicitement identifié, pas au composant de rendu.

Adapters WordPress / CLI / HTTP¶

Les Adapters traduisent un transport ou un contexte vers un service applicatif.

Ils ne doivent pas contenir :

de logique métier ;
de requêtes SQL métier dispersées ;
de mutation implicite ;
de reconstruction de projection inline.

Les détails WordPress, HTTP et WP-CLI restent confinés à la couche Adapter.

Infrastructure SQL¶

L'Infrastructure est la couche où les détails techniques de persistance peuvent exister :

SQL ;
$wpdb ;
tables ;
transactions ;
locks ;
stores techniques.

Cette couche traduit les contrats applicatifs vers la technologie de stockage. Elle ne décide pas si une identité est correcte.

Dépendances interdites¶

Domain Core → SQL concret¶

Interdit : le métier devient dépendant de l'infrastructure.

Frontend → Stage ou tables internes¶

Interdit : le rendu contourne le contrat de projection.

Read Service → Write Service¶

Interdit dans un flux présenté comme read-only.

Projection → source métier¶

Interdit : une projection dérivée ne doit pas devenir l'entrée autoritaire du Pipeline ou du Domain Core.

Adapter → règle métier¶

Interdit : l'Adapter doit déléguer.

Database → orchestration¶

La base ne doit pas devenir un bus implicite dont des flags ou lignes arbitraires remplacent des contrats applicatifs explicites.

Attention aux schémas trop simplifiés¶

Un schéma tel que :

Pipeline → Database → Frontend

est utile pédagogiquement mais incomplet.

Dans le code réel, les frontières importantes sont plutôt :

ProductRepository / Projection Reader / Write Service
                     ↓
               Adapter SQL
                     ↓
                  Database

C'est cette séparation qui permet de changer une implémentation de stockage sans déplacer les règles métier.

Comment diagnostiquer une dépendance douteuse¶

Lorsqu'un fichier accède directement à SQL, demander :

À quelle couche appartient ce fichier ?
Est-ce un Reader, Repository, Write Service ou Adapter SQL légitime ?
Le même accès apparaît-il dans plusieurs couches ?
Le Frontend ou un Adapter transporte-t-il une décision métier ?
L'accès écrit-il alors que le flux est annoncé read-only ?
Le code dépend-il d'un nom de table ou d'un préfixe qui devrait être encapsulé ?
Existe-t-il déjà un contrat canonique pour cette lecture ou écriture ?

Si la réponse révèle un contournement, corriger la frontière plutôt que copier la requête ailleurs.

Préfixe SQL¶

Le Runtime actuellement documenté utilise le préfixe wp_3888956.

Ce préfixe décrit un environnement actuel ; ce n'est pas une dépendance architecturale autorisée à coder en dur partout.

Les composants doivent utiliser les mécanismes de résolution de table prévus par leur infrastructure.

Tests attendus¶

Les frontières Database doivent être protégées par des tests ou vérifications couvrant :

absence de SQL dans le Domain Core ;
absence de writes dans les Read Services ;
absence de SQL direct dans les renderers publics ;
délégation correcte des Adapters ;
stabilité des contrats de Repository/Reader ;
idempotence et périmètre des Write Services.

Invariants¶

Le Domain Core reste indépendant du stockage.
Les Read Services restent read-only.
Les Write Services portent les mutations explicites.
Le Frontend consomme des projections, pas les tables internes.
Les Adapters traduisent et délèguent.
Les détails SQL restent confinés à l'Infrastructure ou aux adapters de persistance prévus.
Aucune projection dérivée ne devient source métier.
Les valeurs d'environnement ne deviennent pas des constantes architecturales.