Présentation des services de lecture¶

Statut¶

Document canonique de la couche de lecture.

À quoi servent les Read Services ?¶

Les Read Services sont les outils qui permettent d'observer, mesurer, comparer et expliquer l'état de CMonChoix sans modifier les données.

Pour une personne qui reprend le projet, c'est une notion essentielle : lorsqu'on ne comprend pas encore parfaitement un problème, on commence par lire et auditer. On n'écrit pas dans la base pour « voir ce que ça donne ».

On peut les résumer ainsi :

Données existantes
      ↓
Read Service
      ↓
Observation / Audit / Comparaison / Rapport
      ↓
Aucune mutation

Le principe directeur est simple : comprendre avant de corriger.

Pourquoi cette couche existe¶

Sans séparation claire, une commande présentée comme un diagnostic pourrait finir par modifier silencieusement une projection ou une identité. Ce serait dangereux, car on ne saurait plus si les données observées sont celles du problème initial ou celles déjà modifiées par l'outil de diagnostic.

Les Read Services garantissent donc une frontière stricte entre :

observer l'état ;
simuler un résultat possible ;
modifier réellement la production.

La modification appartient aux Write Services, pas aux Read Services.

Ce qu'un Read Service peut faire¶

Un Read Service peut notamment :

lire les données persistées ;
lire les projections ;
calculer des indicateurs ;
détecter des anomalies ;
comparer deux états ;
produire des diagnostics et codes de raison ;
générer un rapport exploitable par la CLI ou les tests ;
simuler un résultat sans l'enregistrer.

Ce qu'il ne doit jamais faire¶

Un Read Service ne doit jamais :

exécuter un INSERT, UPDATE, DELETE ou une migration ;
appeler un Write Service ;
lancer ou reprendre une synchronisation ;
modifier une identité produit ;
modifier une offre ;
modifier une projection ;
corriger automatiquement une anomalie ;
cacher une mutation derrière une commande appelée « audit » ou « check ».

Si une commande prétend seulement analyser mais modifie les données, la frontière d'architecture est cassée.

Où se placent les Read Services ?¶

Domain Core / Projections / Ports de lecture
                   ↓
             Read Services
                   ↓
       CLI / Rapports / Audits / Tests

La CLI peut appeler un Read Service, mais elle ne doit pas recopier sa logique. Elle doit rester un adaptateur mince qui :

lit les arguments ;
les valide ;
appelle le service ;
affiche le résultat.

Les principales familles de services de lecture¶

Audits¶

Un audit répond à une question précise sur l'état actuel.

Exemples :

combien de produits sont en conflit ?
combien de lignes ont une image incohérente ?
combien de produits n'ont pas pu être résolus ?

Un audit doit expliquer ses résultats, pas simplement donner un nombre.

Comparaisons¶

Une comparaison confronte deux états ou deux stratégies.

Exemples :

ancienne règle contre nouvelle règle ;
projection avant reconstruction contre projection après reconstruction ;
ancien Resolver contre nouvelle stratégie de résolution.

Simulations¶

Une simulation répond à la question : « Que se passerait-il si cette règle était appliquée ? »

Elle peut produire un résultat alternatif, mais elle ne doit rien enregistrer.

C'est particulièrement utile avant une migration ou une correction importante.

Dumps¶

Un dump affiche des cas détaillés destinés à une revue humaine.

Il sert par exemple à examiner quelques produits ambigus avec toutes leurs preuves et leur décision actuelle.

Un dump doit rester déterministe et traçable jusqu'aux données sources.

Rapports de validation¶

Un rapport de validation rassemble les métriques nécessaires pour décider si une évolution est acceptable.

Il peut conclure par exemple par :

PASS : critères respectés ;
WARN : situation acceptable mais nécessitant attention ;
FAIL : critère bloquant non respecté.

Ces statuts doivent correspondre à des règles documentées et non à une impression manuelle.

Comment lire les métriques¶

Un résultat industriel doit autant que possible distinguer :

scanned : éléments parcourus ;
eligible : éléments réellement concernés par le contrôle ;
checked : éléments effectivement évalués ;
skipped : éléments ignorés pour une raison explicite ;
failed : erreurs techniques ;
résultats métier comme resolved, unknown, ambiguous, conflict, matched ou mismatched selon le service.

Ces compteurs doivent pouvoir être réconciliés.

Par exemple, si 1 000 lignes sont parcourues, le rapport doit permettre de comprendre ce qu'il est advenu de ces 1 000 lignes au lieu d'afficher seulement « 900 OK ».

Reproductibilité¶

Avec les mêmes :

données ;
paramètres ;
version des règles ;
période analysée ;

le même Read Service doit produire le même résultat.

C'est ce qui permet de comparer proprement un avant et un après.

Attention aux données historiques¶

Un audit ancien ne décrit pas forcément l'état actuel.

Si des données ont depuis été modifiées, supprimées ou reconstruites, il faut vérifier le contexte du snapshot ou du run avant de comparer deux rapports.

Une comparaison fiable demande que les deux populations comparées représentent réellement ce que l'on croit comparer.

Cas Media Quality¶

Media Quality respecte exactement la même philosophie.

En mode normal, le moteur :

collecte les preuves ;
classe les médias ;
explique les divergences ;
produit des métriques ;
ne remplace ni ne supprime une image.

Une correction éventuelle appartient à une opération d'écriture distincte et explicitement activée.

Une image incorrecte détectée par un audit n'est donc pas automatiquement supprimée.

Utilisation depuis WP-CLI¶

La forme opératoire canonique utilisée dans le projet est :

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

Avant d'exécuter une commande inconnue, vérifier son existence et son aide avec wp help ou une inspection structurée de wp cli cmd-dump --format=json.

Ne jamais conclure qu'une commande existe simplement parce qu'un ancien document la mentionne.

Comment diagnostiquer avec un Read Service¶

Lorsqu'un problème est observé :

Symptôme
   ↓
Identifier la donnée concernée
   ↓
Trouver l'audit ou le Read Service correspondant
   ↓
Limiter le périmètre si possible
   ↓
Analyser les statuts et raisons
   ↓
Formuler une hypothèse
   ↓
Simuler ou comparer
   ↓
Décider seulement ensuite s'il faut écrire

Cette séquence doit devenir un réflexe pour toute reprise du projet.

Tests attendus¶

Les Read Services doivent être protégés par des tests qui vérifient notamment :

qu'ils n'écrivent pas ;
qu'ils sont reproductibles ;
que leurs compteurs sont cohérents ;
que leurs résultats sont sérialisables ;
qu'ils n'introduisent pas de dépendance vers les Write Services ;
que les snapshots utilisés par les tests sont contrôlés.

Invariants¶

Un Read Service n'écrit jamais.
Une simulation n'est jamais présentée comme un état réellement persisté.
Un résultat significatif doit être explicable.
Les compteurs doivent pouvoir être réconciliés.
Une même entrée et une même version de règles donnent le même résultat.
Les erreurs, inconnues et ambiguïtés restent visibles.
La CLI expose les Read Services sans réimplémenter leur logique.
Une donnée historique altérée doit être régénérée avant une certification qui suppose un état propre.

Pour la personne qui reprend le projet¶

Si tu ne sais pas encore si une commande est dangereuse, considère qu'elle l'est tant que sa documentation n'a pas clairement établi qu'elle est read-only.

Commence toujours par un audit ou une lecture ciblée. Une bonne investigation réduit le besoin d'écriture ; une mauvaise investigation augmente le risque de corriger le mauvais composant.