Présentation des Read Services¶

Statut¶

Document canonique de la couche de lecture.

Rôle¶

Les Read Services observent l'état de la Platform et produisent des résultats exploitables sans modifier les données, déclencher un run ni exécuter une écriture de projection.

Ils constituent la couche commune utilisée par les audits, comparaisons, simulations, dumps et rapports de validation.

Sources persistées / Domain Core / Projections
                    ↓
              Read Services
                    ↓
       Audits · Comparaisons · Rapports

Leur principe directeur est simple : mesurer et expliquer avant de modifier.

Contrat read-only¶

Un Read Service peut :

lire les données persistées et les projections ;
calculer des indicateurs ;
comparer plusieurs états ;
produire des raisons, diagnostics et preuves ;
sérialiser ses résultats pour la CLI, les tests ou les rapports.

Il ne doit jamais :

exécuter un INSERT, UPDATE, DELETE, DDL ou une migration ;
appeler un Write Service ;
lancer ou reprendre une synchronisation ;
modifier une identité, une offre ou une projection ;
masquer une écriture derrière une commande présentée comme un audit ;
charger le frontend pour fonctionner.

Une simulation qui calcule un résultat alternatif reste read-only tant qu'elle ne persiste rien.

Position dans l'architecture¶

Les Read Services peuvent consommer :

les modèles et contrats du Domain Core ;
des ports de lecture ;
des projections persistées ;
les règles d'une verticale lorsque l'analyse est explicitement ciblée ;
les moteurs d'évidence et de scoring en mode sans mutation.

Ils ne dépendent pas des adapters HTTP, Admin ou Frontend. La CLI peut les exposer, mais elle reste un adapter mince : parsing, validation, délégation et formatage.

Familles principales¶

Audits¶

Ils répondent à une question précise et expliquent l'état observé : conflits, qualité, couverture, résolution, projection ou santé opérationnelle.

Comparaisons¶

Ils confrontent deux états compatibles : ancienne et nouvelle implémentation, avant et après une évolution, projection reconstruite et état persistant, ou deux stratégies de résolution.

Simulations¶

Elles évaluent une hypothèse sans écriture. Les résultats simulés doivent être clairement distingués de l'état réellement persisté.

Dumps¶

Ils exposent des cas détaillés pour la revue humaine. Un dump doit rester déterministe, filtrable et traçable jusqu'à ses données sources.

Rapports de validation¶

Ils réconcilient les métriques, documentent les seuils et concluent explicitement par un état tel que PASS, WARN ou FAIL.

Forme d'un résultat¶

Un résultat industriel doit être sérialisable et contenir, selon le cas :

l'identifiant du run ou du snapshot analysé ;
le périmètre et les filtres ;
les volumes scanned, eligible, checked, skipped et failed ;
les résultats métier et leurs raisons ;
les inconnues et ambiguïtés ;
les seuils de validation ;
les erreurs techniques ;
la version de règle ou de moteur utilisée.

Les compteurs doivent pouvoir être réconciliés. Une métrique globale sans ventilation explicable n'est pas suffisante pour certifier un comportement.

Reproductibilité¶

Un Read Service doit produire le même résultat pour :

les mêmes données ;
les mêmes paramètres ;
la même version de règles ;
le même périmètre temporel.

Les commandes doivent donc exposer clairement les paramètres qui influencent le résultat : run, feed, verticale, limite, offset, mode, seuil ou format.

Les audits historiques ne doivent pas être interprétés comme l'état courant lorsque les données ont été modifiées depuis. Une projection ou un échantillon doit être régénéré avant toute comparaison qui suppose un état propre.

Media Quality¶

Media Quality suit le même contrat.

Le moteur :

collecte des évidences ;
classe les cas en correspondance, divergence, inconnu ou ambigu ;
expose les raisons et niveaux de confiance ;
fonctionne par défaut en mode audit-first ;
ne vide pas image_norm ;
ne remplace une image que lorsqu'un mode de mutation explicite est activé et que la confiance requise est atteinte.

Les métriques Media Quality doivent distinguer au minimum les lignes scannées, éligibles, vérifiées, correspondantes, divergentes, inconnues, ambiguës, remplacements trouvés, mutations réalisées et erreurs.

Intégration CLI¶

La forme opératoire canonique est :

docker compose exec platform-worker wp --allow-root --path=/var/www/html <commande>

La présence d'une commande doit être vérifiée par wp help ou par analyse structurée de wp cli cmd-dump --format=json. Un simple grep sur le dump JSON ne constitue pas une preuve fiable.

Les commandes d'audit doivent :

annoncer explicitement qu'elles sont read-only ;
fournir un format humain et, lorsque nécessaire, un format structuré ;
retourner un code non nul en cas d'échec technique ou de seuil de validation non respecté ;
ne pas charger le Pipeline complet lorsqu'un port de lecture ciblé suffit.

Tests attendus¶

La couche doit être couverte par :

des tests unitaires des calculs et classifications ;
des tests de reproductibilité ;
des tests garantissant l'absence d'écriture ;
des tests de réconciliation des compteurs ;
des tests de sérialisation ;
des tests d'architecture interdisant les dépendances vers les adapters et Write Services ;
des tests d'intégration sur des snapshots contrôlés.

Invariants¶

Un Read Service n'écrit jamais.
Une simulation n'est jamais présentée comme un état persisté.
Chaque résultat significatif est explicable par des raisons ou évidences.
Les métriques sont réconciliables avec le volume analysé.
Une même entrée et une même version de règles produisent la même sortie.
Les erreurs et inconnues restent visibles ; elles ne sont pas converties artificiellement en succès.
La CLI expose les Read Services sans réimplémenter leur logique.
Les données historiques altérées sont régénérées avant certification.