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%.

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.

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(texte; recherche)	Position de la recherche dans le texte
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

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_total, 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_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 par fiche

Pour chaque fiche, l'outil utilise le modèle PP en priorité, sinon le modèle PM. Si la fiche a plusieurs versions (FicheVersion), c'est la version la plus récente (date_debut la plus grande, ≤ date_fin) qui est utilisée. Les modèles 100% sont exclus.

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 seul modèle (relation 1-1).

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.

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.