Diagnostic et exploitation¶

Méthode générale¶

Diagnostiquer le catalogue dans l’ordre des projections :

ccx_offers_norm_v2
    ↓
ccx_product_models_v1
    ↓
ccx_product_specs_v1
    ↓
ccx_product_gallery_v1

Ne pas modifier le générateur aval avant d’avoir vérifié l’éligibilité des données amont.

Pour un problème de navigation publique, ne pas commencer par une table SQL : commencer par plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php, qui est la source canonique de l'architecture long terme. Les tables de taxonomie/cache sont des projections runtime et peuvent ne contenir qu'un sous-ensemble actuellement alimenté.

Voir docs/architecture/navigation-architecture.md.

1. Vérifier le schéma réel¶

Accès MariaDB direct vérifié sur le VPS :

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

Pour une commande non interactive :

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SHOW COLUMNS FROM wp_3888956ccx_offers_norm_v2;
"

wp_3888956 est un préfixe observé, pas une constante. Pour une commande portable utilisant WP-CLI :

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

echo "$PREFIX"

Colonnes dont l’absence a déjà provoqué des requêtes invalides :

id : utiliser offer_id ;
title_raw : absent de la projection observée ;
model_key : absent de ccx_offers_norm_v2 ;
brand et model_name : utiliser brand_norm et model_norm dans ccx_product_models_v1.

2. Vérifier les offres d’une verticale¶

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SELECT vertical_id, spec_type_final, status, review_required, COUNT(*) AS total
FROM wp_3888956ccx_offers_norm_v2
WHERE vertical_id='smartphone'
GROUP BY vertical_id, spec_type_final, status, review_required;
"

3. Rechercher un produit par titre¶

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SELECT
  offer_id,
  source_feed,
  brand_norm,
  model_norm,
  title_clean,
  vertical_id,
  spec_type_probable,
  spec_type_final,
  review_required,
  status,
  reject_code
FROM wp_3888956ccx_offers_norm_v2
WHERE title_clean LIKE '%Galaxy A16%';
"

Ne pas limiter immédiatement par source_feed : le produit peut provenir d’un autre flux ou le modèle peut être une projection ancienne.

4. Comparer modèles et spécifications¶

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SELECT m.*
FROM wp_3888956ccx_product_models_v1 m
LEFT JOIN wp_3888956ccx_product_specs_v1 s
  ON s.model_key = m.model_key
 AND s.vertical_id = m.vertical_id
WHERE m.vertical_id = 'smartphone'
  AND s.model_key IS NULL;
"

Cette requête a permis d’identifier un modèle Samsung Galaxy A16 présent dans les modèles mais absent des spécifications.

5. Compter les projections¶

docker exec -i ccx-mariadb mariadb -u root -proot ccx -e "
SELECT vertical_id, COUNT(*) AS total
FROM wp_3888956ccx_product_models_v1
GROUP BY vertical_id;

SELECT vertical_id, COUNT(*) AS total
FROM wp_3888956ccx_product_specs_v1
GROUP BY vertical_id;
"

Un écart n’est pas automatiquement un bug du constructeur de specs. Vérifier d’abord les offres éligibles et l’état de la projection des modèles.

6. Diagnostiquer une catégorie ou sous-catégorie manquante¶

6.1 Vérifier d'abord le registre canonique¶

sed -n '1,360p' \
plugins/ccx-feeds-industrial/includes/application/navigation-architecture.php

Identifier la feuille concernée et ses contrats :

verticals
accessory_types
exclude_accessory_types
éventuellement always_visible

Une feuille déclarée ici fait partie de l'architecture long terme même si aucune ligne correspondante n'existe encore dans les tables runtime.

6.2 Découvrir le préfixe et les tables runtime¶

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"

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

Ne jamais utiliser aveuglément wp_ccx_navigation_taxonomy_v1 : le préfixe réel peut être différent de wp_.

6.3 Inspecter la taxonomie matérialisée¶

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query "
SELECT nav_category, nav_group, nav_subcategory
FROM ${NAV_TABLE}
WHERE is_active = 1
GROUP BY nav_category, nav_group, nav_subcategory
ORDER BY MIN(sort_order), nav_category, nav_group, nav_subcategory;
"

Cette requête montre l'état runtime matérialisé. Elle ne constitue pas la liste canonique de toutes les catégories prévues.

6.4 Inspecter le cache catalogue/navigation¶

docker compose exec -T platform-worker \
  wp --allow-root --path=/var/www/html db query "
SELECT nav_category, nav_group, nav_subcategory, seo_path_norm_nav
FROM ${CACHE_TABLE}
GROUP BY nav_category, nav_group, nav_subcategory, seo_path_norm_nav
ORDER BY nav_category, nav_group, nav_subcategory;
"

Des chemins historiques, incomplets ou sans groupe peuvent apparaître dans une projection/cache. Leur présence n'en fait pas la source de vérité de l'architecture.

6.5 Ordre d'analyse obligatoire¶

Pour une feuille absente du site :

navigation-architecture.php
        ↓
contrat vertical/accessory
        ↓
offres normalisées éligibles
        ↓
modèles publics si requis
        ↓
taxonomie runtime
        ↓
cache navigation
        ↓
rebuild / invalidation

Ne pas conclure « cette catégorie n'existe pas » simplement parce qu'une recherche SQL dans ccx_navigation_taxonomy_v1 ou ccx_catalog_nav_cache_v1 renvoie zéro ligne.

7. Relancer la normalisation d’un flux¶

Exemple Samsung :

docker exec -it ccx-wordpress php \
/var/www/html/wp-content/plugins/ccx-feeds-industrial/includes/pipeline/90-offers-norm.php \
samsung

8. Reconstruire les spécifications sans WP-CLI¶

docker exec -it ccx-wordpress php -r '
require "/var/www/html/wp-load.php";
require_once WP_PLUGIN_DIR . "/ccx-feeds-industrial/includes/bootstrap/product-models-application.php";
ccx_bootstrap_product_models_application();
print_r(ccx_product_specs_rebuild("smartphone"));
'

Exemple de résultat observé :

table_exists: yes
vertical: smartphone
specs_count: 10
avg_confidence: 35.8
status: ok
rebuilt_specs: 10

9. Vérifier le fichier PHP avant déploiement¶

php -l plugins/ccx-feeds-industrial/includes/application/product-model-enrichment.php
php -l plugins/ccx-feeds-industrial/includes/pipeline/90-offers-norm.php

Checklist avant correction de code¶

Pour le catalogue :

schéma SQL confirmé ;
offre retrouvée sans colonnes supposées ;
vertical_id, status et review_required vérifiés ;
projection des modèles contrôlée ;
bootstrap applicatif vérifié ;
reconstruction reproduite ;
différence entre problème de données, de projection et de code établie.

Pour la navigation :

registre navigation-architecture.php vérifié en premier ;
contrat de feuille (verticals / accessory types / exclusions) identifié ;
préfixe WordPress découvert dynamiquement ;
tables runtime identifiées avant interrogation ;
offres/modèles éligibles vérifiés ;
taxonomie et cache traités comme projections, pas comme autorité ;
nécessité d'un rebuild/invalidation établie avant modification du code.