Frontend Preview¶

Status: CURRENT

Objet¶

Le Frontend Preview est l'environnement dédié au développement et à la validation visuelle du frontend public de CMonChoix Platform.

Il permet de modifier les sources frontend dans un worktree Git isolé, de les servir dans un WordPress preview dédié et de les contrôler dans un navigateur avant toute promotion vers la production.

Le preview n'est jamais une autorité de production.

Topologie¶

worktree frontend-preview-v1
        ↓
sources montées read-only
        ↓
WordPress preview
        ↓
Nginx preview
        ↓
127.0.0.1:8082 sur le VPS
        ↓
SSH / VS Code port forwarding
        ↓
http://localhost:8082

Worktree canonique¶

Le worktree du preview est :

/mnt/data/cmonchoix-worktrees/frontend-preview-v1

Le checkout principal reste :

/mnt/data/cmonchoix-platform

Les évolutions frontend du preview ne doivent pas être réalisées directement dans le checkout principal.

Autorité des sources¶

Le fichier d'environnement runtime du preview est :

/mnt/data/cmonchoix-preview/.env

La source active doit être :

CCX_PREVIEW_SOURCE_ROOT=/mnt/data/cmonchoix-worktrees/frontend-preview-v1

Le worktree historique /mnt/data/cmonchoix-worktrees/frontend-review n'est pas l'autorité du Frontend Preview courant.

Infrastructure et état mutable¶

L'infrastructure preview est située sous :

/mnt/data/cmonchoix-worktrees/frontend-preview-v1/docker/preview/

Elle comprend actuellement docker-compose.yml, env.example, nginx.conf et wp-config.php.

Au moment de cette documentation, docker/preview/ est présent localement mais n'est pas suivi par Git. Un nouveau clone ou worktree ne doit donc pas supposer que cette infrastructure existe déjà.

L'état mutable du preview est séparé du worktree :

/mnt/data/cmonchoix-preview

Il contient notamment le fichier .env runtime et les uploads du preview. Les secrets de .env ne doivent jamais être ajoutés à Git.

La base MariaDB du preview utilise un stockage dédié et ne doit jamais utiliser la base de production comme stockage actif.

Services Docker¶

Le projet Compose du preview est :

cmonchoix-preview

Services attendus :

cmonchoix-preview-db-1
cmonchoix-preview-web-1
cmonchoix-preview-gateway-1

Rôles :

db : MariaDB dédiée au preview ;
web : WordPress / Apache servant le frontend ;
gateway : Nginx d'entrée du preview.

Le service DB ne doit pas être recréé pour une simple modification frontend.

Bind mounts frontend¶

Le conteneur Web consomme directement les sources du worktree preview via des bind mounts en lecture seule :

plugins/ccx-feeds-industrial
  -> /var/www/html/wp-content/plugins/ccx-feeds-industrial

wordpress/wp-content/themes/ccx
  -> /var/www/html/wp-content/themes/ccx

wordpress/wp-content/mu-plugins
  -> /var/www/html/wp-content/mu-plugins

src
  -> /opt/cmonchoix-platform/src

vendor
  -> /opt/cmonchoix-platform/vendor

Les uploads utilisent l'état mutable du preview :

/mnt/data/cmonchoix-preview/uploads
  -> /var/www/html/wp-content/uploads

Une modification CSS, PHP ou thème dans le worktree est donc consommée directement par le runtime preview, sans copie manuelle dans le conteneur.

Vendor et autoload Composer¶

Le conteneur Web monte également le répertoire vendor/ du worktree preview :

/mnt/data/cmonchoix-worktrees/frontend-preview-v1/vendor
  -> /opt/cmonchoix-platform/vendor

vendor/ n'est pas versionné par Git. Un worktree nouvellement créé peut donc ne pas contenir les dépendances Composer matérialisées.

Si Docker monte un chemin vendor/ absent, un répertoire vide peut être créé sur l'hôte. Le frontend peut alors échouer avec des erreurs d'autoload alors que les classes existent correctement sous src/.

Avant d'utiliser le preview, vérifier au minimum :

test -f /mnt/data/cmonchoix-worktrees/frontend-preview-v1/vendor/autoload.php

Les dépendances doivent correspondre au composer.lock du worktree.

Si un vendor/ provenant d'un autre worktree est réutilisé temporairement, vérifier d'abord l'identité des composer.lock.

La solution durable reste une matérialisation déterministe des dépendances correspondant au lock courant.

Isolation WordPress¶

Le preview utilise son propre wp-config.php.

Les invariants attendus sont notamment :

DISALLOW_FILE_MODS=true
AUTOMATIC_UPDATER_DISABLED=true
DISABLE_WP_CRON=true
WP_HTTP_BLOCK_EXTERNAL=true
WP_ENVIRONMENT_TYPE=staging

Conséquences :

aucune mise à jour WordPress automatique ;
aucune modification de plugin ou thème depuis WordPress ;
aucun cron WordPress automatique ;
les appels HTTP sortants initiés par WordPress sont bloqués ;
le preview ne doit pas déclencher les synchronisations marchands de production.

Les ressources externes chargées directement par le navigateur ne sont pas concernées par WP_HTTP_BLOCK_EXTERNAL.

Vérification de la configuration Compose¶

Avant toute recréation de conteneur, vérifier la configuration Compose réellement résolue :

docker compose \
  --env-file /mnt/data/cmonchoix-preview/.env \
  -f /mnt/data/cmonchoix-worktrees/frontend-preview-v1/docker/preview/docker-compose.yml \
  config

Les bind mounts frontend doivent tous provenir de :

/mnt/data/cmonchoix-worktrees/frontend-preview-v1

Une configuration qui pointe vers un autre worktree doit être considérée comme non alignée.

Le gateway doit rester publié uniquement sur :

127.0.0.1:8082

Recréation des services preview¶

Une modification CSS, PHP ou thème montée par bind mount est généralement visible sans rebuild d'image et sans recréation de la DB.

Une recréation du Web est nécessaire notamment lorsqu'un mount ou une variable Compose structurante change.

La recréation doit cibler uniquement le projet cmonchoix-preview.

La DB preview ne doit pas être recréée pour une simple évolution frontend.

Lorsqu'un nouveau conteneur Web reçoit une nouvelle identité réseau, le gateway peut également être recréé afin d'éviter une résolution Nginx obsolète.

Ne jamais utiliser les commandes du preview contre le projet Compose de production.

Validation HTTP¶

Un code HTTP 200 ne suffit pas à prouver que le frontend est sain.

WordPress peut afficher une erreur PHP dans une réponse HTTP 200.

Après une évolution runtime, vérifier au minimum :

HTTP 200
Content-Type text/html
absence de "Fatal error"
absence de "Uncaught Error"

La validation HTTP doit être suivie d'une validation visuelle dans le navigateur.

Workflow de développement frontend¶

Le workflow normal est :

vérifier le worktree, la branche, le HEAD et le status ;
vérifier que CCX_PREVIEW_SOURCE_ROOT pointe vers frontend-preview-v1 ;
vérifier que vendor/autoload.php existe ;
localiser le markup ou la règle CSS exacte avant modification ;
modifier la source canonique à son emplacement existant ;
exécuter git diff --check ;
examiner le diff ciblé et le status Git ;
rafraîchir le preview dans le navigateur ;
valider visuellement le changement ;
contrôler desktop, tablette et mobile lorsque le changement le nécessite ;
exécuter php -l et les tests ciblés lorsqu'un fichier PHP change ;
ne commit qu'après validation ;
ne jamais promouvoir directement le worktree preview en production.

Pour le CSS, éviter les couches successives de correctifs ajoutées en fin de fichier.

Une règle existante doit être modifiée à sa source lorsque cela est possible.

Éviter notamment :

!important
FIX V1
FIX V2
FINAL FIX
MOBILE PATCH

Sources frontend principales¶

Plugin frontend canonique :

plugins/ccx-feeds-industrial/

Catalogue :

plugins/ccx-feeds-industrial/includes/frontend/catalog-router.php
plugins/ccx-feeds-industrial/includes/frontend/product-models.php
plugins/ccx-feeds-industrial/includes/frontend/assets/catalog.css

Thème WordPress :

wordpress/wp-content/themes/ccx/

CSS principaux :

wordpress/wp-content/themes/ccx/assets/css/header.css
wordpress/wp-content/themes/ccx/assets/css/pages.css

Le preview doit toujours consommer ces sources canoniques plutôt qu'une copie runtime indépendante.

Séparation stricte avec la production¶

Le Frontend Preview ne doit jamais :

éditer directement /var/www/html de production ;
modifier manuellement un conteneur de production ;
exécuter docker compose down sur la production ;
builder une image de production sur le VPS ;
supprimer des volumes ;
exécuter docker prune ;
modifier MariaDB de production ;
modifier le .env de production ;
redémarrer Redis ou le worker de production pour une évolution frontend preview ;
effectuer un rollout de production.

Toute commande Docker utilisée pendant ce workflow doit être explicitement rattachée au projet cmonchoix-preview et au Compose du preview.

Promotion vers la production¶

Une validation réussie dans le preview n'est pas une autorisation de déploiement.

La promotion suit le workflow contrôlé :

Frontend Preview
    ↓
validation visuelle et technique
    ↓
commit / push
    ↓
Pull Request
    ↓
CI
    ↓
main
    ↓
image Web immuable
    ↓
activation du RepoDigest
    ↓
release authority
    ↓
rollout wordpress-only
    ↓
certification post-rollout

Le passage en production nécessite une décision explicite séparée.

Invariants¶

Le checkout principal /mnt/data/cmonchoix-platform reste propre pendant le travail preview.
Les évolutions frontend sont réalisées dans /mnt/data/cmonchoix-worktrees/frontend-preview-v1.
CCX_PREVIEW_SOURCE_ROOT pointe vers ce worktree.
Les sources frontend sont montées read-only dans le conteneur Web preview.
Le preview possède son propre état mutable et sa propre DB.
Le gateway reste loopback-only sur 127.0.0.1:8082.
WordPress cron et les mises à jour automatiques sont désactivés.
Les appels HTTP sortants initiés par WordPress sont bloqués.
vendor/ doit être matérialisé et cohérent avec le composer.lock courant.
Un HTTP 200 n'est pas une preuve suffisante de santé runtime.
La validation visuelle est obligatoire pour une évolution d'interface.
Le preview ne constitue jamais une autorité de production.
Toute promotion en production passe par Git, CI, une image immuable et une release authority.