Les fiches CEE sont gérées dans l'onglet Fiches. Chaque fiche représente un type d'opération CEE (ex : BAR-TH-171, RES-EC-104).

Champs principaux

• Numéro : identifiant unique de la fiche (ex : BAR-TH-171).
• Libellé : description lisible.
• Code prestation : associe la fiche à un code prestation pour la résolution automatique depuis la référence de lot.
• Modèle PP / PM : modèle de synthèse à utiliser pour chaque type (particuliers / professionnels).
• Modèle PP 100% / PM 100% : modèles dédiés aux synthèses 100% (si éligible).
• Automatique : si coché, les compteurs sont validés automatiquement sans intervention. Si décoché, le job passe en pending_review pour validation manuelle.
• Analyse PDF : si coché, les rapports PDF des missions sont téléchargés depuis SharePoint et analysés pour en extraire des données (voir section Extraction PDF).
• Éligible 100% : si coché, la fiche est disponible pour les synthèses en mode 100%.
• ⚠ Configuration non terminée : à cocher tant que la fiche n'est pas pleinement configurée (mapping incomplet, fiche en cours de mise au point, modèle en test...). La fiche apparaît alors en surbrillance jaune avec un picto ⚠ dans la liste, et toute synthèse générée sur cette fiche ajoute un avertissement (visible dans l'historique et dans le champ warnings de la réponse API publique) : « La configuration de la synthèse pour cette fiche n'est pas terminée. Vérifier le contenu des fichiers générés. » À décocher quand la fiche est validée.

Versions de fiches

Chaque fiche peut avoir plusieurs versions avec des dates de début et fin. Le système sélectionne automatiquement la bonne version en fonction de la date d'engagement ou d'intégration du lot. Chaque version peut pointer vers un modèle de synthèse différent.

Résolution automatique

Lors de la génération, la fiche est identifiée automatiquement depuis les informations SharePoint du lot (champ fiche_cee), ou à défaut par parsing du code prestation dans la référence de lot.

L'onglet Clients permet de gérer une liste de clients (donneurs d'ordre).

Saisie

Le nom d'un client doit correspondre exactement au champ Client de la liste SharePoint « Liste des commandes », tel qu'il est dans SharePoint, parenthèse comprise (ex : EDF (Marché des Particuliers)). Sensible à la casse, espaces inclus.

Synthèse avec KPI

Si la coche Synthèse avec KPI est activée, toute synthèse PDF générée pour un lot dont le client correspond à ce nom recevra une 2e page « KPI », à condition que le modèle de synthèse de la fiche ait un mapping KPI configuré (page Mappings KPI). La 2e page contient :

• Le nombre de contrôles réalisés dans le lot
• Un camembert avec la répartition des conclusions (Satisfaisant / Non satisfaisant / Non vérifiable)
• Un camembert avec les points Non satisfaisants observés sur les missions du lot

Si le client n'est pas dans la liste OU n'est pas marqué « Synthèse avec KPI » OU si le modèle n'a pas de mapping KPI rattaché (principal ou secondaire) → pas de 2e page (synthèse PDF inchangée).

Modèles secondaires d'un Mapping KPI

Un mapping KPI est rattaché à un modèle principal (celui qui définit la structure des références de colonnes utilisées dans les points KPI). Mais on peut aussi déclarer des modèles secondaires dans l'éditeur de mapping (page Mappings KPI) — typiquement le modèle PM jumeau du PP.

Cas d'usage : les champs Kizeo sont identiques entre PP et PM, donc le paramétrage KPI est strictement le même. Plutôt que de dupliquer le mapping pour le PM, on liste simplement le modèle PM comme secondaire. Au moment de générer la synthèse d'un lot PM : si le modèle PM est listé comme secondaire d'un KpiMapping, le pipeline relance une 2e passe d'évaluation interne avec le modèle principal (PP) pour produire les compteurs KPI compatibles. Coût : ~1-2 s de calcul supplémentaire, invisible pour l'utilisateur.

Sur la page Fiches CEE, un petit picto histogramme à côté du numéro indique la couverture KPI :

• Vert : tous les modèles rattachés à la fiche (principaux PP/PM + 100% + versions) sont rattachés à un mapping KPI.
• Jaune : certains modèles seulement ont une couverture KPI.
• Pas de picto : aucun mapping KPI ne couvre les modèles de cette fiche.

Les modèles définissent la structure du fichier Excel de synthèse. Ils sont gérés dans l'onglet Modèles.

Colonnes de sortie

Chaque modèle contient une liste ordonnée de colonnes. Pour chaque colonne :

• Position : numéro de la colonne dans l'Excel (A=0, B=1...). Laisser vide pour une colonne intermédiaire (calcul interne, non affichée).
• Label : en-tête de la colonne dans l'Excel.
• Format : texte (défaut), nombre, entier, etc. Détermine le formatage dans l'Excel.
• Couleur en-tête : couleur de fond de l'en-tête (format #RRGGBB).

Colonnes intermédiaires

Les colonnes intermédiaires n'ont pas de position Excel : elles servent uniquement aux calculs internes. Elles sont référencées dans les formules via @{Label}. Utile pour stocker des résultats intermédiaires réutilisés par d'autres formules.

Source de données (mapping)

Chaque colonne est associée à une source de données qui détermine d'où vient la valeur :

Source	Description	Valeur source
command_file	Fichier commande (Excel SharePoint)	Nom exact de la colonne
kizeo	Formulaire Kizeo inspection	Nom du champ Kizeo
kizeo_cpc	Formulaire Kizeo CPC	Nom du champ CPC
sharepoint_list	Liste SharePoint du lot	Nom du champ SharePoint
rapport_pdf	Données extraites du PDF	Clé normalisée du pattern ($PDF.cle)
formula	Formule calculée	Expression (voir section Formules)

Colonne conditionnelle

Une colonne peut être conditionnelle : sa valeur n'est affichée que si la colonne référencée dans condition_col_label vaut "Oui". Sinon, la cellule reste vide.

Bouton Tester

Le bouton Tester le mapping dans l'éditeur de modèle permet de tester une référence de mission. Il applique le même pipeline de mapping et de validation que la génération réelle, et affiche le résultat colonne par colonne avec un code couleur (valeur trouvée, vide, erreur).

Les formules permettent de calculer des valeurs à partir des données sources et d'autres colonnes. Elles sont saisies dans le champ "Valeur source" lorsque le type de source est formula.

Références aux données sources

Référence	Source	Exemple
$CMD.champ	Fichier commande	$CMD.Code postal
$KIZ.champ	Kizeo inspection	$KIZ.mission_realisable
$KIZ_CPC.champ ou $CPC.champ	Kizeo CPC	$KIZ_CPC.conclusion_generale
$SP.champ	Liste SharePoint	$SP.Statut
$PDF.champ	Rapport PDF extrait	$PDF.Zone_climatique
$KIZL.champ	Kizeo (label du champ)	$KIZL.type_isolant
#A, #B, #C...	Colonne de sortie par lettre	#A = 1re colonne non-intermédiaire
@{Label}	Colonne intermédiaire par label	@{Surface totale}

Fonctions disponibles

Fonction	Description
IF(cond; vrai; faux)	Condition simple
IFS(c1; v1; c2; v2; ...)	Conditions multiples (1re vraie retenue)
AND(a; b) / OR(a; b) / NOT(a)	Opérateurs logiques
UPPER / LOWER / TRIM	Manipulation de texte
LEFT(t; n) / RIGHT(t; n) / MID(t; d; l)	Extraction de sous-chaîne
LEN(texte)	Longueur du texte
SEARCH(cherche; dans)	Position de cherche dans dans (1-based), insensible à la casse ; 0 si non trouvé. Aligné sur Excel.
FIND(cherche; dans)	Position de cherche dans dans (1-based), sensible à la casse ; 0 si non trouvé. Aligné sur Excel.
REPLACE(t; ancien; nouveau)	Remplace dans le texte
CONCAT(a; b; ...)	Concaténation
COALESCE(a; b; ...)	1re valeur non-vide
ABS / INT / MOD / ROUND	Fonctions numériques
MIN(a; b) / MAX(a; b)	Minimum / maximum
TEXT(nombre; format)	Formatage numérique
ISNUMBER(val) / ISBLANK(val)	Tests de type
ZONE_CLIMATIQUE(cp)	Déduit H1/H2/H3 depuis un code postal
CHAR(code)	Caractère ASCII
DATE_EST_POSTERIEURE_A(date; date_ref)	Vrai si date ≥ date_ref (inclusif). Gère texte, serial Excel et dates réelles ; faux si une date est vide/illisible.

Opérateurs de comparaison

=, != (ou <>), <, >, <=, >=

Le séparateur d'arguments peut être le point-virgule ; ou la virgule ,.

Évaluation itérative

Les formules sont évaluées en 2 phases :

1. Phase 1 : toutes les valeurs brutes (non-formules) sont renseignées.
2. Phase 2 : les formules sont évaluées en boucle (jusqu'à 10 itérations) jusqu'à stabilisation. Cela permet à une formule de référencer le résultat d'une autre formule, même si celle-ci est définie plus bas dans le modèle.

Types de validation

Chaque colonne du modèle peut avoir un type de validation optionnel :

• Entier : la valeur doit être un nombre entier.
• Décimal : la valeur doit être un nombre décimal.
• Liste de valeurs : la valeur doit faire partie d'une liste prédéfinie (saisie ligne par ligne dans le paramètre de validation).

Saisie libre auth. — sous le sélecteur de type de validation, un toggle permet d'autoriser l'utilisateur à forcer une valeur hors contrainte lors de la validation PDF manuelle (coche Forcer la saisie dans la modale). Désactivé par défaut sur tous les mappings existants. À activer uniquement sur les colonnes où l'utilisateur doit pouvoir écrire une valeur libre (ex : mention spéciale, cas non prévu).

Source « Saisie manuelle »

Dans le mapping, la source Saisie manuelle signifie que la colonne n'a aucune source automatique : elle est toujours demandée à l'utilisateur lors de l'étape de validation manuelle (comme un champ PDF non trouvé).

• Pas de valeur source à renseigner dans le mapping.
• Validation de données (Entier / Décimal / Liste de valeurs) paramétrable normalement, ainsi que Saisie libre auth..
• Condition Si # = Oui respectée : si la condition n'est pas remplie, la valeur reste vide et aucune saisie n'est demandée.
• Déclenche l'étape de validation manuelle même sur une fiche sans Analyse PDF. Dans ce cas, la modale ne montre pas le panneau PDF à droite.
• Sur une fiche avec Analyse PDF, le rapport PDF reste affiché à côté (sans surlignage pour les colonnes Saisie manuelle).

Extraction PDF

Lorsque Analyse PDF est activée sur la fiche, les rapports PDF de chaque mission sont téléchargés depuis SharePoint et analysés automatiquement.

La configuration des patterns d'extraction se fait dans l'onglet PDF Templates. Pour chaque pattern :

• Texte du pattern : le texte à rechercher dans le PDF (en-tête de colonne, label...).
• Label : clé de stockage pour la valeur extraite. Utilisée pour la référence $PDF.cle dans les formules (normalisée automatiquement : espaces → _, caractères spéciaux supprimés).
• Position :
  • right : 1re cellule non-vide à droite du pattern.
  • below : cellule en dessous du pattern.
  • checkboxes : collecte les cases cochées à droite du pattern (gère les cellules fusionnées et les lignes de continuation multi-lignes). Symboles reconnus : ☑ ☒ ✓ ✗ [x].

Smart cleaning (nettoyage intelligent)

Lorsqu'une colonne a une validation liste de valeurs, le système cherche automatiquement les valeurs autorisées dans le texte extrait du PDF :

• Si 1 seule valeur trouvée → retenue automatiquement.
• Si 2+ valeurs trouvées (ambiguïté) → la valeur brute est conservée et une validation manuelle est demandée.
• Les sous-chaînes sont éliminées intelligemment : si "Non vérifiable" est trouvé, "Non" seul n'est pas compté comme une correspondance indépendante.

Endpoint de debug PDF

L'endpoint GET /api/generation/debug-pdf/{ref_mission} permet de visualiser les tables brutes et le texte extrait par pdfplumber pour une mission donnée. Utile pour diagnostiquer les problèmes d'extraction (structure des tables, caractères spéciaux, colonnes vides).

Définition globale

Les compteurs sont définis globalement dans l'onglet Compteurs. Chaque compteur a :

• Clé : identifiant unique utilisé comme balise dans le PDF (ex : nb_operations, nb_cpc).
• Label : libellé affiché dans la modale de validation et dans le PDF.
• Ordre : position d'affichage.

Association aux modèles

Dans l'éditeur de modèle, chaque compteur peut être associé à une condition de comptage :

• Référence colonne : colonne de sortie à évaluer (ex : #A).
• Opérateur : eq (égal), ne (différent), gt (supérieur), lt (inférieur)...
• Valeur : valeur de comparaison.
• Conditions alternatives (OU) : liste JSON de conditions supplémentaires. Une ligne est comptée si au moins une condition est remplie.

Un compteur sans condition compte toutes les lignes (utilisé pour nb_operations qui remplace l'ancien nb_total).

Authentification

Toutes les requêtes API nécessitent un token Bearer dans le header Authorization :

Authorization: Bearer votre-token-api

Les tokens sont créés et gérés dans l'onglet Tokens API. Chaque token a un nom, une date d'expiration optionnelle, et peut être révoqué à tout moment.

Endpoints disponibles

Méthode	Endpoint	Description
POST	/public-api/generation	Génération synchrone (sans upload SP)
POST	/public-api/generation/with-sharepoint	Génération + upload SharePoint auto
POST	/public-api/generation/100pct	Génération 100% par missions
POST	/public-api/generation/100pct/with-sharepoint	Génération 100% + upload SP
POST	/public-api/generation/{id}/save-sharepoint	Upload SP manuel d'un job existant
GET	/public-api/generation/{id}/download/excel	Télécharger le fichier Excel
GET	/public-api/generation/{id}/download/pdf	Télécharger le fichier PDF

Corps de requête (génération standard)

{
  "lot_reference": "20260303-07-DIVERS-INS-EDF",
  "user": "prenom.nom@spekty.fr",
  "output_filename": "REF-CLIENT-1234"
}

output_filename (optionnel) : si renseigné, les fichiers produits sont nommés Synthèse-<output_filename>.pdf et Synthèse-<output_filename>.xlsx au lieu du format par défaut Synthèse-<lot_reference> <fiche_numero>.<ext>. Le nom uploadé sur SharePoint suit le nom local. Sans effet sur le contenu des fichiers. S'applique aux endpoints /generation et /generation/with-sharepoint. Cette option n'est pas disponible via l'interface web. Les caractères interdits dans les noms de fichiers Windows/SharePoint (\ / : * ? " < > |) sont automatiquement remplacés par _.

Corps de requête (génération 100%)

{
  "mission_references": ["REF-001", "REF-002"],
  "fiche_numero": "BAR-TH-171",
  "type_pp_pm": "PP",
  "output_filename": "Ma synthese",
  "user": "prenom.nom@spekty.fr"
}

Réponse type

{
  "status": "completed",
  "job_id": 123,
  "warnings": [],
  "excel_download_url": "/public-api/generation/123/download/excel",
  "pdf_download_url": "/public-api/generation/123/download/pdf",
  "sharepoint_excel_url": "https://...",
  "sharepoint_pdf_url": "https://..."
}

Timeout et erreurs

Le timeout des requêtes API est de 5 minutes (300 secondes). En cas de timeout serveur Kizeo (erreur 504), le message d'erreur indique s'il s'agit du formulaire d'inspection ou CPC, et recommande de réessayer dans quelques minutes.

L'outil KPI est une fonctionnalité annexe à la génération de synthèses. Il permet d'extraire un fichier Excel décomptant les opérations Non satisfaisantes par point KPI configuré, sur un périmètre filtré (clients, fiches CEE, période).

Pré-requis

• Un Mapping KPI doit être configuré sur le modèle de synthèse de chaque fiche concernée (page Mappings KPI).
• Les configurations existantes (clients, fiches, modèles, formulaires Kizeo, mappings de synthèse) sont réutilisées telles quelles. Aucune modification n'est nécessaire dans les paramétrages existants.

Lancer une analyse

1. Aller dans l'onglet KPI.
2. Saisir un ou plusieurs clients (un par ligne, ou séparés par ,/;). Doit correspondre exactement au champ Client de la liste SharePoint Liste des contrôles.
3. Sélectionner une ou plusieurs fiches CEE.
4. Renseigner les dates de début et de fin. Les missions retenues seront celles dont la Date SharePoint est dans cet intervalle.
5. Cliquer sur Lancer l'analyse KPI. Le job s'exécute en arrière-plan, l'historique se met à jour automatiquement.

Filtrage des missions

Les missions sont identifiées sur la liste SharePoint Liste des contrôles selon les critères :

• Statut = Terminé
• Client ∈ liste saisie
• Fiche_CEE ∈ fiches sélectionnées
• Date ∈ intervalle [date_debut, date_fin]

Choix du modèle et du mapping par lot

La résolution se fait par lot, à la date d'intégration du lot (les 8 premiers caractères AAAAMMJJ de la référence). Pour chaque lot :

• on prend le modèle de la FicheVersion active à cette date (PP en priorité, sinon PM) ;
• on cherche le mapping KPI où ce modèle est principal ; sinon où il est secondaire (dans ce cas l'évaluation se fait avec le modèle principal du mapping, comme pour la 2e page de synthèse) ;
• si ce modèle n'est rattaché à aucun mapping, on remonte vers les versions plus récentes jusqu'à en trouver un ;
• si aucun modèle (sur toutes les versions) n'a de mapping, les données du lot sont ignorées avec un avertissement.

Ainsi, sur une période à cheval sur un changement de modèle (frontière par date d'intégration), chaque lot est compté avec le bon mapping. Les comptages sont ensuite agrégés par libellé de point KPI au niveau de la fiche (même libellé entre deux modèles → additionné). Les modèles 100% sont exclus.

Limitation : seules les frontières par date d'intégration sont gérées. Pour une fiche dont les versions basculent par date d'engagement, l'outil en lot ne dispose pas de cette date (il ne lit pas les fichiers commande) et utilise la date d'intégration comme approximation.

Récupération des données

• Seules les données Kizeo inspection sont récupérées (pas de CPC, pas de fichier commande, pas de PDF).
• Multi-formulaires implicite : tous les formulaires Kizeo inspection du code prestation sont interrogés (sans filtre date), comme en mode "Multi-formulaires Kizeo".
• En cas de doublons Kizeo : même logique que pour la synthèse, mais lorsqu'un blocage serait déclenché, on prend la donnée la plus récente (create_time).
• Les colonnes du modèle dont la source est Fichier commande, Liste SharePoint, Rapport PDF, Saisie manuelle ou Kizeo CPC sont évaluées comme vides (non utilisées par l'outil KPI).

Mappings KPI

Onglet Mappings KPI. Un mapping est rattaché à un modèle principal (qui définit la structure des références de colonnes utilisées dans les points), et éventuellement à un ou plusieurs modèles secondaires.

Chaque mapping contient une liste ordonnée de points Non satisfaisant. Pour chaque point :

• Libellé : nom du point (ex: "RDV non honoré").
• Catégorie : à choisir parmi Documentaire, Eligibilité, Paramètre de la prime, Non qualité manifeste.
• Condition principale : colonne du modèle + opérateur + valeur.
• Conditions OU : 0 à N conditions supplémentaires. Si la principale OU une condition OU matche, l'opération est comptée.

Opérateurs disponibles : égal, différent, contient, commence par, vide, non vide.

Modèles secondaires (rattachements multiples)

Un mapping KPI peut être appliqué à plusieurs modèles de synthèse via la liste de modèles secondaires. Cas d'usage typique : un modèle ... PP et son jumeau ... PM partagent les mêmes champs Kizeo, donc le paramétrage KPI est identique. Plutôt que de dupliquer le mapping, on rattache le modèle PM en secondaire du mapping principal PP.

Dans l'éditeur, sous le nom du mapping, la zone Modèles secondaires liste les rattachements actuels sous forme de chips. Pour en ajouter un, cliquer sur + Rattacher un modèle secondaire : une modale propose le sous-ensemble des modèles disponibles. Pour en retirer un, cliquer sur le × du chip correspondant.

Règle d'unicité : un modèle ne peut être rattaché qu'à un seul mapping à la fois, en principal ou en secondaire. Conséquences :

• Les modèles déjà rattachés ailleurs ne sont pas proposés dans la modale + Rattacher.
• À la création d'un mapping, si le modèle principal choisi est actuellement secondaire d'un autre mapping, une confirmation est demandée. Si elle est acceptée, le modèle est automatiquement détaché de l'ancien mapping puis devient le principal du nouveau.
• Si le modèle principal choisi est déjà principal d'un autre mapping, la création est refusée (il faut d'abord supprimer ou renommer l'ancien).

À l'exécution sur un lot dont le modèle de synthèse est un secondaire : le pipeline relance une 2e passe d'évaluation en interne avec le modèle principal, afin que les références de colonnes du mapping (qui suivent la structure du principal) trouvent leurs valeurs. Coût ~1-2 s, invisible pour l'utilisateur.

Format du fichier Excel de sortie

Col	Contenu
A	Fiche CEE
B	Catégorie
C	Libellé du point Non satisfaisant
D	Nombre d'opérations Non satisfaisantes

Une ligne par couple (fiche CEE × point KPI), y compris les compteurs à 0. À droite des données, un tableau cumul par catégorie + un camembert de répartition.

Non interférence avec la synthèse

Cette fonctionnalité n'a aucun impact sur la génération de synthèses : pas de modification du pipeline existant, pas de modification des mappings de colonnes, des modèles, des fiches ou des formulaires Kizeo.

Les paramètres globaux sont configurés en haut de cette page :

• Token API Kizeo : token d'authentification pour l'API Kizeo Forms. Utilisé pour récupérer les données des formulaires d'inspection et CPC.
• URL site SharePoint : URL du site SharePoint contenant les fichiers de commande, les rapports PDF et les listes de contrôles.
• Chemin fichier commande : chemin relatif dans SharePoint vers le dossier contenant les fichiers de commande (ex : Documents partagés/Commandes).
• ID liste des contrôles : identifiant de la liste SharePoint utilisée pour lire les infos du lot et des missions.
• Client ID SharePoint (Azure) : identifiant de l'application Azure AD utilisée pour l'authentification SharePoint.
• Client Secret SharePoint : secret de l'application Azure AD.

Le webhook Power Automate est configuré via une variable d'environnement serveur (POWER_AUTOMATE_WEBHOOK_URL), non modifiable depuis l'interface.

Nettoyage automatique

Les jobs de plus de 7 jours sont automatiquement supprimés (fichiers Excel/PDF et entrées en base), ainsi que les tokens API révoqués.