Crawl catégories

Périmètre

Cette documentation couvre la fonctionnalité de lancement des crawls catégories depuis l'application.

Route UI :

  • /crawl-category

Routes API :

  • POST /api/crawl/run
  • POST /api/crawl/runDE

Fonctionnel

Objectif

Permettre à un utilisateur de lancer manuellement un crawl des catégories Workbench :

  • en français
  • en allemand

La fonctionnalité ne fait pas le crawl elle-même. Elle déclenche un script externe en arrière-plan.

Expérience utilisateur

L'écran propose deux cartes :

  • Crawl FR
  • Crawl DE

Chaque action passe par une modale de confirmation, car le traitement :

  • peut durer plusieurs minutes
  • peut consommer des ressources importantes

Après confirmation :

  • l'UI affiche un état Traitement en cours
  • une notification de succès ou d'erreur est affichée
  • le message utilisateur indique qu'un mail sera envoyé à la fin du traitement

Ce que fait exactement l'écran

L'écran ne suit pas l'exécution du script en temps réel.

Il se limite à :

  • envoyer la demande de lancement
  • confirmer que le process a bien été démarré

Il n'y a pas dans ce repo :

  • de polling d'état
  • de lecture d'avancement
  • de page d'historique des crawls

Technique

Stack

  • Front : Angular
  • Back : Express
  • Lancement système : child_process.spawn
  • Exécution découplée : process détaché

Fichiers clés

Front :

  • linvosges_utilitaire_akeneo/src/app/features/crawl-category/crawl-category.component.ts
  • linvosges_utilitaire_akeneo/src/app/features/crawl-category/crawl-category.component.html
  • linvosges_utilitaire_akeneo/src/app/core/models/crawl.model.ts

Back :

  • server/routes/crawl.routes.js
  • server/main.js

Config :

  • server/.env
  • server/.env.example

Architecture générale

CrawlCategoryComponent  -> POST /api/crawl/run ou /api/crawl/runDE    -> crawl.routes.js      -> vérification CRAWL_SCRIPT_DIR      -> vérification présence du script      -> spawn(process.execPath, [scriptFile], { detached: true })      -> logs stdout/stderr dans le répertoire des scripts      -> réponse immédiate au front

Enchaînement des appels

Crawl FR

Utilisateur  -> clique "Lancer le crawl FR"  -> modale de confirmation  -> CrawlCategoryComponent.confirmCrawl()  -> POST /api/crawl/run  -> crawl.routes.js  -> launchCrawlScript('liste_prod_categ_fr_laura.js', 'fr')  -> spawn node sur le script externe  -> réponse JSON de succès

Crawl DE

Utilisateur  -> clique "Lancer le crawl DE"  -> modale de confirmation  -> CrawlCategoryComponent.confirmCrawl()  -> POST /api/crawl/runDE  -> crawl.routes.js  -> launchCrawlScript('liste_prod_categ_de_linda.js', 'de')  -> spawn node sur le script externe  -> réponse JSON de succès

Scripts attendus

Le backend cherche les scripts suivants dans CRAWL_SCRIPT_DIR :

  • liste_prod_categ_fr_laura.js
  • liste_prod_categ_de_linda.js

Ces scripts ne sont pas versionnés dans ce repo.

Le repo ne contient donc que le lanceur, pas la logique de crawl elle-même.

Variable d'environnement

La variable critique est :

  • CRAWL_SCRIPT_DIR

Elle doit pointer vers :

  • un répertoire existant
  • contenant les scripts FR et DE attendus
  • accessible en lecture/écriture par l'utilisateur qui lance le backend

Exemple :

CRAWL_SCRIPT_DIR=/chemin/vers/crawl_journalier_categ_workbench

Mode d'exécution

Le backend lance le script avec :

  • process.execPath
    • donc le binaire Node courant
  • cwd positionné sur CRAWL_SCRIPT_DIR
  • detached: true
  • stdio redirigé vers des fichiers logs

Le process enfant est ensuite unref(), ce qui signifie :

  • il continue sa vie sans bloquer le serveur Express
  • l'API peut répondre immédiatement

Logs produits

Les sorties standard et erreur sont redirigées dans CRAWL_SCRIPT_DIR :

Pour le crawl FR :

  • crawl_stdout.log
  • crawl_stderr.log

Pour le crawl DE :

  • crawl_stdout_de.log
  • crawl_stderr_de.log

Ces logs sont le premier endroit à vérifier en cas d'échec réel du script après lancement.

Codes d'erreur possibles

La route peut répondre :

  • 503
    • si CRAWL_SCRIPT_DIR n'est pas configuré
  • 404
    • si le répertoire ou le script attendu n'existe pas
  • 500
    • si une autre erreur survient au lancement

Le front affiche simplement une notification d'erreur générique Erreur lors du lancement du crawl FR/DE.

Comportement du front

Le composant Angular :

  • maintient deux états de chargement distincts : isLoadingFR et isLoadingDE
  • garde la trace du type en attente via pendingCrawlType
  • ouvre une modale avant envoi
  • affiche un bandeau Traitement en cours après un lancement réussi

Le contrat de réponse front est minimal :

{  "success": true,  "message": "Crawl FR lancé en arrière-plan. Un mail vous sera envoyé..."
}

Prérequis de mise en service

Pour que la fonctionnalité marche en prod ou en local :

  1. le backend Express doit être démarré
  2. CRAWL_SCRIPT_DIR doit être renseigné dans server/.env
  3. le répertoire cible doit exister
  4. les deux scripts attendus doivent y être présents
  5. l'utilisateur système du backend doit avoir les droits nécessaires
  6. l'infrastructure de notification mail du script externe doit être fonctionnelle si on compte sur cet email

Limites actuelles

  • pas de suivi d'avancement
  • pas de consultation des logs depuis l'interface
  • pas d'historique des exécutions
  • pas de prévention explicite contre les doubles lancements consécutifs
  • forte dépendance à des scripts externes non versionnés ici

Points d'attention maintenance

1. La feature dépend d'artefacts hors repo

Si CRAWL_SCRIPT_DIR ou les scripts changent de nom, l'UI restera visible mais la fonctionnalité sera cassée.

2. Les noms de scripts sont codés en dur

Ils sont aujourd'hui fixés dans server/routes/crawl.routes.js. Toute évolution de nommage doit être reportée dans le code.

3. Le backend ne contrôle pas le succès métier du crawl

Une réponse API success: true signifie seulement :

  • le script a été lancé

Elle ne garantit pas :

  • que le script a terminé
  • qu'il a terminé correctement
  • qu'il a envoyé l'email attendu

4. Les logs de diagnostic sont hors des logs Express

Le diagnostic réel se fait souvent dans :

  • crawl_stdout*.log
  • crawl_stderr*.log

pas seulement dans les logs PM2 ou Winston du backend.