Bibliothèque d'objets de restitution — Pastilles, KPI, Graphiques, Vues

Spécification technique pour Heriade Rapport. Harmonise la création et la réutilisation des objets insérables dans un Tableau de bord (TDB), aujourd'hui hétérogène (KPI a sa bibliothèque, les pastilles se copient-collent, graphiques et vues n'ont pas de mécanisme d'insertion unifié).

1. Objectif

Remplacer le copier-coller de pastilles par un modèle de bibliothèque, sur le même principe que la bibliothèque de KPI déjà spécifiée (docs/spec-bibliotheque-kpi.md) : chaque objet de restitution est défini une fois, dans son propre onglet de préparation, puis inséré (jamais recréé) dans un ou plusieurs TDB.

2. Les 4 types d'objets insérables

Type	Nature	Où il est préparé	Comportement dans le TDB
KPI	Ratio (volume réalisé / capacité), cf. `spec-bibliotheque-kpi.md`	Onglet Indicateurs (existant)	Affiché en place (jauge)
Pastille	Valeur unique, avec comparaison optionnelle	Nouvel onglet Pastilles	Affiché en place (valeur + tendance)
Graphique	Visualisation (waterfall, courbe, treemap...)	Nouvel onglet Graphiques, ou dérivé d'une Vue existante	Miniature cliquable → ouvre le graphique en détail
Vue	Tableau complet (cascade P&L, etc., déjà existant)	Écran Vues (existant)	Miniature cliquable → ouvre la vue en détail

Le principe commun : préparer une fois, insérer partout. Un TDB ne contient plus de configuration propre à un objet, seulement une référence vers une définition de bibliothèque + sa position sur le canevas.

3. Modèle de données

PastilleDefinition (nouveau)

interface PastilleDefinition {
  id: string
  nom: string                    // ex: "Marge brute"
  mesure: {
    connectionId: string
    axis: string                  // ex: 'compte'
    noeuds: string[]               // codes DimNode sélectionnés, à n'importe quel niveau de hiérarchie
                                    // (feuille ou agrégat, ex: "Marge brute", "601500")
    filtresComplementaires?: { axis, code }[]  // ex: établissement, si non couvert par le périmètre du TDB
  }
  comparaison?: {
    type: 'budget' | 'n1' | 'variation_pct' | 'aucune'
  }
  // Règle de coloration (cf. note ci-dessous) : jamais de logique conditionnelle
  // par type de compte (charge/produit) — le signe du delta suffit toujours.
  unite: '€' | 'k€' | 'M€' | '%' | 'nombre'   // réutilise format.ts
  titre: {
    position: 'haut' | 'centre' | 'bas'    // défaut : 'haut'
    poids: 'normal' | 'gras'                 // défaut : 'normal'
    taille: 'petit' | 'normal' | 'grand'     // défaut : 'normal'
  }
  visuel: {
    type: 'valeur_seule' | 'valeur_avec_tendance' | 'valeur_avec_comparaison' | 'valeur_avec_icone' | 'valeur_avec_barre_progression' | 'carte_comparative'   // catalogue élargi, cf. docs/spec-parametres-mise-en-forme.md section 6
    // couleur dérivée automatiquement du domaine de la mesure, cf. docs/spec-parametres-mise-en-forme.md section 3 — plus de champ éditable ici
  }
}

Sélection de la mesure — nœud agrégé plutôt que liste de feuilles. L'étape 1 du wizard utilise le TreePicker existant (déjà utilisé pour les filtres établissement) sur l'arbre DimNode de l'axe choisi, plutôt qu'une liste plate de comptes à cocher un par un. L'utilisateur sélectionne directement un nœud agrégé (ex. "Marge brute", "Charges variables") pour bénéficier de la consolidation déjà gérée par pivot() en remontant l'arbre, sans avoir à recomposer manuellement la liste de comptes qui compose cet agrégat. La sélection de plusieurs nœuds (feuilles ou agrégats) reste possible pour composer une mesure sur mesure (ex. deux agrégats combinés).

Règle de coloration favorable/défavorable — nature du compte + convention de signe, jamais le signe brut seul. Le signe brut d'une valeur ne suffit pas à déterminer le sens favorable/défavorable, pour deux raisons : un produit peut légitimement être négatif (avoir, note de crédit), et certaines entreprises chargent leurs données en valeur absolue (charges stockées en positif) plutôt qu'en convention comptable standard (charges négatives). La règle correcte combine deux attributs indépendants, définis une fois et jamais déduits automatiquement du signe d'une valeur observée :

nature (charge | produit) — attribut sur le nœud de dimension (compte), au même titre que les autres DimAttribute (cf. docs/spec-onboarding-entreprise.md, étape "création des attributs")
conventionSigne (signe_comptable | valeur_absolue) — attribut au niveau de la connexion/source (cf. docs/meta-modele-dimensions.md), propre à la façon dont cette entreprise exporte ses données

multiplicateur =
  nature = 'produit'                                   → +1
  nature = 'charge' ET convention = 'signe_comptable'   → +1   (charge moins négative = favorable)
  nature = 'charge' ET convention = 'valeur_absolue'    → -1   (charge plus petite en absolu = favorable)

favorable = (valeur − référence) × multiplicateur > 0

Ne jamais implémenter cette coloration en se basant uniquement sur le signe du delta brut — cette version plus simple casse dès qu'une source charge ses données en valeur absolue.

Bloc de restitution générique (référence insérée dans un TDB)

interface BlocRestitution {
  id: string
  type: 'kpi' | 'pastille' | 'graphique' | 'vue'
  definitionId: string            // référence vers KpiDefinition / PastilleDefinition / GraphiqueDefinition / vue existante
  position: { x, y, largeur, hauteur }  // placement sur le canevas du TDB
}

interface TableauDeBord {
  id: string
  nom: string
  blocs: BlocRestitution[]
}

Aucune configuration de calcul ne vit dans BlocRestitution — tout est dans la définition référencée. Un TDB devient un pur assembleur de références + mise en page.

GraphiqueDefinition (nouveau, pour les graphiques autonomes hors Vue)

interface GraphiqueDefinition {
  id: string
  nom: string
  type: 'waterfall' | 'courbe' | 'treemap' | 'barres'
  source: { connectionId, axisField, filtres? }
  axeGroupement?: string          // ex: par établissement, par mois
}

Si un graphique est simplement l'extrait d'une Vue existante (ex. la cascade P&L déjà en waterfall dans une Vue), il n'a pas besoin de GraphiqueDefinition séparée : le bloc type: 'graphique' peut alors référencer directement une Vue avec un mode d'affichage graphique plutôt qu'une nouvelle entité.

4. Onglet de préparation des Pastilles (nouveau)

Sur le modèle de l'onglet Indicateurs (KPI), un nouvel onglet Pastilles permet de :

Créer une pastille (mesure via sélection d'un ou plusieurs nœuds DimNode dans un TreePicker, filtre complémentaire, comparaison, unité, titre, visuel), via un wizard à 3 étapes (Mesure, Nom + comparaison, Visuel) — plus court que le wizard KPI puisqu'il n'y a ni numérateur/dénominateur ni seuils de gestion. L'étape Visuel couvre : le type d'affichage (catalogue élargi, cf. docs/spec-parametres-mise-en-forme.md section 6), la position/poids/taille du titre (défaut : haut, normal, normal), et un aperçu en lecture seule de la couleur — dérivée automatiquement du domaine de la mesure, pas de sélecteur de couleur dans le wizard (cf. docs/spec-parametres-mise-en-forme.md section 3).
Lister les pastilles existantes, les modifier, voir dans quels TDB elles sont utilisées avant suppression (éviter de casser un TDB en supprimant une pastille encore référencée).

5. Insertion dans un TDB

En mode édition d'un TDB, un bouton Insérer ouvre un choix à 4 entrées :

Insérer un KPI → sélection dans la bibliothèque KPI existante
Insérer une pastille → sélection dans la bibliothèque Pastilles (nouvelle)
Insérer un graphique → sélection dans la bibliothèque Graphiques ou parmi les Vues en mode graphique
Insérer une vue → sélection parmi les Vues existantes, insérée sous forme de miniature

Aucune configuration ad hoc ne doit rester possible dans cet écran — si l'utilisateur veut une pastille qui n'existe pas encore, il doit être renvoyé vers l'onglet Pastilles pour la créer, puis revenir l'insérer. Ça évite de recréer deux mécanismes de configuration pour le même objet.

KPI, Pastilles et Graphiques sont regroupés sous une seule entrée de navigation Bibliothèque (niveau Modeleur, cf. docs/spec-reorganisation-bandeau.md), plutôt que trois entrées séparées dans le bandeau. Chacun garde son propre onglet de préparation à l'intérieur de cette entrée, mais l'utilisateur comprend d'un coup d'œil que ce sont trois variantes d'un même principe : préparer un objet réutilisable, l'insérer ensuite dans un TDB.

5ter. Flux de création d'un graphique — depuis la vue pivot, pas depuis la Bibliothèque

Deux approches étaient possibles : créer d'abord le graphique dans Bibliothèque puis lui choisir une source (rupture de flux, l'utilisateur quitte l'écran de travail), ou l'insérer directement depuis la vue pivot en cours de construction (flux naturel, façon tableur : on construit un pivot, on ajoute un graphique juste à côté).

Flux retenu : insertion depuis la vue pivot, avec création automatique de la définition en arrière-plan.

L'utilisateur construit sa vue pivot normalement (lignes, colonnes, mesure).
Bouton « Insérer un graphique » dans l'écran pivot → choix du modèle (waterfall, courbe, treemap, barres).
Le graphique s'affiche à côté du tableau, sur la même page — pas de changement d'écran.
En arrière-plan, cette action crée une GraphiqueDefinition référençant la configuration du pivot au moment de la création (lignes/colonnes/mesure/filtres figés à cet instant).
Ce graphique apparaît alors aussi dans l'onglet Bibliothèque, disponible pour insertion dans n'importe quel TDB — sans que l'utilisateur ait eu à naviguer vers la Bibliothèque pour l'y créer.

Ce flux évite la rupture de contexte d'une création préalable dans la Bibliothèque, tout en préservant la réutilisabilité : la définition existe dès la première insertion, pas seulement si l'utilisateur pense à l'enregistrer explicitement. C'est le même principe que la migration assistée des pastilles ad hoc (section 7) — créer l'objet réutilisable au moment naturel de son usage, pas comme une étape administrative séparée.

Point de vigilance : si la vue pivot source est ensuite modifiée par son auteur (changement de lignes/colonnes), le graphique déjà créé ne doit pas se recalculer silencieusement sur une configuration différente — il garde la configuration figée au moment de sa création (cf. point 4). Une modification du pivot source n'affecte donc pas les graphiques déjà insérés dans des TDB ; pour refléter un changement, l'utilisateur doit créer un nouveau graphique ou explicitement mettre à jour la définition existante.

KPI et Pastille : affichage direct en place, pas de clic pour approfondir (ce sont des objets de synthèse, leur rôle est d'être lus d'un coup d'œil).
Graphique et Vue : la miniature est cliquable et ouvre l'écran détaillé correspondant (le graphique en plein format, ou la Vue complète avec son tableau). Comportement cohérent avec un dashboard qui sert de point d'entrée vers le détail, pas de finalité en soi.

7. Migration des pastilles existantes (copier-coller → bibliothèque)

Les pastilles actuellement dupliquées par copier-coller dans différents TDB doivent être reprises, pas recréées de zéro :

En mode édition d'un TDB existant, chaque pastille ad hoc actuelle propose une action "Enregistrer comme pastille réutilisable" qui crée une PastilleDefinition à partir de sa configuration actuelle.
Une fois enregistrée, la pastille ad hoc dans le TDB est remplacée par un BlocRestitution de type pastille référençant cette nouvelle définition.
Pas de migration automatique en masse proposée dans un premier temps — le risque de dédupliquer par erreur deux pastilles visuellement identiques mais configurées différemment (ex. une "Marge brute" filtrée sur un établissement précis) est réel ; mieux vaut une reprise assistée manuellement, TDB par TDB.

8. Niveau de droits (cohérence avec `docs/spec-reorganisation-bandeau.md`)

Onglet Pastilles (préparation) : Modeleur, au même niveau que l'onglet Indicateurs (KPI) — cohérence avec l'objectif d'autonomie du CDG.
Insertion dans un TDB (édition) : Modeleur, déjà couvert par saisie/views en édition dans le modèle de droits actuel — à vérifier si un accès dédié folders.pastilles est nécessaire ou si ça peut rester rattaché à la permission d'édition de TDB existante.

9. Phasage suggéré

Étape 1 : modèle PastilleDefinition + onglet de préparation (wizard 3 étapes, incluant le choix de visuel), sans encore toucher à l'insertion dans les TDB.
Étape 2 : modèle BlocRestitution générique + refonte du bouton d'édition de TDB pour insérer des références plutôt que des configurations en dur (KPI et Pastille d'abord, les deux bibliothèques existant déjà à ce stade).
Étape 3 : extension du mécanisme d'insertion aux Graphiques et Vues (miniature cliquable → détail).
Étape 4 : parcours de migration assistée des pastilles ad hoc existantes vers des PastilleDefinition (section 7).

10. Point de vigilance

Le risque principal est de sous-estimer le nombre de pastilles ad hoc déjà dupliquées dans les TDB existants (Serenis notamment) — avant de lancer l'étape 4, un inventaire rapide (combien de pastilles distinctes, combien de duplications visuellement identiques) permettrait de calibrer l'effort réel de reprise plutôt que de le découvrir en cours de migration.

Bibliothèque d'objets de restitution — Pastilles, KPI, Graphiques, Vues ​

1. Objectif ​

2. Les 4 types d'objets insérables ​

3. Modèle de données ​

PastilleDefinition (nouveau) ​

Bloc de restitution générique (référence insérée dans un TDB) ​

GraphiqueDefinition (nouveau, pour les graphiques autonomes hors Vue) ​

4. Onglet de préparation des Pastilles (nouveau) ​

5. Insertion dans un TDB ​

5bis. Regroupement navigation — entrée « Bibliothèque » ​

5ter. Flux de création d'un graphique — depuis la vue pivot, pas depuis la Bibliothèque ​

7. Migration des pastilles existantes (copier-coller → bibliothèque) ​

8. Niveau de droits (cohérence avec docs/spec-reorganisation-bandeau.md) ​

9. Phasage suggéré ​

10. Point de vigilance ​