BDD-139 — Entrée dossier avec ligne de titres et nom_du_fichier

1. User Story

En tant qu'administrateur, je veux sélectionner un dossier du dépôt comme source d'un workflow (au lieu d'un seul fichier), afin de charger automatiquement tous les fichiers compatibles du dossier à l'exécution, avec une ligne d'en-tête configurable et une colonne indiquant l'origine de chaque ligne.

2. Critères d'acceptance

#	Critère	Statut
1	Le panneau Entrée (fichier dépôt) propose un basculement Fichier / Dossier	✅
2	En mode Dossier : sélection d'un dossier accessible + saisie de la ligne d'en-tête (1-based)	✅
3	Aperçu des données fusionnées (échantillon) avec bannière récapitulative	✅
4	À l'exécution : tous les fichiers compatibles du dossier sont chargés et empilés	✅
5	Chaque ligne porte la colonne nom_du_fichier	✅
6	En-têtes incohérents entre fichiers → erreur claire	✅
7	La configuration est sauvegardée avec le canvas workflow	✅

3. Périmètre fonctionnel

Règles métier

• Périmètre fichiers : enfants directs du dossier sélectionné uniquement.
• Extensions : .csv, .xls, .xlsx, .json.
• Tri : nom de fichier croissant.
• Ligne d'en-tête : headerRowIndex (défaut 1), appliquée à chaque fichier.
• Fichiers non compatibles : ignorés ; l'UI affiche le nombre retenu sur le total.
• Mode fichier unique : comportement existant inchangé.

Frontend

Fichier	Rôle
WorkflowDepotSourcePanel.vue	Bascule Fichier / Dossier dans le mode dépôt
WorkflowDepotFolderSourcePanel.vue	Sélection dossier, ligne d'en-tête, aperçu
WorkflowSourceSelectorPanel.vue	Intégration du panneau dépôt étendu
workflow-folder-source-preview.fetch.js	Appel GET /workflows/depot-folder-preview
useWorkflowActiveSourceBindings.js	Liaisons depotSourceScope, inputFolderUuid, headerRowIndex
workflow-canvas.model.js / workflow-canvas.sync.js	Persistance canvas
workflow-traitement-preview.pipeline.js	Aperçu traitements amont depuis source dossier

Backend

Fichier	Rôle
sql/tool_20_workflow_input_folder.sql	Colonne workflow_nodes.input_folder_id
workflow-canvas-folder-bindings.ts	Résolution UUID dossier → id (contrôle d'accès)
workflow-source-depot-config.ts	Normalisation depotSourceScope / headerRowIndex
workflow-depot-folder-parse.util.ts	Parse CSV / Excel / JSON avec ligne d'en-tête
workflow-depot-folder-input.service.ts	Fusion fichiers + nom_du_fichier → staging
workflow-depot-folder-preview.service.ts	Aperçu éditeur dossier
workflow-run-staging-execution.service.ts	Dispatch source dossier à l'exécution
workflows.controller.ts	Endpoint depot-folder-preview
workflow.presenter.ts	Champs dossier dans la réponse canvas

Base de données

Changement	Détail
workflow_nodes.input_folder_id	FK nullable vers folders.id
workflow_nodes.configuration.sourceDepot	{ depotSourceScope: "folder" | "file", headerRowIndex: number }

4. Endpoints API

Méthode	Chemin	Guards	Description
GET	/workflows/depot-folder-preview	AuthGuard, AdminGuard	Aperçu fusionné d'un dossier dépôt
PUT	/workflows/current/canvas	AuthGuard, AdminGuard	Sauvegarde nœud source avec inputFolderUuid

Query GET /workflows/depot-folder-preview

Paramètre	Obligatoire	Description
folderUuid	oui	UUID du dossier
headerRowIndex	non	Ligne d'en-tête 1-based (défaut 1)

Exemple de réponse

{
  "folder": { "uuid": "…", "name": "Salaires" },
  "documentCount": 2,
  "totalDocuments": 3,
  "headerRowIndex": 1,
  "columns": [
    { "name": "code", "inferredType": "texte" },
    { "name": "nom_du_fichier", "inferredType": "texte" }
  ],
  "rows": [
    { "code": "A", "nom_du_fichier": "janvier.csv" }
  ],
  "hint": "Aperçu limité à 20 lignes."
}

Payload canvas (extrait nœud source)

{
  "id": "…",
  "type": "source",
  "sourceMode": "document",
  "depotSourceScope": "folder",
  "inputFolderUuid": "uuid-dossier",
  "headerRowIndex": 2
}

5. Tests

Couche	Fichiers
Back unit	workflow-source-depot-config.spec.ts, workflow-canvas-folder-bindings.spec.ts, workflow-depot-folder-parse.util.spec.ts, workflow-depot-folder-input.service.spec.ts, workflows.service.spec.ts, workflow-group-by.engine.spec.ts, workflow-group-by-staging.service.spec.ts
Back e2e	test/e2e/workflows-controller.e2e-spec.ts — depot-folder-preview, persistance canvas dossier, persistance canvas group_by
Front unit	WorkflowDepotSourcePanel.spec.js, workflow-folder-source-preview.fetch.spec.js, useWorkflowActiveSourceBindings.spec.js, workflow-canvas.model.spec.js, workflow-group-by.engine.spec.js, workflow-traitement-preview.pipeline.spec.js, workflow-traitement.sync.spec.js, workflow-run-validation.spec.js
Front e2e	e2e/pages/admin/admin-workflows.spec.js — sélection dossier + PUT canvas, aperçu group_by

6. Documentation technique

• Workflows — source dossier dépôt
• Workflows — Regrouper et calculer (GROUP BY)

7. Extension (même branche) — Regrouper et calculer (GROUP BY)

Livré sur la branche BDD-139 : nouveau bloc de traitement distinct de la Ligne de synthèse.

Objectif

Remplacer les lignes détail par des lignes agrégées (équivalent SQL GROUP BY), sans ajouter de lignes en fin de tableau.

Périmètre

• Sous-type Traitement : group_by (libellé UI : Regrouper et calculer).
• Colonnes de sortie = groupByColumns + colonnes cibles des metrics ; les autres colonnes amont sont supprimées.
• Calculs : SUM, COUNT, COUNT DISTINCT, AVG, MIN, MAX (même moteur d’agrégats que la ligne de synthèse).
• groupByColumns vide : agrégat global sur toutes les lignes.
• Exécution : WorkflowGroupByStagingService (CREATE TABLE … AS SELECT … GROUP BY).

Différence avec Ligne de synthèse (BDD-134)

	Regrouper et calculer	Ligne de synthèse
Effet	Remplace le détail	Conserve le détail + ajoute des lignes
SQL	GROUP BY	UNION ALL

Configuration JSONB (extrait)

{
  "type": "group_by",
  "groupByColumns": ["Matricule", "Mois"],
  "metrics": [
    { "sourceColumn": "Montant", "fn": "SUM", "targetColumn": "Montant_total" }
  ]
}

Fichiers principaux

Rôle	Chemin
Moteur front	front/src/pages/admin/workflows/workflow-group-by.engine.js
Panneau UI	front/src/components/workflows/WorkflowGroupByPanel.vue
Moteur back	back/src/api/workflows/execution/workflow-group-by.engine.ts
Staging SQL	back/src/api/workflows/staging/workflow-group-by-staging.service.ts