# Guide utilisateur : KPI finance

Documentation utilisateur de la feuille KPI finance (`/kpi/finance`), même présentation que les guides précédents (charte ADLER, encadrés, figures numérotées). Le détail technique est dans `docs/kpi_finance.md`.

## Fichiers livrés

- `docs/Guide_utilisateur_kpi_finance.docx`
- `docs/Guide_utilisateur_kpi_finance.pdf` (7 pages, 8 figures)

## Contenu

1. Rôle de la feuille (basée sur les factures, pas les BL), accès (menu Statistiques > KPI finance, droit « KPI finance / Synthèse client » qui ouvre aussi l'onglet Synthèse du client).
2. Filtres Société / Année (année en cours du 1er janvier à aujourd'hui), ligne Période, règles communes (factures validées ou non, avoirs déduits du CA sans retirer de volume, béton = lignes de type béton, N-1 au jour près).
3. Les 4 cartes (CA, avoirs, volume béton, échues non réglées), couleurs de l'évolution, état « à ce jour » des échues, fenêtres de détail et leurs colonnes.
4. CA HT mensuel N / N-1 complète et répartition du CA par type de ligne.
5. Top 10 clients (CA sur l'entête de facture, avoirs déduits) et chantiers (CA sur les lignes), libellé chantier avec référence.
6. Prix moyen HT et volume de béton par mois sur 3 exercices (découpage selon le début d'exercice de la société, janvier pour « Toutes »).
7. FAQ.

## Points vérifiés dans le code

- `app/Http/Controllers/kpi_finance_controller.php` : `periode()`, `facturesEchuesQuery()` (hors avoirs, reste > 0, échéance < aujourd'hui), top clients en `SUM(signe * facture_total_ht)`, `exercices()`.
- `resources/views/kpi/finance.blade.php` : `evolution()` n'affiche rien si N-1 = 0 ; couleurs inversées pour les avoirs ; titres et colonnes des détails.

## Méthode

- Docx généré avec PHPWord à partir de `guide_commun.php` (scratchpad, non versionné) ; PDF exporté par Word (COM).
- Captures html2canvas dans l'application locale (année 2026, toutes sociétés), via `public/_capture_doc_tmp.php` et `.js`, supprimés à la fin. Les graphiques Chart.js (canvas) n'étant pas recopiés par html2canvas, ils ont été remplacés temporairement par leur image (`canvas.toDataURL()`) le temps de la capture. Dans les détails, seules des lignes de clients sociétés ont été gardées (pas de particuliers).

## Limites des captures

La base locale ne contient pas de factures sur 2025 : les valeurs N-1 sont à 0 et l'évolution en % n'apparaît pas sur les captures (le guide l'explique). Le montant des factures échues est élevé car les règlements ne sont pas tous saisis dans cette base.
