Application Visualisation PIM

Vue d'ensemble

Cette application regroupe plusieurs outils internes autour des données produit Linvosges :

  • visualisation PIM par SKU ou slug
  • visualisation web produit avec variantes
  • assistant conversationnel personal shopper
  • génération de fiches techniques Excel
  • génération de listing web SKU / slug / gamme
  • lancement de crawls catégories

Le projet est composé d'un front Angular et d'un backend Node.js/Express. En production, Apache sert le build Angular et reverse-proxy les API applicatives.

Résumé très court par fonctionnalité

Visualisation PIM

Permet de rechercher un produit par SKU ou par slug, puis d'afficher ses données Akeneo enrichies. Deux vues existent :

  • complet pour une lecture technique large
  • web pour une vue plus proche du rendu e-commerce, avec variantes couleur/taille

Personal Shopper

Interface conversationnelle qui envoie un besoin en langage naturel à un service externe de recommandation, puis affiche les produits retournés avec leurs variantes, statuts et liens vers le site.

Fiches Techniques

Génère un fichier Excel de fiche technique à partir d'un listing produit, d'une liste de SKU et d'un type de template (LDL, TABLE, EPONGE, DECO, VETEMENT, LITERIE). Le moteur s'appuie sur des templates .xlsx versionnés dans le repo.

Listing Web

Génère un workbook Excel de travail à partir d'un export produit et d'un export product model, afin d'obtenir des correspondances entre SKU, slug produit et slug de gamme. Un filtre optionnel par liste de SKU est possible.

Crawl catégories

Déclenche des scripts de crawl catégories FR ou DE en arrière-plan, via des scripts Node externes au repo principal, pointés par variable d'environnement.

Architecture du repo

Le repo est organisé en trois grandes zones :

  • linvosges_utilitaire_akeneo/
    • front Angular
    • pages, composants, services, assets, templates Excel embarqués côté projet
  • server/
    • backend Express
    • routes API
    • services Akeneo
    • moteurs de génération Excel
    • historique des générations
  • racine du repo
    • configuration Apache de référence
    • documentation
    • fichiers d'exemple ou de test selon l'état du worktree

Arborescence utile :

visualisation_pim/  apache-vhost-akeneo.conf  docs/  linvosges_utilitaire_akeneo/    src/    dist/    package.json    angular.json  server/    main.js    ecosystem.config.js    routes/    services/    utils/    config/    package.json    .env.example

Technique

Front

  • Angular standalone components
  • Tailwind CSS + DaisyUI
  • build via @angular/build
  • environnements dev/prod via :
    • src/environments/environment.ts
    • src/environments/environment.prod.ts

URLs front :

  • en local :
    • API back principale : http://localhost:3005/api
    • API personal shopper : http://localhost:8443
  • en prod :
    • API back principale : /api
    • API personal shopper : /api/shopper

Backend

  • Node.js
  • Express
  • Axios pour Akeneo et autres appels HTTP
  • ExcelJS pour certains traitements Excel
  • xlsx-populate pour les fiches techniques
  • Multer pour les uploads
  • Winston pour les logs
  • NodeCache pour le cache mémoire
  • PM2 pour l'exécution en production

Services externes

  • API Akeneo REST
  • deeplinks images du site
  • service personal shopper externe sur port 8443
  • scripts de crawl catégories situés hors du repo applicatif

Architecture applicative

Front -> Back principal

Angular  -> /api/products...  -> /api/excel...  -> /api/crawl... Express  -> authentification Akeneo  -> services Akeneo  -> générateurs Excel  -> scripts de crawl externes

Front -> Personal Shopper

Angular  -> /api/shopper/api/chat en production Apache  -> proxy vers 127.0.0.1:8443

Production

Navigateur  -> Apache HTTPS    -> fichiers statiques Angular dist/linvosges-app/browser    -> proxy /api vers Node Express:3005    -> proxy /api/shopper vers service shopper:8443

Installation locale

Prérequis

  • Node.js et npm
  • accès réseau à Akeneo
  • credentials Akeneo valides
  • service personal shopper local si on veut tester cette fonctionnalité
  • scripts de crawl locaux si on veut tester les crawls

1. Installer le front

cd linvosges_utilitaire_akeneo
npm install

2. Installer le backend

cd server
npm install

3. Configurer le .env backend

Le backend charge son .env depuis server/.env, pas depuis la racine du repo.

Variables requises au démarrage :

  • USER_API
  • PASSWORD_API
  • GRANT_TYPE
  • AUTHORIZATION

Variables importantes en pratique :

  • COOKIE
  • PORT
  • NODE_ENV
  • ALLOWED_ORIGINS
  • RATE_LIMIT_WINDOW_MS
  • RATE_LIMIT_MAX_REQUESTS
  • LOG_LEVEL
  • CACHE_TTL
  • CRAWL_SCRIPT_DIR

Lancer l'application en local

Front Angular

cd linvosges_utilitaire_akeneo
npm start

Par défaut :

  • front sur http://localhost:4200

Backend Express

cd server
npm run dev

Par défaut :

  • backend sur http://localhost:3005
  • healthcheck sur http://localhost:3005/health

Tests

Backend :

cd server
npm test

Front :

cd linvosges_utilitaire_akeneo
npm test

Build et lancement en production

Build Angular

cd linvosges_utilitaire_akeneo
npm run build:prod

Le build de sortie est servi depuis :

  • linvosges_utilitaire_akeneo/dist/linvosges-app/browser

Lancement backend simple

cd server
npm start

Lancement backend avec PM2

cd server
npm run prod

Le fichier PM2 est :

Configuration actuelle :

  • nom du process : utilitaire-akeneo
  • script : main.js
  • port : 3005
  • mode : cluster
  • cwd codé en dur sur /home/mwolkowicz/dev/visualisation_pim/server

Point important :

Le cwd PM2 est hard-codé. Si le projet est installé ailleurs sur le serveur, il faut adapter ecosystem.config.js avant de lancer PM2.

Commandes PM2 utiles

pm2 start ecosystem.config.js pm2 list pm2 logs utilitaire-akeneo pm2 restart utilitaire-akeneo pm2 stop utilitaire-akeneo pm2 delete utilitaire-akeneo pm2 save

Apache

Le fichier de référence fourni est :

Il fait quatre choses essentielles :

  1. redirection HTTP -> HTTPS
  2. service des fichiers statiques Angular depuis dist/linvosges-app/browser
  3. rewrite SPA vers index.html
  4. reverse proxy :
    • /api -> 127.0.0.1:3005/api
    • /api/shopper/ -> 127.0.0.1:8443/

En production, Apache est donc le point d'entrée unique.

Vérification après déploiement

pm2 logs utilitaire-akeneo --lines 100
curl http://127.0.0.1:3005/health

Règle critique de ce repo

Les templates .xlsx des fiches techniques font partie de l'application et doivent être versionnés dans git.

PM2 et logs

Deux niveaux de logs existent :

  • PM2 :
    • out.log
    • error.log
  • Winston en production :
    • logs/combined.log
    • logs/error.log

Point utile :

Le dossier logs/ doit exister ou être gérable par l'utilisateur qui lance le process, sinon les transports fichier Winston peuvent poser problème.

Fichier .env

Emplacement

  • server/.env

Variables vraiment nécessaires

  • USER_API
  • PASSWORD_API
  • GRANT_TYPE
  • AUTHORIZATION

Variables fortement conseillées

  • COOKIE
  • ALLOWED_ORIGINS
  • LOG_LEVEL
  • CACHE_TTL

Variables optionnelles selon fonctionnalités

  • CRAWL_SCRIPT_DIR
    • obligatoire uniquement si on veut utiliser Crawl catégories

Comportement au démarrage

Le backend valide les variables au boot via server/config/env-validator.js.

Si des variables requises sont absentes :

  • le serveur ne démarre pas

Fichiers et répertoires d'exploitation

Côté backend

  • server/uploads/
    • fichiers entrants temporaires
  • server/exports/
    • fichiers Excel générés
    • historiques JSON

Historiques persistants

  • server/exports/fiches-tech-history.json
  • server/exports/sku-slug-history.json

Assets applicatifs sensibles

  • templates fiches techniques dans linvosges_utilitaire_akeneo/src/app/features/fiches-tech/templates/
  • src/assets/data/mesures.json pour les unités produits

Points utiles de maintenance

1. Le front et le back sont déployés séparément mais vivent dans le même repo

Il faut penser à :

  • installer les dépendances du front
  • builder le front
  • installer les dépendances du back
  • redémarrer PM2

Faire seulement un git pull ne suffit pas.

2. Le personal shopper n'est pas implémenté dans ce repo

Le front suppose qu'un service existe sur :

  • localhost:8443 en local
  • 127.0.0.1:8443 derrière Apache en production

3. Les crawls catégories dépendent d'un répertoire externe

La feature ne fonctionnera que si CRAWL_SCRIPT_DIR :

  • est défini
  • existe
  • contient les scripts attendus

4. Le backend tourne sur 3005, pas 3000

L'ancien README racine est obsolète sur ce point. La configuration actuelle du repo et de PM2 pointe vers 3005.

5. Les fichiers générés ne sont pas faits pour être commités

uploads et exports sont des répertoires d'exploitation locale/serveur, pas des assets sources.

Séquence de mise en service recommandée

  1. Cloner le repo.
  2. Créer server/.env à partir de server/.env.example.
  3. Installer les dépendances du front et du back.
  4. Builder Angular en production.
  5. Vérifier que les templates .xlsx sont bien présents dans le repo déployé.
  6. Configurer Apache avec le bon DocumentRoot et les proxies /api et /api/shopper.
  7. Adapter server/ecosystem.config.js si le chemin cwd n'est pas le bon.
  8. Lancer le backend avec PM2.
  9. Tester GET /health.
  10. Vérifier ensuite les écrans :
    • visualisation PIM
    • personal shopper
    • listing web
    • fiches techniques

Documents complémentaires