Reconstruction des projections

Status: CURRENT / OPERATIONAL

Rôle

Cette page documente les chemins opérateur certifiés pour reconstruire ou contrôler des projections dérivées.

Il n’existe pas, dans l’état CURRENT documenté ici, une commande générique unique rebuild-projections qui reconstruirait sans distinction toutes les familles. Il faut utiliser l’entrypoint concret de la projection visée et vérifier son comportement dans le Runtime courant.

Canonical Product Projection

Projection :

ccx_canonical_products_v1

Source amont CURRENT :

ccx_offers_norm_v2

La projection est globale et regroupée par product_identity_key non vide.

Statut read-only

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx product-canonical status

La sortie expose notamment :

• la table ;
• son existence ;
• le nombre total de lignes ;
• les slugs manquants ;
• le nombre de slugs distincts ;
• le dernier calculated_at.

Cette commande observe la projection ; elle ne la reconstruit pas.

Rebuild contrôlé

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx product-canonical rebuild

Classe de sécurité : écriture / reconstruction globale.

L’adapter CLI appelle le refresh verrouillé ccx_product_canonical_projection_refresh() et ne doit pas contourner ce verrou pour appeler le rebuild brut.

Le résultat réussi expose notamment :

ok: 1
source_table: ...ccx_offers_norm_v2
rows_selected: <N>
rows_written: <N>
missing_slug: 0
calculated_at: <UTC>

Les valeurs <N> dépendent de l’état courant ; elles ne doivent pas être codées en dur dans une procédure.

Garde-fous du rebuild canonical

Le chemin CURRENT garantit :

• vérification de l’existence de la table source ;
• lock applicatif dédié avec attente bornée ;
• table cible InnoDB ;
• ouverture explicite d’une transaction ;
• aucune suppression de la cible si la lecture source échoue ;
• DELETE + réécriture dans la transaction ;
• rollback si le clear, un insert ou le commit échoue ;
• remontée explicite de db_error sur les erreurs techniques prévues.

Le rebuild ne doit pas être remplacé par :

• un TRUNCATE manuel ;
• des INSERT ciblés pour les produits manquants ;
• une correction du slug dans le thème ;
• une génération d’URL concurrente dans le frontend.

Health check après reconstruction

Après un rebuild, exécuter le contrôle read-only :

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx health projections

Pour la projection canonical, le contrôle structurant est :

missing_canonical_product_identity

Résultat attendu :

count = 0
status = PASS

Le health check vérifie également la présence des tables nécessaires et les autres invariants de projection qu’il connaît.

Synchronisation normale

Un rebuild manuel ne constitue pas le mécanisme normal de fraîcheur.

Lors de la finalisation d’un sync marchand réussi :

upsert offres normalisées
→ ccx_sync_refresh_product_projections(feed)
→ refresh canonical
→ rebuild Product Models des verticales concernées

Un replay d’offre en mode apply rafraîchit également la projection canonical après le commit de l’offre.

Le rebuild manuel sert donc surtout à :

• récupérer d’une désynchronisation ;
• certifier une évolution du générateur ;
• reconstruire après changement de règle ou de schéma ;
• rétablir une projection dont l’état dérivé n’est plus fiable.

Autres familles de projections

Les autres procédures opérationnelles restent documentées par famille :

• Rebuild modèles
• Rebuild spécifications
• Rebuild galeries

Ne pas déduire le nom d’une commande à partir du nom d’un document. Vérifier l’entrypoint réel avec wp help ccx ou le dump JSON de la CLI avant exécution.

Frontière d’architecture

La CLI reste un adapter mince : validation, délégation et formatage.

La logique de projection ne doit pas être réimplémentée dans la commande. Les détails SQL appartiennent aux composants techniques prévus, et la cible normative reste :

Application / orchestration
        ↓
Contracts
        ↓
Builder de projection pur
        ↓
Write Service
        ↓
Infrastructure de persistance

L’implémentation canonical CURRENT n’a pas encore totalement atteint cette séparation ; voir la dette technique documentée dans ../engineering/technical-debt.md.

Checklist opérateur

[ ] je connais la projection visée
[ ] je sais si la commande est read-only ou mutante
[ ] la source amont est saine
[ ] aucun autre rebuild concurrent n'est attendu
[ ] j'utilise l'entrypoint CLI certifié
[ ] je contrôle le code de retour et les compteurs
[ ] je lance le health check après écriture
[ ] je vérifie le consommateur concerné si l'incident était visible en frontend
[ ] je n'effectue aucune réparation SQL manuelle ligne par ligne