Guide des Vertical Modules¶

Ce document est le point d'entrée opérationnel pour concevoir, auditer et intégrer une verticale dans CMonChoix Platform.

Les règles d'implémentation détaillées restent versionnées au plus près du code dans le plugin canonique :

plugins/ccx-feeds-industrial/includes/platform/docs/VERTICAL_DEVELOPMENT_GUIDE.md

Objectif¶

Une verticale encapsule uniquement la connaissance métier propre à une famille de produits.

Elle complète les mécanismes génériques de la Platform sans :

modifier le Domain Core ;
remplacer le Resolver ;
écrire directement dans les projections ;
contourner les Contracts ;
introduire une dépendance vers une autre verticale.

Parcours de lecture recommandé¶

lire l'overview pour comprendre les frontières architecturales ;
lire la page de la verticale concernée ;
consulter le guide technique dans le plugin canonique ;
vérifier les Contracts consommés ;
examiner les audits, simulations et rapports de validation associés.

Cycle d'industrialisation¶

Observation des données
        ↓
Modélisation des attributs métier
        ↓
Règles locales déterministes
        ↓
Read Services et audits
        ↓
Simulation sans écriture
        ↓
Validation des KPI et invariants
        ↓
Intégration contrôlée au runtime

Une verticale ne doit pas être branchée au runtime normal avant que ses cas ambigus, inconnus et conflictuels soient mesurés.

Contrat minimal d'une verticale¶

Une verticale industrialisée doit documenter :

son périmètre produit ;
ses attributs métier ;
ses sources de preuve ;
ses règles de normalisation ;
ses règles de conflit ;
ses statuts et codes de raison ;
ses invariants ;
ses métriques d'audit ;
ses jeux de tests ;
ses limites connues.

Les résultats doivent rester déterministes et explicables. À données et version de règles identiques, deux exécutions doivent produire la même décision.

Statuts attendus¶

Les Vertical Modules alimentent les contrats communs avec des états explicites :

Statut	Signification
`resolved`	les preuves permettent une décision stable
`unknown`	les preuves disponibles sont insuffisantes
`ambiguous`	plusieurs décisions restent plausibles
`conflict`	des preuves incompatibles empêchent la résolution

Une verticale ne doit jamais convertir silencieusement un cas unknown, ambiguous ou conflict en valeur résolue.

Séparation lecture / écriture¶

Les règles métier peuvent être exécutées par les Read Services pour produire :

audits ;
simulations ;
rapports de validation ;
métriques de couverture ;
exemples de décisions et contre-exemples.

Toute écriture persistante appartient aux Write Services ou au pipeline certifié. Une règle de verticale ne doit pas muter directement les tables métier ou les projections.

Media Quality¶

Les règles Media Quality rattachées à une verticale suivent le même modèle :

audit-first ;
preuves et codes de raison conservés ;
aucune mutation implicite ;
correction uniquement via un flux d'écriture explicite, traçable et réversible ;
absence de remplacement fiable conservée comme état non résolu.

Un média jugé incohérent ne doit pas être supprimé ou remplacé automatiquement sans candidat certifié et politique d'écriture explicite.

Critères d'intégration¶

Avant intégration, la verticale doit démontrer :

l'absence de dépendance vers une autre verticale ;
la compatibilité avec les Contracts communs ;
la stabilité des sorties ;
la couverture des conflits importants ;
l'observabilité des décisions ;
la non-régression sur les verticales existantes ;
la possibilité de rejouer les audits sans effet de bord.

Extraction vers le Core¶

Une règle locale ne devient générique que lorsqu'un besoin commun est prouvé sur plusieurs verticales.

L'extraction doit conserver :

une sémantique indépendante du métier d'origine ;
des entrées et sorties stables ;
des tests couvrant plusieurs verticales ;
l'absence de vocabulaire ou d'exception propre à une famille produit.

Une similarité superficielle ne suffit pas à déplacer une règle vers le Domain Core.