Présentation des Write Services¶

Status: CONTRACT

Rôle¶

Les Write Services sont la frontière applicative des opérations qui modifient durablement l'état de CMonChoix Platform.

Ils appliquent une décision déjà validée. Ils ne réalisent ni l'audit, ni la comparaison, ni la décision métier qui justifie l'écriture.

Read Service / Audit
        ↓
Simulation
        ↓
Validation explicite
        ↓
Write Service
        ↓
Persistance contrôlée

La séparation lecture/écriture est stricte : une commande ou un service présenté comme read-only ne doit jamais déléguer vers un Write Service.

Responsabilités¶

Un Write Service peut notamment :

persister une projection ;
reconstruire une structure dérivée ;
appliquer une correction validée ;
exécuter une migration ou une maintenance contrôlée ;
centraliser une écriture auparavant dispersée dans un adapter ou un orchestrateur ;
exposer un résultat d'exécution explicite et mesurable.

Il doit définir avant exécution :

le périmètre concerné ;
la source de la décision ;
les préconditions ;
les effets attendus ;
les mécanismes de reprise ou de rollback ;
les métriques de sortie.

Frontières¶

Un Write Service ne doit jamais :

décider si une identité est correcte ;
inventer une règle métier ;
masquer un conflit ;
effectuer un audit sous couvert d'une écriture ;
lire directement les paramètres HTTP, CLI ou admin ;
produire du HTML, des headers, des redirections ou un format de transport ;
contourner les services de projection ou les contrats applicatifs existants ;
écrire implicitement lors du chargement d'un bootstrap.

Les adapters HTTP, admin et CLI valident la requête, délèguent au service, puis traduisent son résultat. Ils ne contiennent pas l'écriture métier ou SQL.

Écritures de projection¶

Les projections sont des données dérivées et reconstruisibles. Leur persistance doit passer par les services dédiés documentés par l'architecture du plugin.

La famille actuellement certifiée comprend notamment :

CCX_OfferProjectionWriteService pour la projection des offres normalisées ;
CCX_ProductModelProjectionWriteService pour les Product Models ;
CCX_ProductVariantProjectionWriteService pour les variantes ;
CCX_ProductSpecificationProjectionWriteService pour les spécifications ;
CCX_ProductGalleryProjectionWriteService pour les galeries ;
CCX_ProductModelRebuildOrchestrator pour l'ordre canonique des reconstructions multiples.

Ordre canonique d'une reconstruction complète de cette famille :

Product Models
    ↓
Variants
    ↓
Specifications
    ↓
Gallery

Un point d'entrée ou un orchestrateur ne doit pas appeler directement un writer SQL legacy lorsqu'un Write Service dédié existe.

Media Quality¶

Media Quality fonctionne actuellement en politique audit-first.

Par défaut :

le moteur collecte des évidences ;
il produit des décisions et des métriques ;
il ne vide pas image_norm ;
il ne remplace pas une image ;
il n'exécute aucune mutation implicite.

Une future mutation Media Quality devra être exposée comme un Write Service distinct, activé explicitement et séparé du moteur d'audit. Elle devra disposer de seuils de confiance documentés, d'un mode dry-run, d'une traçabilité par offre et d'une preuve qu'aucune image valide n'est supprimée par défaut.

Contrat d'exécution¶

Chaque Write Service doit retourner un résultat structuré contenant, selon l'opération :

le statut global ;
le nombre de lignes examinées ;
le nombre de lignes modifiées ;
le nombre de lignes ignorées ;
le nombre d'échecs ;
les raisons d'échec ou d'ignorance ;
l'identifiant du run, du batch ou de l'opération ;
la durée ;
les avertissements.

Les compteurs doivent être réconciliables. Par exemple :

examined = changed + unchanged + skipped + failed

Lorsqu'une opération fonctionne par lots, chaque lot doit être identifiable et reprenable sans dupliquer les effets déjà appliqués.

Sécurité opérationnelle¶

Toute écriture potentiellement large doit proposer autant que possible :

un mode dry-run ou une simulation équivalente ;
un filtre explicite par run, feed, verticale ou identifiant ;
une limite de volume ;
une confirmation opérateur pour les opérations sensibles ;
une stratégie de reprise ;
une stratégie de rollback ou une justification documentée de son absence.

Une commande CLI doit annoncer clairement qu'elle écrit. Son nom, son aide et sa sortie ne doivent pas laisser croire à un audit read-only.

Idempotence et reprise¶

Une opération rejouée avec les mêmes paramètres ne doit pas produire de duplication ni dégrader un état déjà valide.

Le service doit distinguer :

une ligne réellement modifiée ;
une ligne déjà conforme ;
une ligne ignorée par politique ;
une ligne en échec.

Pour les runs et projections, les identifiants de run, les offsets, les hashes ou les clés métier servent à rendre la reprise explicite et vérifiable.

Traçabilité¶

Toute écriture doit pouvoir être reliée à :

l'adapter ou l'orchestrateur demandeur ;
l'identité de l'opération ;
ses paramètres ;
la version du code ;
les données ciblées ;
les compteurs avant/après ;
les erreurs rencontrées ;
la validation ou le rapport ayant autorisé l'opération lorsque cela s'applique.

Les logs ne remplacent pas le résultat structuré du service. Les deux sont complémentaires.

Tests attendus¶

Un Write Service doit être couvert par des tests vérifiant au minimum :

que les préconditions sont appliquées ;
que le périmètre d'écriture est respecté ;
que les adapters restent minces ;
que le mode dry-run n'écrit rien lorsqu'il existe ;
que le rejeu est idempotent ;
que les compteurs se réconcilient ;
que les erreurs partielles sont visibles ;
que les invariants des projections sont préservés ;
que les composants audit-first, dont Media Quality, ne mutent pas par défaut.

Invariants¶

Écriture explicite — aucune mutation ne se produit par simple chargement d'un fichier ou d'un bootstrap.
Décision séparée — le Write Service applique une décision ; il ne la fabrique pas.
Périmètre borné — les données ciblées sont identifiables avant l'exécution.
Traçabilité — toute écriture est attribuable, mesurable et explicable.
Idempotence — le rejeu ne duplique pas les effets.
Reprise contrôlée — une interruption ne transforme pas un succès partiel en état opaque.
Transport neutre — aucun détail HTTP, CLI, admin ou HTML dans le service.
Projection reconstruisible — une projection n'est jamais traitée comme vérité métier.
Audit-first préservé — Media Quality n'écrit pas tant qu'une politique de mutation distincte n'est pas explicitement activée.