Invariants d'architecture¶
Status: NORMATIVE / CONTRACT
Un invariant est une règle qui doit rester vraie même si le code, les marchands, WordPress ou l'infrastructure changent. Sa violation est une régression d'architecture.
1. La Platform fonctionne sans WordPress¶
Le Core doit pouvoir exécuter les traitements métier sans charger WordPress.
WordPress -> src/ : autorisé
src/ -> WordPress : interdit
ABSPATH, fonctions wp_*, $wpdb, hooks et classes WordPress ne doivent pas être requis par Domain ou Application.
2. Toute responsabilité non spécifique à WordPress converge vers src/¶
Le plugin peut conserver du code métier historique uniquement comme état CURRENT/TRANSITIONAL pendant une migration certifiée.
Aucune nouvelle responsabilité métier ne doit être créée dans le plugin parce que son point d'entrée Runtime y existe encore.
3. Une vérité métier importante n'a qu'un propriétaire¶
Identité canonique, classification, variante, qualité, score, état d'offre et décisions de projection ne doivent pas être recalculés par plusieurs couches concurrentes.
4. Une observation marchande n'est pas une décision¶
Le feed fournit des observations et des preuves. Une catégorie, un titre, un EAN ou un attribut source ne devient pas automatiquement la vérité canonique.
5. Les états d'incertitude restent visibles¶
Les flux de résolution conservent lorsque pertinent : resolved, unknown, ambiguous, conflict.
Une absence de preuve ne devient pas un succès artificiel.
6. Le Domain Core reste générique¶
Il ne connaît ni WordPress, ni SQL concret, ni marchand, ni feed précis, ni verticale concrète, ni Frontend, ni Runtime.
7. Les règles marchands restent confinées¶
Une particularité Acer, Samsung ou d'un autre marchand ne doit pas être dispersée dans le moteur générique.
Elle appartient à un adapter/configuration/policy explicitement propriétaire. Le retrait d'un marchand ne doit pas imposer de modifier le Domain Core.
8. Les Vertical Modules restent isolés¶
Une verticale porte les connaissances d'une famille produit. Elle ne dépend pas directement d'une autre verticale et n'écrit pas en production.
9. Les Contracts restent neutres¶
Un contrat ne contient ni SQL, ni WordPress, ni orchestration Runtime, ni règle propre à un marchand ou une verticale concrète.
10. Un Read Service n'écrit jamais¶
Audit, simulation, comparaison, preview, dump et diagnostic restent read-only.
11. Toute mutation franchit une frontière explicite¶
Une écriture métier passe par un Write Service ou une frontière Application certifiée, avec périmètre, résultat et comportement d'échec explicites.
12. Le Runtime orchestre, il ne décide pas¶
Scheduling, locks, retries, batches et workers sont des responsabilités Runtime. Les décisions métier restent dans les couches propriétaires.
13. Les jobs de volume sont bornés et rejouables¶
Les traitements massifs doivent pouvoir être divisés en batches ou unités de travail bornées.
Un job critique doit autant que possible être idempotent, retryable, observable, checkpointable et rejouable.
14. Un marchand ne bloque pas les autres¶
Une erreur de téléchargement, parsing, mapping ou traitement d'un marchand ne doit pas immobiliser la synchronisation des autres marchands.
La concurrence et les quotas doivent permettre une isolation opérationnelle progressive.
15. L'incrémental est préféré au recalcul global inutile¶
Une modification locale doit cibler le périmètre réellement affecté lorsqu'il peut être déterminé de façon sûre.
Le full rebuild reste disponible comme mécanisme de convergence, certification et recovery.
Le résultat incrémental doit rester compatible avec le résultat canonique obtenu après reconstruction complète.
16. Une projection est dérivée et reconstruisible¶
Une projection ne résout pas une identité, ne masque pas un conflit et ne devient pas la vérité du Domain.
Le Frontend doit préférer ces représentations préparées aux calculs métier à la requête.
17. Le Frontend et WordPress consomment, ils ne reconstruisent pas¶
Une page ne doit pas reclassifier, résoudre l'identité, recalculer la qualité ou relire un feed brut pour s'afficher.
18. Cache et search ne sont pas des vérités durables¶
Redis et un moteur de recherche sont des mécanismes techniques ou des projections spécialisées. Leur perte ne doit pas entraîner la perte irréversible de la vérité métier durable.
19. Les décisions critiques sont déterministes et explicables¶
À entrées, configuration et version de règles identiques, la même décision doit être reproductible.
Elle expose lorsque pertinent statut, reason codes, preuves, version de règle et métadonnées d'audit.
20. L'observabilité fait partie du contrat opérationnel¶
Un run critique doit pouvoir être relié à son marchand, run, batch, job et périmètre de données.
Les métriques doivent permettre de distinguer succès, rejet métier, incertitude, retard et erreur technique.
21. La montée en charge ne réécrit pas le métier¶
Passer d'un VPS unique à plusieurs machines doit principalement déplacer ou multiplier Web, workers, DB, cache, recherche et observabilité.
Le Domain Core ne doit pas changer parce qu'un worker change de machine.
22. Les données de marché sont explicites¶
Pays, marché, monnaie, fiscalité, disponibilité et conditions de livraison ne doivent pas être déduits implicitement du site WordPress ou de la langue de la page.
23. Toute projection et tout index critique possède une voie de rebuild¶
La perte d'une donnée dérivée doit pouvoir être réparée depuis un état amont certifié.
24. Les sauvegardes doivent être restaurables¶
La présence d'un fichier de backup ou d'une réplica ne constitue pas à elle seule une certification de reprise.
Les procédures de restauration et recovery doivent être testables et documentées.
25. CURRENT n'est jamais TARGET par accident¶
Toute compatibilité ou dette historique doit être explicitement marquée CURRENT, TRANSITIONAL, HISTORICAL ou DEPRECATED et avoir une trajectoire de sortie lorsqu'elle contredit la cible.
26. Une règle critique doit être protégée automatiquement lorsque possible¶
Tests d'architecture, tests de contrats, guards, certifications Runtime et tests d'idempotence/replay doivent empêcher les régressions importantes.
Une convention seulement orale n'est pas un garde-fou industriel.
Vérification avant une modification sensible¶
- Identifier la responsabilité et son propriétaire.
- Vérifier le sens de dépendance.
- Déterminer si l'action lit ou écrit.
- Vérifier l'isolation marchand/verticale.
- Vérifier le comportement de retry/replay si le traitement est asynchrone.
- Vérifier le scope de refresh/projection.
- Prévoir métriques et reason codes.
- Vérifier que WordPress n'est pas introduit dans le Core.
- Prévoir la récupération ou le rollback lorsque nécessaire.
- Mettre à jour documentation et tests dans le même chantier.