Fiches Techniques

Périmètre

Cette documentation couvre la fonctionnalité de génération de fiches techniques Excel.

Route UI :

  • /fiches-tech

Routes API :

  • POST /api/excel/fiches-tech/generate
  • GET /api/excel/fiches-tech/history
  • GET /api/excel/download/:fileName

Fonctionnel

Objectif

Générer une fiche technique Excel à partir :

  • d'un listing produit source
  • d'une liste de références stock
  • d'un type de fiche
  • d'un plan
  • d'un fournisseur
  • d'un pays

Types de fiches supportés

Le front expose aujourd'hui :

  • LDL
  • TABLE
  • EPONGE
  • DECO
  • VETEMENT
  • LITERIE

Saisie utilisateur

L'utilisateur renseigne :

  • un fichier listing Excel
  • le type de fiche
  • le PLAN
  • le fournisseur
  • le pays
  • les références stock en multiligne

Formats de séparateurs acceptés pour les références :

  • retour ligne
  • virgule
  • point-virgule

Restitution

Après génération :

  • le fichier est téléchargeable immédiatement
  • un résumé est affiché
  • des warnings peuvent être remontés
  • l'historique des générations est mis à jour

Warnings fonctionnels

Le moteur remonte notamment :

  • les références introuvables dans le listing
  • les champs manquants sur certaines références
  • les générations partielles
  • la présence de plusieurs familles dans le même jeu de refs
  • la présence de plusieurs collections dans le même jeu de refs

Dans les cas multi-familles ou multi-collections :

  • la génération continue
  • un warning important liste les valeurs détectées
  • la première valeur trouvée sert d'en-tête

Historique

L'écran affiche un historique des 100 dernières générations maximum encore présentes sur disque.

Technique

Stack

  • Front : Angular
  • Back : Express
  • Lecture listing : ExcelJS
  • Rendu template : xlsx-populate
  • Stockage des exports et de l'historique : système de fichiers local serveur

Fichiers clés

Front :

  • linvosges_utilitaire_akeneo/src/app/features/fiches-tech/fiches-tech.component.ts
  • linvosges_utilitaire_akeneo/src/app/features/fiches-tech/fiches-tech.component.html
  • linvosges_utilitaire_akeneo/src/app/core/models/fiches-tech.model.ts

Back :

  • server/routes/excel.routes.js
  • server/utils/generateFicheTech.js
  • server/utils/fichesTechHistoryStore.js
  • server/utils/fichesTech/genericRenderer.js
  • server/utils/fichesTech/ldlRenderer.js
  • server/utils/fichesTech/workbookCommon.js
  • server/utils/fichesTech/xlsxPopulateRowOps.js

Templates :

  • linvosges_utilitaire_akeneo/src/app/features/fiches-tech/templates/

Architecture générale

FichesTechComponent  -> POST FormData /api/excel/fiches-tech/generate    -> excel.routes.js      -> multer upload du listing      -> generateFicheTech()        -> lecture listing Excel        -> filtrage des références demandées        -> normalisation et groupement        -> sélection du template        -> rendu workbook        -> écriture export .xlsx        -> écriture historique JSON  -> GET /api/excel/download/:fileName

Enchaînement détaillé des appels

Utilisateur  -> FichesTechComponent.generate()  -> création FormData(listingFile, refs, type, plan, supplier, country)  -> POST /api/excel/fiches-tech/generate  -> excel.routes.js  -> multer stocke le fichier dans server/uploads  -> generateFicheTech()  -> buildListingIndex()  -> parseRefs()  -> filtrage des refs présentes dans le listing  -> deriveArticleGroup() sur GENRE, fallback LIBELLE  -> buildWarnings()  -> findTemplatePath()  -> renderGenericWorkbook() ou renderLdlWorkbook()  -> écriture du .xlsx dans server/exports  -> écriture historique JSON  -> réponse JSON front  -> ouverture de /api/excel/download/:fileName

Contrat de données de la route

Le POST /api/excel/fiches-tech/generate attend :

  • listingFile
  • refs
  • type
  • plan
  • supplier
  • country

Les champs obligatoires sont validés côté route avant appel métier.

Lecture du listing

Le moteur construit un index à partir de la première feuille Excel du listing.

Colonnes importantes :

  • REFERENCE STOCK
  • MENU FAMILLE
  • GAMME
  • COLORIS
  • DIM.
  • QUALITE / IMPRESSION
  • DESCRIPTIF
  • MATIERE
  • COMPOSITION / CONTEXTURE
  • GRAMMAGE / NOMBRE DE FILS
  • FINITION / COUTURE
  • FINITION / ACCESSOIRES
  • REF FOURNISSEUR
  • LIBELLE
  • GENRE

Le code supporte aussi plusieurs alias d'en-têtes.

Normalisation des refs

Les refs saisies sont :

  • nettoyées
  • dédoublonnées
  • préservées dans l'ordre de saisie

Chaque ligne retenue du listing est ensuite enrichie avec :

  • un articleGroupKey
  • un articleGroupLabel

La logique de groupement actuelle est volontairement data-driven :

  • source principale : GENRE
  • fallback : LIBELLE

Sélection des templates

Le type de fiche est décrit dans TYPE_CONFIG :

  • template fixe ou préfixe de template
  • cellules d'en-tête
  • renderer à utiliser
  • contrat de bloc du template

Deux types de renderers existent :

  • generic
  • ldl

Le rendu est maintenant Linux-native et ne dépend plus de PowerShell ni d'Excel COM.

Rendu des workbooks

Le renderer reçoit :

  • le chemin du template
  • le chemin de sortie
  • les en-têtes à injecter
  • les informations techniques globales
  • les lignes produits déjà préparées
  • le contrat de géométrie du template

Le renderer s'occupe ensuite :

  • de remplir les cellules d'en-tête
  • de construire les blocs produits
  • de gérer les groupes par genre
  • de gérer les séparations visuelles groupe/produit
  • de produire les tableaux annexes selon le template

Nom des fichiers

Le nom de sortie suit ce schéma :

fiche_technique_{PLAN}_{FOURNISSEUR}_{COLLECTION}_{TYPE}_{YYYYMMDD}_{HHMMSS}.xlsx

Les segments sont sanitizés avant écriture.

Historique et stockage

Les fichiers exportés sont écrits dans :

  • server/exports/

L'historique est persisté dans :

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

Le store :

  • limite l'historique à 100 entrées
  • filtre les entrées dont le fichier n'existe plus

Nettoyage des uploads

Le fichier upload temporaire est supprimé dans le finally de la route après traitement, succès ou échec.

Points d'attention

  • les templates .xlsx sont une dépendance applicative forte et doivent être déployés avec le code
  • le contrat TYPE_CONFIG et la géométrie des templates doivent rester synchronisés
  • le groupement est piloté par les données du listing, pas par des familles codées en dur
  • la génération repose sur la première feuille du listing

Limites actuelles

  • génération FR uniquement côté écran
  • si plusieurs familles/collections sont mélangées, le moteur continue mais choisit la première pour l'en-tête
  • la qualité du rendu dépend directement de la qualité du listing source et de ses en-têtes