# Génération facture : regroupement par client / réf. commande client

## Fonctionnalité

Nouvelle présentation de facture **3 = « Une facture par réf commande client »** (libellé de la fiche client et des paramètres) (champ `client_presentation_facture`, en plus de 0 = par BL, 1 = par chantier, 2 = par client).

À la génération (et en préfacturation), les BL d'un client sont regroupés par **référence commande client du BL** (`t_bl.bl_ref_commande`) : une facture par référence.

- La référence est comparée sans les espaces de début/fin et sans tenir compte de la casse (`UPPER(TRIM(...))`).
- Les BL sans référence sont regroupés ensemble sur une facture « sans référence ».
- Le corps de la facture ne change pas : les lignes restent triées par chantier, avec l'en-tête « CHANTIER : … » (et le sous-total chantier si l'option est active) à chaque changement de chantier. Une facture peut donc contenir plusieurs blocs chantier.
- La référence est stockée sur l'en-tête de la facture (`facture_ref_commande`), avec la saisie d'origine du BL.

## Fichiers modifiés

- `database/migrations/2026_10_26_1100_V905001_NB_t_facture_facture_ref_commande.php` : colonne `facture_ref_commande` varchar(55) nullable dans `t_facture` et `t_pre_facture` (les deux tables gardent les mêmes colonnes).
- `public/generation_facture/generation_facture_selectionner_client.php`
  - Boucle principale : `case 3`, copie du cas 2. Il regroupe sur `facture_ref_commande_groupe` au lieu de `t_bl.chantier_id` et filtre aussi sur `$critere_select_bl_facture` (BL sélectionnés), ce qui évite de créer des en-têtes vides.
  - `generer_ligne_facture()` : `case 3`, copie du cas 2 avec le filtre sur la référence du groupe (valeur passée par `$pdo->quote`).
  - `generer_facture_generale()` : l'`INSERT` renseigne `facture_ref_commande` (`null` pour les autres présentations).
- `public/pre_facture/transformer_facture.php` : recopie `facture_ref_commande` de la préfacture vers la facture.
- `resources/views/client/form.blade.php`, `resources/views/client/form_v2.blade.php`, `resources/views/parametre/index.blade.php` : option 4 dans « Présentation facture ».
- `resources/views/facture/form.blade.php` : affiche « Réf. commande client » (lecture seule) dans le cadre Impression quand elle est renseignée.

## Décisions

- Source de la référence : `t_bl.bl_ref_commande` plutôt que `t_commande.commande_ref_client`. Elle existe aussi pour les BL sans commande (pesée, saisie manuelle) et c'est la valeur visible sur le BL.
- Pas de mode « chantier / réf. commande » pour l'instant : seul le cas client / réf. a été demandé.
- `t_facture.chantier_id` reçoit l'un des chantiers du groupe (valeur non agrégée, comme le cas 2). La liste des factures n'affiche le chantier que pour la présentation 1.
- Vérifié sur la base : la présentation 2 produit bien une facture multi-chantiers (191 factures) et aucune facture vide. Les en-têtes sans ligne sont supprimés dans `generer_ligne_facture()`.

## Reste à faire

- PDF : afficher `facture_ref_commande` dans l'en-tête. Le PDF est rendu par le modèle externe (`URL_MODELE_CLIENT`), hors de ce dépôt.
- Facture électronique (CII / Factur-X / Peppol) : la référence de commande (BT-13) n'est pas encore transmise. `extraction_facture_comptant_trait.php` lit encore la référence du premier BL.

---

# Variante 4 : une facture par client, détail par réf commande client

## Fonctionnalité

Valeur **4 = « Une facture par client, détail par réf commande client »**. Le regroupement des factures est celui du cas 2 (une facture par client), sans le chantier. Dans le corps, les lignes sont organisées en blocs par référence (option A validée) :

```
RÉF. COMMANDE : CMD-4587            (ligne 'E')
  CHANTIER : CH001 - ...            (en-tête chantier existant)
    lignes des BL
  CHANTIER : CH014 - ...
    lignes des BL
Sous total réf. commande : CMD-4587 (ligne 'H')

SANS RÉFÉRENCE COMMANDE             (dernier bloc)
  ...
Sous total sans référence commande
```

- Les blocs sont triés par référence normalisée (`UPPER(TRIM)`), le bloc « sans référence » en dernier, puis par chantier comme avant.
- Le sous-total par référence est **toujours** écrit. Il **remplace** le sous-total chantier (option du chantier ignorée dans ce mode), car un même chantier peut apparaître sous plusieurs références.
- L'en-tête chantier est réécrit en tête de chaque bloc de référence, même si le chantier ne change pas.
- Les contributions et les frais de facturation restent en fin de facture, hors référence.
- `t_facture.facture_ref_commande` reste vide, puisque la facture contient plusieurs références.

## Fichiers modifiés

- `database/migrations/2026_10_26_1400_V905001_NB_t_ligne_facture_ligne_facture_ref_commande.php` : colonne `ligne_facture_ref_commande` varchar(55) nullable dans `t_ligne_facture` et `t_ligne_pre_facture`. Elle contient la réf. normalisée sur toutes les lignes générées en mode 4 (`#SANS_REF#` = bloc sans référence), et vide ou NULL ailleurs : `BaseModel` remplace NULL par `''` à chaque enregistrement Eloquent, on ne peut donc pas distinguer NULL de `''`.
- `public/generation_facture/generation_facture_selectionner_client.php`
  - `ecrire_ligne_facture()` : écrit `ligne_facture_ref_commande` à partir de `$GLOBALS['ref_commande_ligne_facture']`. Pour un client non « BL détaillé », la recherche de la ligne à cumuler (même article / chantier / centrale) est limitée à la même réf. Sans cela, les quantités de deux commandes d'un même chantier seraient fusionnées.
  - Nouvelles fonctions `generer_ligne_facture_entete_ref_commande()` (ligne 'E') et `generer_ligne_facture_sous_total_ref_commande()` (ligne 'H', `chantier_id` NULL, somme des lignes tarifées de la réf.).
  - `generer_ligne_facture()` : `case 4` (tri par réf. puis chantier) et gestion du changement de réf. dans la boucle : sous-total de la réf. précédente, 2 lignes vides, en-tête de la nouvelle réf., en-tête chantier forcé. Sous-total de la dernière réf. après la boucle, puis remise à NULL de la globale avant les contributions et les frais.
  - Boucle principale : `case 4` (regroupement par client, filtré sur les BL sélectionnés).
- `public/inc/fonction.inc.php` : `recalculer_sous_totaux_ref_commande()` et `recalculer_sous_totaux_facture()`. Elles sont dans ce fichier et non dans `init.inc.php`, qui est ignoré par git (`.gitignore`, propre à chaque installation) : sinon les scripts legacy planteraient sur les autres environnements. `fonction.inc.php` est chargé par `init.inc.php`.
- `public/facture/valider_ligne_facture.php`, `public/facture/supprimer_ligne_facture.php`, `public/pre_facture/valider_ligne_facture.php`, `public/pre_facture/supprimer_ligne_facture.php` : le recalcul du sous-total chantier ignore les lignes 'H' de réf. (`IFNULL(ligne_facture_ref_commande,'')=''`), puis on appelle `recalculer_sous_totaux_ref_commande()`.
- `app/Http/Controllers/facture_controller.php` : `recalculerSousTotaux()` additionne par `ligne_facture_ref_commande` pour les lignes 'H' de réf.
- `public/pre_facture/transformer_facture.php` : recopie `ligne_facture_ref_commande` sur les lignes.
- Fiche client (`form`, `form_v2`) et paramètres : option 4.

## Décisions

- Type 'H' pour le sous-total de réf. plutôt qu'un nouveau type : environ 23 états excluent les lignes non tarifées par `NOT IN ('E','C','H','B')`, et un nouveau type serait compté dans le CA.
- Réf. transmise à `ecrire_ligne_facture()` par une variable globale (comme les cumuls de contributions) pour ne pas modifier la signature de 30 paramètres et ses appelants.
- Une ligne ajoutée à la main sur une facture en mode 4 n'a pas de réf. : elle n'entre dans aucun sous-total de réf.

## Non testé

Le code passe `php -l`, mais aucune préfacturation réelle n'a été lancée : cela aurait vidé les préfactures en cours de la base de dev et les 4 BL sélectionnés auraient limité la génération.

## Mise à jour du sous-total quand on modifie une facture (prix, quantité)

Le sous-total par référence est recalculé à chaque ajout, modification ou suppression de ligne :

- Laravel (`facture_laravel`) : `valider_ligne`, `supprimer_ligne` et `deduire_acomptes` appellent `recalculerSousTotaux()`. Une ligne 'H' dont la réf. est renseignée est recalculée par `ligne_facture_ref_commande`, sinon par `chantier_id` comme avant.
- Legacy (`public/facture/` et `public/pre_facture/`, `valider_ligne_facture.php` et `supprimer_ligne_facture.php`) : `recalculer_sous_totaux_ref_commande()`.
- Les autres `UPDATE t_ligne_facture` du projet (PDF, exports, comptabilité) ne modifient pas les montants.

Testé sur des lignes factices dans une transaction annulée :
- Laravel : CMD-A = 150, `#SANS_REF#` = 30, et le sous-total chantier sans réf. (lignes NULL et `''`) = 45 ;
- SQL legacy : les sous-totaux de réf. sont recalculés et les sous-totaux chantier ne sont pas touchés.

Ce test a fait apparaître le piège de `BaseModel`, qui transforme NULL en `''` : d'où le marqueur `#SANS_REF#`.

Avoirs : les sous-totaux sont aussi recalculés sur les prix de l'avoir.
- Laravel : `creer_avoir` appelle `recalculerSousTotaux()` (BL, chantier et réf.). `replicate()` recopie déjà `ligne_facture_ref_commande`.
- Legacy (`public/facture/generer_avoir.php`, `public/pre_facture/generer_avoir.php`) : la colonne `ligne_facture_ref_commande` est recopiée, puis `recalculer_sous_totaux_facture()` (`public/inc/fonction.inc.php`) recalcule tous les sous-totaux, comme `recalculerSousTotaux()` côté Laravel : 'B' par `bl_id`, 'H' sans réf. par `chantier_id`, 'H' avec réf. par réf. Testé dans une transaction annulée sur 6 sous-totaux (BL, chantier avec réf. vide ou NULL, réf., `#SANS_REF#`) : tous justes.

## Fonctions legacy versionnées

`public/inc/init.inc.php` est ignoré par git (propre à chaque installation). Les fonctions dont dépendent des scripts versionnés sont donc dans `public/inc/fonction.inc.php`, que `init.inc.php` charge :
- `recalculer_sous_totaux_ref_commande()` et `recalculer_sous_totaux_facture()`, ajoutées dans cette session ;
- `mettre_a_jour_cout_lignes_facture()`, déplacée depuis `init.inc.php`. Elle est entourée de `if (!function_exists(...))` : un `init.inc.php` local qui la contient encore garde sa version, sans erreur « Cannot redeclare ».
