Bibliothèque de KPI génériques + visuels associés — Spécification technique

1. Objectif

Permettre à un client de calculer un KPI de type "remplissage/rendement" (TO, TO permanent, TO temporaire, TRS, taux d'avancement...) en mappant simplement ses propres champs à une formule générique préexistante, sans développement spécifique par secteur. Chaque KPI de cette famille doit s'accompagner d'un visuel par défaut cohérent (jauge), sans configuration manuelle du client.

Ce chantier s'appuie directement sur :

• Le méta-modèle (docs/meta-modele-dimensions.md), bloc "Référentiels"
• Le pattern générique déjà formalisé : Taux = Volume réalisé (fait transactionnel) / Capacité théorique disponible (référentiel)
• Le constat que ce pattern existe à l'identique dans plusieurs secteurs (EHPAD : TO, agroalimentaire : TRS, BTP : taux d'avancement)

2. Prérequis modèle de données (déjà en place)

D'après l'exploration Claude Code (schéma en étoile Movement) :

• Le référentiel (dénominateur) est déjà stocké dans Movement via la connexion type saisie (kind=statistique), consolidation en moyenne
• Le volume réalisé (numérateur) est stocké dans Movement via les connexions sources classiques (kind financier ou métier)
• Le lien se fait par établissement + période (mois), conformément à la maille actuelle

Aucune migration de stockage nécessaire pour ce chantier : il s'agit d'une couche de définition de calcul et de restitution par-dessus l'existant.

3. Modèle de définition d'un KPI générique

Un KPI de la famille "remplissage/rendement" doit être défini par une structure de configuration, pas codé en dur. Proposition de schéma :

KpiDefinition {
  id: string
  label: string                    // nom métier choisi par le client, ex: "Taux d'occupation"
  pattern: "remplissage_rendement"  // extensible à d'autres patterns génériques plus tard
  numerateur: {
    connectionId / domain: string  // source du volume réalisé
    axisField: string              // champ Movement à sommer (ex: montant, quantité)
    filtres?: { axis, code }[]     // ex: segment "type d'hébergement" = permanent
  }
  denominateur: {
    connectionId: string           // référentiel (connexion type "saisie")
    axisField: string
    ajustements?: { axisField, operation: "soustraction" }[]  // ex: jours de fermeture
    consolidation: "moyenne" | "somme"
  }
  perimetre: {
    dimension: "etablissement" | autre axe structurel
    niveauHierarchique?: string    // permet le calcul à différents niveaux d'agrégation
  }
  visuel: {
    type: "jauge_circulaire" | "barre_progression" | "valeur_seule" | "anneau" | "jauge_horizontale_seuils" | "valeur_avec_fleche_tendance"   // défaut : jauge_circulaire ; catalogue élargi cf. docs/spec-parametres-mise-en-forme.md
    // 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
  }
  seuils?: { bon: number, alerte: number, critique: number }  // pour la coloration du visuel (tous types confondus)
}

4. Exemples d'instanciation (à partir des cas déjà traités)

TO global (EHPAD)

numerateur: Movement (Serenis Métier, journées facturées)
denominateur: Movement (Saisie Rapport, capacité) 
              - Movement (Saisie Rapport, jours de fermeture)
perimetre: etablissement

TO permanent / TO temporaire (EHPAD) Même structure que TO global, avec filtre supplémentaire sur le segment "type d'hébergement".

TRS (agroalimentaire, cas futur)

numerateur: Movement (temps de production réel × cadence réelle)
denominateur: Movement (temps d'ouverture théorique × cadence nominale)
perimetre: site de production

Illustration que la même définition KpiDefinition sert aux deux secteurs — seuls les mappings de champs changent, pas la formule ni le moteur de calcul.

5. Moteur de calcul

• Réutiliser le moteur pivot() existant pour charger et consolider numérateur et dénominateur séparément selon leurs règles de consolidation propres (somme pour le numérateur, moyenne pondérée pour le référentiel — logique déjà en place pour les indicateurs de stock)
• Calculer le ratio uniquement après consolidation à la maille et au niveau hiérarchique demandés (jamais ratio de ratios, toujours somme/somme au niveau agrégé pour rester statistiquement correct)
• Prévoir un cache ou une matérialisation si le calcul s'avère coûteux sur de gros volumes (à évaluer selon perf réelle, pas d'optimisation prématurée)

Fonction calendaire — nombre de jours du mois

Le calcul du dénominateur d'un KPI type TO nécessite le nombre de jours du mois (ex. capacité × jours du mois − jours de fermeture). Cette valeur est calculée, jamais saisie : elle se déduit directement des axes annee et mois déjà existants, sans dimension ni Movement dédié.

joursDansLeMois(annee: number, mois: number): number
// ex: joursDansLeMois(2026, 2) → 28 (année non bissextile)
// ex: joursDansLeMois(2024, 2) → 29 (année bissextile)

Cette fonction s'utilise comme multiplicateur automatique dans le calcul du dénominateur d'un KpiDefinition de type remplissage_rendement :

Capacité théorique = capacité (référentiel)
                      × joursDansLeMois(annee, mois)
                      − jours de fermeture (référentiel, si renseignés)

Aucun champ de configuration ni écran de saisie n'est nécessaire côté client pour cette valeur — elle est implicite dès que la maille mois/année est connue. Si un client facture sur une base de jours d'ouverture (hors jours fériés par exemple) plutôt que sur des jours calendaires, cette distinction reste couverte par le champ existant "jours de fermeture" du référentiel, pas par une nouvelle notion.

6. Interface de configuration (client, no-code) — Wizard de création

Écran de création de KPI, dans le prolongement de l'écran Dimensions/Modélisation existant, structuré en wizard à 4 étapes avec navigation libre (pas strictement séquentielle) et aperçu en direct.

Principe général

• Navigation latérale (liste des 4 étapes), cliquable à tout moment — l'utilisateur peut revenir en arrière ou sauter à une étape déjà remplie sans repasser par les précédentes.
• Panneau d'aperçu permanent (jauge) affiché en dehors du flux d'étapes, mis à jour en direct à chaque modification (nom, seuils) — l'utilisateur voit l'effet de ses choix avant de valider, plutôt qu'à la fin seulement.
• Vocabulaire toujours en langage métier : "Volume réalisé" / "Capacité" plutôt que "numérateur" / "dénominateur" (jamais exposer la terminologie technique du modèle de données au client).

Étape 1 — Modèle

Choix d'un modèle de calcul plutôt que formulaire vide en premier écran, pour réduire la charge cognitive sur le cas le plus fréquent :

• Taux de remplissage (pattern remplissage_rendement, mis en avant par défaut) : volume réalisé / capacité théorique — couvre TO, TRS, taux d'avancement
• Ratio simple : deux valeurs libres, sans notion de capacité (réservé, pour extension future hors périmètre immédiat)
• Personnalisé : formule libre (réservé, hors périmètre immédiat — cf. section 8, Étape 4)

Étape 2 — Volume réalisé (numérateur)

• Sélection de la source (connexion)
• Filtre optionnel par segment (ex. type d'hébergement = permanent, pour un TO permanent/temporaire)

Étape 3 — Capacité (dénominateur)

• Sélection du référentiel (connexion type saisie)
• Ajustement optionnel (ex. soustraire les jours de fermeture)

Étape 4 — Nom et seuils

• Nom du KPI en langage métier (préremplit l'aperçu en direct)
• Seuil de bonne performance (curseur, ex. 90%) et seuil d'alerte (curseur, ex. 75%) — chaque changement recolore immédiatement l'aperçu selon la logique de seuils définie en section 7

Étape 5 — Visuel

• Choix du type d'affichage parmi le catalogue élargi (jauge circulaire par défaut, barre de progression, valeur seule, anneau, jauge horizontale à seuils, valeur avec flèche de tendance — cf. docs/spec-parametres-mise-en-forme.md section 6) — l'aperçu en direct change immédiatement de type au clic
• Aperçu en lecture seule de la couleur d'accent, dérivée automatiquement du domaine de la mesure (cf. docs/spec-parametres-mise-en-forme.md section 3) — pas de sélecteur de couleur dans cette étape ; un lien renvoie vers Paramètres / Mise en forme si l'utilisateur veut changer la couleur du domaine (effet global, pas local à ce KPI)
• Bouton final "Créer le KPI" (pas "Suivant" sur cette dernière étape, pour signaler l'action de validation)

Aperçu en direct — comportement

• L'aperçu utilise une valeur d'exemple (donnée réelle si disponible sur le périmètre par défaut, sinon valeur de démonstration explicite) pour montrer le rendu final sans attendre la fin du wizard.
• La coloration suit les seuils en cours de saisie à l'étape 4 en temps réel (vert si ≥ seuil bon, orange si entre alerte et bon, rouge si < alerte), quel que soit le type de visuel choisi à l'étape 5.

7. Visuel : catalogue de types disponibles

Composants réutilisables dans le design-system, sélectionnables au wizard (étape 5) — catalogue détaillé dans docs/spec-parametres-mise-en-forme.md section 6 :

• Jauge circulaire (HGauge) : arc de progression, valeur au centre — défaut recommandé pour les KPI de type remplissage/rendement.
• Barre de progression (HBarreProgression) : bande horizontale, plus compacte, adaptée à un affichage en liste ou en tableau plutôt qu'en carte isolée.
• Valeur seule : le chiffre affiché en grand avec sa couleur de seuil, sans représentation graphique — adapté aux emplacements très contraints.
• Anneau, jauge horizontale à seuils, valeur avec flèche de tendance : variantes complémentaires, cf. catalogue élargi.

Points communs à tous les types :

• Couleur dynamique selon les seuils définis dans KpiDefinition (vert/orange/rouge, jamais autre chose pour cet usage sémantique)
• Couleur d'accent (hors zone de seuil) : dérivée automatiquement du domaine de la mesure, jamais éditable individuellement (cf. docs/spec-parametres-mise-en-forme.md)
• Doit s'insérer dans une HCard pour affichage en dashboard (TDB / Synthèse)
• Prévoir un état "donnée manquante" explicite (ex. référentiel non saisi pour la période) plutôt qu'un 0% trompeur

8. Phasage suggéré

1. Étape 1 : modèle KpiDefinition + moteur de calcul pour le pattern remplissage/rendement, sans UI de configuration (câblé en dur pour valider le calcul sur le cas EHPAD existant)
2. Étape 2 : composant visuel HGauge + intégration dans un dashboard existant (Synthèse)
3. Étape 3 : écran de configuration no-code pour que le client crée son propre KPI sans intervention développeur
4. Étape 4 : extension à d'autres patterns génériques si besoin (ex. ratio simple, écart en valeur, évolution en %) — non prioritaire tant que le pattern remplissage/rendement n'est pas validé en usage réel

9. Point de vigilance

Ce chantier reste compatible avec la maille mois actuelle et la décision prise sur la Phase 5 "structurelle sans grain fin" (hiérarchie Structure→Salarié/Résident avec attributs, sans grain transactionnel journalier). Le calcul de KPI remplissage/rendement fonctionne à la maille mois sans dépendre des entités individuelles — les deux chantiers sont indépendants et peuvent avancer en parallèle.