Preview¶

Status: CONTRACT

À quoi sert un Preview Read Service ?¶

Un Preview est un Read Service qui montre à quoi ressemblerait un résultat ou une vue dérivée, sans modifier l'état persistant de CMonChoix.

Il répond à une question simple :

« Si je construis cette représentation avec les données actuelles, qu'est-ce qui sera affiché ou produit ? »

Le Preview est donc un outil d'observation et de préparation. Il ne doit jamais être confondu avec une écriture.

Données actuelles
      ↓
Preview Read Service
      ↓
Vue calculée en mémoire
      ↓
Inspection humaine / CLI / rapport

Pourquoi ce composant existe¶

Le Preview permet de vérifier une représentation avant qu'elle ne soit persistée, exposée au Frontend ou utilisée par un consommateur.

Il est utile notamment pour :

vérifier une future projection ;
inspecter un rendu logique avant rebuild ;
valider qu'un ensemble d'attributs est suffisamment complet ;
comprendre pourquoi une vue actuelle diffère du résultat attendu ;
préparer une comparaison avant/après.

Position dans CMonChoix¶

Le Preview se situe après les données métier résolues et avant toute écriture éventuelle :

Canonical Identity / données résolues
              ↓
        Preview Read Service
              ↓
        résultat en mémoire
              ↓
   validation / comparaison éventuelle
              ↓
   Write Service séparé si nécessaire

Le Preview ne remplace ni le Projection Builder ni le Write Service. Il peut réutiliser un Builder pur lorsqu'il existe, mais il ne doit jamais persister sa sortie.

Entrées¶

Un Preview doit recevoir explicitement les données et le contexte nécessaires, par exemple :

Canonical Identity ;
variantes ;
attributs déjà résolus ;
données de projection ;
version de schéma ;
filtres ;
run ou snapshot ;
configuration influençant la vue.

Les entrées doivent être suffisamment explicites pour reproduire le résultat.

Sortie¶

La sortie doit être sérialisable et adaptée au diagnostic.

Elle peut contenir :

le type de preview ;
la version du format ;
les identifiants stables ;
les champs calculés ;
les valeurs manquantes ;
les états unknown, ambiguous ou conflict ;
les warnings ;
les reason codes ;
les métadonnées de contexte.

Ce qu'un Preview ne doit jamais faire¶

Un Preview Read Service ne doit jamais :

écrire en base ;
appeler un Write Service ;
déclencher un rebuild persistant ;
modifier une projection existante ;
corriger une identité ;
masquer un champ incertain pour obtenir un rendu plus propre ;
dépendre d'un effet de bord Frontend pour calculer son résultat.

Le mot « preview » ne suffit pas à garantir la lecture seule : le comportement doit être vérifié dans l'implémentation et par tests.

Différence entre Preview, Simulation et Dump¶

Ces trois familles sont proches mais répondent à des questions différentes :

Dump       = quel est l'état interne actuel ?
Preview    = à quoi ressemble la vue calculée maintenant ?
Simulation = que se passerait-il avec une autre règle ou stratégie ?

Un Preview utilise normalement la règle actuelle. Une Simulation évalue volontairement une hypothèse différente.

Cas d'usage typiques¶

Prévisualiser une projection¶

Construire en mémoire la représentation qui serait persistée par un Write Service, puis l'inspecter sans écrire.

Prévisualiser une évolution de vue¶

Comparer le rendu logique actuel avec une nouvelle représentation calculée.

Diagnostiquer un champ absent¶

Vérifier si la valeur manque déjà dans les données métier ou si elle disparaît seulement dans la projection ou le Frontend.

Diagnostic¶

Si le Preview ne correspond pas au résultat attendu, vérifier dans cet ordre :

les données source sont-elles celles du bon run ou snapshot ?
l'identité ou les attributs sont-ils déjà résolus correctement ?
le Preview utilise-t-il la bonne version de schéma ou de Builder ?
une projection persistée plus ancienne est-elle comparée au calcul actuel ?
le Frontend applique-t-il ensuite une transformation supplémentaire ?
les états unknown, ambiguous et conflict sont-ils correctement conservés ?

Cette méthode évite d'accuser le Frontend lorsqu'une donnée manque déjà en amont.

Reproductibilité¶

Pour les mêmes entrées, la même configuration et la même version de code, un Preview doit produire le même résultat logique.

Tout tri doit être stable et toute valeur dépendant du temps ou d'un contexte externe doit être injectée explicitement.

Tests attendus¶

Un Preview important doit être couvert par :

tests read-only ;
tests de déterminisme ;
tests de sérialisation ;
tests de conservation des valeurs inconnues et ambiguës ;
tests garantissant qu'aucun writer n'est appelé ;
tests séparant le service du formatage CLI ou Frontend.

Invariants¶

Un Preview est read-only.
Il calcule une vue sans la persister.
Il n'invente pas les données manquantes.
Les états d'incertitude restent visibles.
Le résultat est reproductible.
Toute écriture éventuelle appartient à un Write Service distinct.
Le transport ou le Frontend ne doit pas porter la logique métier du Preview.