Aller au contenu

Base de données et projections catalogue

Préfixe WordPress

Le préfixe WordPress est une donnée d'environnement, pas une constante applicative.

Un environnement VPS observé utilise actuellement :

wp_3888956

mais il ne faut jamais supposer que le préfixe vaut wp_ ou wp_3888956 dans une commande réutilisable.

Le Domain et l’Application ne doivent pas connaître $wpdb ni le préfixe WordPress. La résolution des noms physiques appartient aux adapters / à l’Infrastructure WordPress, notamment via ccx_feeds_table() ou, dans les composants techniques legacy, $wpdb->prefix.

Pour les diagnostics shell via WP-CLI, découvrir le préfixe :

PREFIX="$(docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db prefix | tr -d '\r')"

echo "$PREFIX"

Puis construire le nom physique :

TABLE="${PREFIX}ccx_navigation_taxonomy_v1"

Pour un accès MariaDB direct sur le VPS, la commande vérifiée est :

docker exec -it ccx-mariadb mariadb -u root -proot ccx

En non-interactif :

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "SELECT 1;"

Les tables de navigation ne définissent pas à elles seules l'architecture publique voulue.

La source canonique de l'architecture de navigation long terme est :

plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php

via :

ccx_navigation_architecture_registry()

Les feuilles futures restent déclarées dans ce registre même lorsqu'aucune offre ne les rend encore visible.

Les tables telles que :

ccx_navigation_taxonomy_v1
ccx_catalog_nav_cache_v1

sont des états/projections runtime. Elles répondent à la question « qu'est-ce qui est actuellement matérialisé ? », pas à la question « quelle est l'architecture publique canonique ? ».

Voir docs/architecture/navigation-architecture.md avant tout diagnostic de catégorie/menu.

ccx_offers_norm_v2

Rôle

Projection normalisée des offres marchandes. C’est une source amont majeure des projections produit de lecture, modèles, spécifications et galeries.

Clé primaire réelle

offer_id

Il n’existe pas de colonne générique id, ni de colonne model_key dans cette table. Les diagnostics SQL doivent utiliser le schéma réel au lieu de supposer des colonnes.

Colonnes structurantes

Identité et source :

  • offer_id
  • run_id
  • source_feed
  • feed_id
  • offer_key
  • ean_norm
  • brand_norm
  • model_norm
  • title_clean
  • product_identity_key
  • variant_identity_key
  • identity_level
  • identity_confidence

Attributs techniques utilisés par l’enrichissement :

  • storage_norm
  • color_norm
  • screen_size_norm
  • ram_norm
  • resolution_norm
  • refresh_rate_norm
  • os_norm
  • network_norm
  • sim_norm
  • cpu_norm
  • gpu_norm
  • aw_description
  • battery_mah si la colonne existe
  • attributes_raw si la colonne existe

Images :

  • image_norm
  • image_alt_1 à image_alt_4
  • image_gallery_json
  • image_count

Classification et qualité :

  • spec_type_probable
  • vertical_id
  • spec_type_final
  • classifier_confidence
  • classifier_reason_primary
  • classifier_reason_codes
  • classification_rule_id
  • classification_rule_code
  • classification_stage
  • classification_notes
  • review_required
  • status
  • reject_code

Point de maintenance important

Une colonne ajoutée à ccx_offers_norm_v2 n’est pas automatiquement consommée par l’enrichissement. Elle doit aussi être sélectionnée dans les readers/builders qui en ont explicitement besoin.

ccx_canonical_products_v1

Rôle

Projection produit canonique de lecture, reconstruite depuis les offres normalisées possédant un product_identity_key non vide.

Elle matérialise un résumé directement consommable par les lectures catalogue et les URLs produit, mais elle ne remplace pas la Canonical Identity du Domain Core.

Clé et index structurants

  • id — clé primaire auto-incrémentée ;
  • product_identity_key — clé logique unique via uniq_product_identity_key ;
  • ean_norm ;
  • canonical_slug ;
  • index sur EAN, slug, économies multi-marchands, nombre de marchands et prix minimum.

Champs de lecture principaux

  • canonical_title ;
  • brand_norm ;
  • model_norm ;
  • image_url ;
  • offer_count ;
  • merchant_count ;
  • min_price ;
  • max_price ;
  • saving_amount ;
  • best_merchant_name ;
  • best_offer_url ;
  • is_multi_merchant ;
  • calculated_at.

Invariant de couverture

Pour tout product_identity_key non vide présent dans ccx_offers_norm_v2, une ligne de même identité doit exister dans ccx_canonical_products_v1.

Le contrôle read-only correspondant est exposé par :

ccx health projections
→ missing_canonical_product_identity

Une identité manquante est une désynchronisation de projection. La correction normale est un refresh/rebuild contrôlé, jamais un INSERT manuel ciblé.

Sémantique de reconstruction CURRENT

Le schéma crée la table en InnoDB. Ce choix est nécessaire à la stratégie de reconstruction transactionnelle actuelle.

Le rebuild :

  1. vérifie l’existence de ccx_offers_norm_v2 ;
  2. ouvre une transaction ;
  3. lit et agrège toutes les identités source ;
  4. échoue sans vider la projection si la lecture source échoue ;
  5. exécute DELETE FROM <projection> dans la transaction ;
  6. réécrit les lignes calculées ;
  7. commit uniquement si toute l’écriture réussit ;
  8. rollback sur erreur de lecture, clear, insert ou commit.

TRUNCATE ne fait pas partie du chemin de rebuild CURRENT, afin de préserver la capacité de rollback transactionnel.

Le refresh public applicatif est protégé par un lock technique ccx_product_canonical_projection_refresh avec attente bornée. Les adapters CLI doivent appeler ce refresh verrouillé et non le rebuild brut.

ccx_product_models_v1

Rôle

Projection agrégée des modèles produits.

Schéma observé

  • model_id — clé primaire auto-incrémentée
  • vertical_id
  • brand_norm
  • model_norm
  • model_key
  • slug
  • image_url
  • offers_count
  • offers_new_count
  • offers_refurb_count
  • best_price_new
  • best_price_refurb
  • min_price
  • best_saving
  • best_savings_percent
  • best_promo_offer_id
  • updated_at
  • created_at

ccx_product_specs_v1

Rôle

Projection des spécifications consolidées par modèle et verticale.

Les lignes sont produites par ccx_product_specs_build_row() puis remplacées verticalement par le service d’écriture de projection.

Les champs observés dans la construction comprennent notamment :

  • vertical_id
  • model_slug
  • model_key
  • brand_norm
  • model_norm
  • écran, résolution et fréquence
  • RAM et stockage
  • couleurs
  • système, réseau et SIM
  • batterie
  • CPU et GPU
  • résumé caméra et USB
  • confidence_score
  • source_count
  • horodatages

Rôle

Projection de la galerie consolidée d’un modèle.

La construction produit notamment :

  • vertical_id
  • model_slug
  • model_key
  • images_json
  • images_count
  • primary_image
  • source_count
  • horodatages

Requêtes de découverte du schéma

Avant tout diagnostic sur une table inconnue, découvrir d'abord le préfixe ou entrer dans MariaDB, puis inspecter le schéma réel.

Exemple avec MariaDB direct :

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SHOW TABLES LIKE '%offers_norm%';
SHOW COLUMNS FROM wp_3888956ccx_offers_norm_v2;
"

Le nom physique ci-dessus est un exemple observé. Pour une commande portable, préférer la découverte dynamique du préfixe avec WP-CLI.

Ne jamais supposer les noms id, title_raw, model_key, brand ou model_name sans validation préalable.

Requêtes de découverte navigation

PREFIX="$(docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db prefix | tr -d '\r')"

NAV_TABLE="${PREFIX}ccx_navigation_taxonomy_v1"
CACHE_TABLE="${PREFIX}ccx_catalog_nav_cache_v1"

printf 'PREFIX=%s\nNAV_TABLE=%s\nCACHE_TABLE=%s\n' \
  "$PREFIX" "$NAV_TABLE" "$CACHE_TABLE"

Lister les tables avant de supposer leur existence :

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query \
  "SHOW TABLES LIKE '%navigation%'; SHOW TABLES LIKE '%taxonomy%';"

Puis seulement interroger les projections runtime.

Une absence dans ces tables ne doit jamais être interprétée comme une absence dans l'architecture canonique sans vérifier navigation-architecture.php.