# API `/transfert/{fiche}` — intégration BHP

## Le problème

BHP (système externe) a besoin d'échanger des fiches référentiel (chauffeur, client, chantier, formule, véhicule, origine, fournisseur...) avec CentralManager Web, sans qu'on ait à écrire un endpoint dédié par fiche. `api_transfert_controller` (`app/Http/Controllers/api_transfert_controller.php`) fournit un endpoint générique `GET`/`POST`/`DELETE` `/transfert/{fiche}` qui délègue à la logique métier existante de chaque contrôleur (`enregistrer()`, `supprimer()`), déjà utilisée par les formulaires web.

---

## Routes

```
routes/api.php, groupe auth:sanctum, prefix /transfert :

GET    /transfert/{fiche}   -> api_transfert_controller::demander_fiche
POST   /transfert/{fiche}   -> api_transfert_controller::enregistrer_fiche
DELETE /transfert/{fiche}   -> api_transfert_controller::supprimer_fiche
```

`{fiche}` est mis en minuscule et doit être une clé de `$modeles`/`$controleurs` dans `api_transfert_controller` (ex: `chauffeur`, `origine`, `fournisseur`...), sinon réponse `404` (`Fiche inconnue.`).

---

## Format du payload

Le corps peut être un objet unique ou une liste d'objets — les deux sont normalisés vers une liste en interne, et une réponse est renvoyée par fiche, dans le même ordre :

```json
[
  {
    "id_tracabilite_envoi": 20,
    "id_tracabilite_envoi_bhp": 50,
    "centrale_code": "01",
    "user_bhp": "Brody",
    "tracabilite_envoi_date_heure_bhp": "2026-09-03 11:33:00",
    "origine_code": "RANVILLE",
    "origine_libelle": "RANVILLE",
    "fournisseur": { "fournisseur_code": "503446" }
  }
]
```

- `<fiche>_code` (ou `chantier_code_complet` pour chantier) identifie la fiche pour savoir s'il s'agit d'une création ou d'une mise à jour.
- `id_tracabilite_envoi_bhp` et `user_bhp` sont renvoyés tels quels dans chaque réponse, et utilisés pour construire l'auteur de la traçabilité (voir plus bas).
- Une fiche liée s'envoie en objet imbriqué (`"fournisseur": {"fournisseur_code": "..."}`), résolue automatiquement (voir §Résolution des fiches liées). `null` explicite = fiche liée retirée.

---

## Convention par contrôleur de fiche

Chaque contrôleur métier (`origine_controller`, `fournisseur_controller`, `chauffeur_controller`...) expose, en plus de ses méthodes web habituelles (`enregistrer()`, `supprimer($id)`), deux méthodes dédiées à l'API :

- **`enregistrer_api(Request $request)`** : résout le PK propre de la fiche via son `*_code` (`$fiche = X::where('X_code', ...)->first()`), merge `<fiche>_id` dans la requête, puis délègue à `$this->enregistrer($request)`. Les FK vers des fiches liées (`fournisseur_id`, `transporteur_id`...) n'ont **pas** à être résolues ici : `api_transfert_controller::resoudre_liaisons()` le fait déjà en amont.
- **`supprimer_api(Request $request)`** : cherche la fiche par `code` (paramètre `code` du payload/query), `404` si introuvable, sinon délègue à `supprimer($id, true, $tracabilite_envoi_bhp, $token_name.' - '.$user_bhp, $tracabilite_envoi_date_heure_bhp)`.
- **`supprimer($id, $api=false, $tracabilite_envoi_bhp=null, $user='', $date_heure_bhp='')`** : mêmes contrôles métier que la version web (droit profil, fiche utilisée ailleurs), mais chaque réponse porte en plus `errors` (souvent la chaîne littérale `'null'`, par convention existante) et `id_tracabilite_envoi_bhp`. Sur un blocage métier, `success` passe à `true` quand `$api` est vrai — pour éviter qu'un retry BHP boucle indéfiniment sur une fiche qu'on refuse de toucher — sauf sur « non trouvée », qui reste toujours `false`. `$date_heure_bhp` est transmis tel quel à `ecrire_traca_std(..., $date_heure_bhp)` (voir §Auteur et horodatage de la traçabilité).
- **`enregistrer()`** : la réponse d'échec de validation porte `message`/`id_tracabilite_envoi_bhp` en plus de `errors`, la réponse de succès porte `errors`/`id_tracabilite_envoi_bhp`. Un blocage métier propre à la fiche (droit insuffisant selon le profil, ex: `classe_chlorure`/`classe_consistance`/`classe_exposition`) suit la même règle : `message` + `id_tracabilite_envoi_bhp` en plus d'`errors`.

### Auteur et horodatage de la traçabilité

`ecrire_traca_std($feuille, $enreg, $action, $user='', $date_heure='')` (`app/fonctions/tracabilite_fonction.php`) est appelée avec :

```php
$this->tracabilite->ecrire_traca_std(
    "Chauffeur", $chauffeur->chauffeur_code, $action_tracabilite,
    $request->user()?->currentAccessToken()?->name
        ? $request->user()->currentAccessToken()->name.' - '.$request->input('user_bhp')
        : $this->user->name,   // repli formulaire web (pas de token Sanctum)
    $request->has('tracabilite_envoi_date_heure_bhp') ? $request->input('tracabilite_envoi_date_heure_bhp') : ''
);
```

- **Auteur (`$user`)** : token Sanctum + `user_bhp` du payload si appel API, sinon `$this->user->name` (utilisateur web connecté). ⚠️ Ne pas copier le repli `''` d'`origine_controller`/`fournisseur_controller` (historique) pour une fiche activement éditée en UI : ça blanchirait l'auteur de la traça lors d'un enregistrement via le formulaire web.
- **Horodatage (`$date_heure`)** : si `tracabilite_envoi_date_heure_bhp` est fourni dans le payload, `ecrire_traca_std` l'utilise comme `tracabilite_date_heure` (heure **réelle de l'événement** côté BHP) et remplit `tracabilite_date_integration_reelle`/`tracabilite_heure_integration_reelle` avec `now()` (heure **réelle de l'intégration** ici) — ça distingue les deux moments. Sans valeur, `tracabilite_date_heure` = `now()` et les colonnes "réelle" restent `null`.
- Pour une suppression, le même `$date_heure_bhp` (venant de `supprimer_api()`) est transmis en 5ᵉ argument de `supprimer()` puis de `ecrire_traca_std()`.

---

## Résolution automatique des fiches liées (`resoudre_liaisons`)

`enregistrer_fiche()`/`supprimer_fiche()` appellent `resoudre_liaisons($modele, $ligne)` sur chaque ligne du payload, **avant** de déléguer au contrôleur métier. Elle :

1. Inspecte les méthodes `lier_*` du modèle (relations `belongsTo` uniquement, pas les `belongsToMany`).
2. Pour `lier_fournisseur`, cherche la clé `fournisseur` dans le payload (préfixe `lier_` retiré).
3. Si absente : ne touche à rien. Si `null` : merge `fournisseur_id = 0`. Si objet `{"fournisseur_code": "..."}` : trouve la colonne `*_code` de la table liée, cherche l'enregistrement correspondant, merge `fournisseur_id` (nom réel de la FK, via `getForeignKeyName()`) — `0` si le code n'est pas trouvé.

Ça marche pour n'importe quel modèle ayant une méthode `lier_xxx` — pas de code à écrire par fiche pour ce cas.

---

## Rattachement aux centrales (`resoudre_centrales`)

Pour les fiches qui ont une relation `lier_<fiche>_centrale` (`belongsToMany` vers `centrale`) — listées dans `api_transfert_controller::$modeles_centrale` (**client, chauffeur, vehicule, chantier, formule, service, produit**) — `enregistrer_fiche()`/`supprimer_fiche()` calculent aussi un tableau `centrales`, consommé par le `sync()` du contrôleur métier (`$model->lier_<fiche>_centrale()->sync($request->input('centrales'))`). Nécessaire car BHP n'envoie qu'un `centrale_code` unique (la centrale émettrice), pas un tableau.

Pilotage via `t_parametre.parametre_integration_<fiche>` (colonne booléenne par fiche, existe pour `client`, `chantier`, `chauffeur`, `vehicule`, `service`, `produit` — pas pour `formule`) :

- **`= 1`** → fiche **commune** à toutes les centrales actives (`centrale_active = 1`) : `centrales` = tous leurs ids.
- **`= 0` / absent** → fiche **locale** à la centrale émettrice : `centrales` = id de la centrale résolue via `centrale_code`, **plus** les centrales déjà liées à la fiche existante (recherchée par son `*_code`), pour qu'une mise à jour ne fasse pas perdre un rattachement précédent (`sync()` remplace tout le pivot, contrairement à un simple insert ciblé).

La clé réelle utilisée est lue dynamiquement via `getRelatedKeyName()`, jamais codée en dur. C'est `id_centrale` pour toutes les fiches depuis le 2026-10-05 : `chantier` était la dernière à utiliser `centrale_code` comme clé pivot (`t_chantier_centrale` liée par `chantier_code_complet`/`centrale_code`) ; elle est maintenant liée par `chantier_id`/`centrale_id` comme les autres (migration `2026_10_05_1540_V905000_BAM_t_chantier_centrale_avec_id`, même principe que `t_client_centrale` en V900 : colonnes code conservées en `NULL`able, plus remplies par Laravel).

⚠️ **Colonnes ambiguës (corrigé le 2026-09-24)** : les tables pivot `t_client_centrale` et `t_chantier_centrale` ont elles aussi une colonne `centrale_code`. Le `pluck()` des centrales déjà liées est donc qualifié (`$relation->getRelated()->qualifyColumn($cle_liee)` → `t_centrale.centrale_code` à l'époque pour chantier, `t_centrale.id_centrale` aujourd'hui), et les scopes globaux `order`/`active` de `app/Models/centrale.php` qualifient aussi leurs colonnes (`qualifyColumn()`). Avant ça, en mode local, toute mise à jour d'un client ou d'un chantier déjà rattaché à une centrale plantait en 500 (« centrale_code ambigu »). Depuis le 2026-10-05, la clé pivot de chantier est `id_centrale`, mais les deux pivots gardent leur colonne `centrale_code` legacy (nullable) : la qualification reste nécessaire (notamment pour le scope `order`, trié sur `centrale_code`). À garder en tête pour toute nouvelle requête qui joint `t_centrale` à un pivot.

⚠️ **Casse du `<fiche>_code`** : les clés de tableau PHP sont sensibles à la casse (contrairement aux noms de colonnes MySQL, insensibles à la casse). La plupart des fiches suivent la convention `<fiche>_code` tout en minuscule (`chauffeur_code`, `origine_code`...), mais certaines colonnes DB ont une casse différente (`vehicule` → `Vehicule_Code`, `chantier` → en réalité `chantier_code_complet`, pas `chantier_code`). `api_transfert_controller::$colonnes_code_speciales` liste ces exceptions ; `resoudre_centrales()` s'en sert pour savoir sous quelle clé chercher le code dans le payload. À vérifier/compléter à chaque nouvelle fiche dont le payload BHP utilise la casse réelle de la colonne plutôt que la convention minuscule.

⚠️ **Bug corrigé le 2026-09-28 — `colonne_code()` insensible à `$colonnes_code_speciales`** : ce helper privé (utilisé par `resoudre_liaisons()` pour résoudre un FK depuis une fiche liée imbriquée en POST, et par `getBelongsToRelations()` pour construire le `with()` restreint en GET) devine le nom de la colonne code via `preg_replace('/^t_/', '', $table) . '_code'` puis compare avec `in_array(..., true)`/`str_ends_with()` — tous deux **sensibles à la casse**, et sans jamais consulter `$colonnes_code_speciales`. Pour `t_vehicule.Vehicule_Code`, ça ne matchait jamais : `colonne_code()` renvoyait `null`, donc `lier_vehicule` (présent sur `commande`, `bl`, `planning`, `planning_prev`, `incident`) n'était **jamais résolu en POST** (FK silencieusement ignorée), et en GET tombait dans le fallback "pas de colonne code" qui charge **toutes** les colonnes de `t_vehicule` sans restriction (au lieu de juste `id_vehicule,Vehicule_Code`). Corrigé en rendant la comparaison insensible à la casse (`strcasecmp`, et suffixe `_code` comparé en minuscule) — retourne la colonne avec sa casse réelle telle qu'en base. Un scan de tous les modèles câblés dans l'API a confirmé que `vehicule` est le seul cas concerné actuellement. Vérifié via tinker (`colonne_code('t_vehicule', ...)` → `Vehicule_Code` ; `getBelongsToRelations()` → `lier_vehicule:id_vehicule,Vehicule_Code` ; `resoudre_liaisons()` sur `commande` avec `{"vehicule": {"Vehicule_Code": "01"}}` → `vehicule_id` correctement résolu).

Cette logique reproduit le comportement de l'ancien endpoint legacy `public/trans/action_trans_chauffeur.php` (delete+insert ciblé sur une seule centrale si `=0`, boucle sur toutes les centrales actives + notification `t_tracabilite_envoi` des autres centrales si `=1`).

---

## État d'avancement par fiche

| Fiche | `enregistrer_api`/`supprimer_api` | Dans `$modeles_centrale` |
|---|---|---|
| origine | ✅ (historique) | non concerné (pas de `lier_centrale`) |
| fournisseur | ✅ (historique) | non concerné |
| chauffeur | ✅ (ajouté 2026-09-05) | ✅ |
| classe_chlorure | ✅ (ajouté 2026-09-05) | non concerné (pas de `lier_*`) |
| classe_consistance | ✅ (ajouté 2026-09-05) | non concerné (pas de `lier_*`) |
| classe_exposition | ✅ (ajouté 2026-09-05) | non concerné (pas de `lier_*`) |
| transporteur | ✅ (ajouté 2026-09-05) | non concerné (pas de `lier_*`) |
| vehicule | ✅ (ajouté 2026-09-15) | ✅ — payload utilise `Vehicule_Code` (casse exacte colonne DB), voir `$colonnes_code_speciales` |
| type_beton | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| designation_beton | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| specificite | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| classe_resistance | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| famille_beton_echantillon | ✅ (ajouté 2026-09-15, demandé comme "famille_beton") | non concerné (pas de `lier_*`). Corrigé 2026-09-24 : la traça de `enregistrer()` écrivait `"Suppression"` en dur au lieu de `$action_tracabilite` |
| nature_addition | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| mode_reg | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`). Corrigé 2026-09-24 : validation `mode_reg_libelle` `max:50` → `max:25` (colonne `varchar(25)`, MySQL non strict tronquait en silence) |
| pays | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| unite | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| position_compte | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`). Corrigé 2026-09-24 : colonne `position_compte_alarme` jamais créée (ligne commentée dans la migration V900) → erreur 500 dès que le champ était envoyé ; migration `2026_09_24_1216_V904005_BAM_t_position_compte_position_compte_alarme` |
| tva | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| zone | ✅ (ajouté 2026-09-15) | non concerné — a des `lier_*` (tva, famille_article, groupe_tarif, typologie_article) donc `resoudre_liaisons` s'applique, mais pas de `lier_centrale`. Corrigé 2026-09-24 dans `supprimer()` : `t_commune.zone_id` n'existait pas (500 sur toute suppression ; migration `2026_09_24_1339_V904005_BAM_t_commune_zone_id`), et les contrôles devis/commande/BL testaient `$chantier` au lieu de leur ligne, sans filtrer le type d'article (`*_type_article = 4` = zone) |
| client | ✅ (ajouté 2026-09-15) | ✅ — voir §Rattachement aux centrales, colonnes ambiguës (corrigé 2026-09-24) |
| chantier | ✅ (ajouté 2026-09-15) | ✅ — clé pivot = `id_centrale` (`t_chantier_centrale.chantier_id`/`centrale_id`) depuis le 2026-10-05 ; c'était `centrale_code` avant (`chantier_code_complet`/`centrale_code`, colonnes conservées en legacy nullable). Champ PK propre = `id_chantier` (pas `chantier_id`), code = `chantier_code_complet` (`$colonnes_code_speciales`). Plusieurs FK (`formule_id`, `centrale_id`, `motif_echec_reussite_id`, `concurrent_id`, `modele_impression_id`, `ventilation_id`, `modele_qr_code_id`) n'ont pas de relation `lier_*` sur le modèle donc ne sont **pas** résolues par `resoudre_liaisons()` **Revérifié le 2026-10-06 après le merge de `test_chantier_centrale`** (GET, création en mode commun et local, mise à jour, DELETE, blocage si utilisé par commande/devis/BL : pivot par ids, sans ligne orpheline ni doublon). Corrigé ce jour-là : `enregistrer()` lit le champ de formulaire `commune_id_chantier` (qui n`existe pas en base, la colonne est `commune_id`) et retombe sur 0 s`il est absent — un aller-retour GET→POST sans objet `commune` effaçait `commune_id`, `chantier_code_postal` et `chantier_ville` ; `enregistrer_api()` conserve maintenant la commune existante quand `commune` n`est pas envoyé (`commune: null` explicite l`efface toujours). |
| formule | ✅ (ajouté 2026-09-15/16) | ✅ — pas de `parametre_integration_formule` (pas de migration prévue), donc toujours la branche "locale" (centrale émettrice ajoutée sans retirer les autres) |
| civilite | ✅ (ajouté 2026-09-15) | non concerné (pas de `lier_*`) |
| type_vehicule | ✅ (ajouté 2026-09-17) | non concerné (pas de `lier_*`). Corrigé 2026-09-24 : `supprimer()` n'avait aucun contrôle (droit `profil_fichier_facturation`, type utilisé par un véhicule) ; code validé `max:2` (colonne `varchar(2)`) au lieu de `max:12` |
| service | ✅ (ajouté 2026-09-22) | ✅ — `parametre_integration_service` existe en base |
| produit | ✅ (ajouté 2026-09-22) | ✅ — `parametre_integration_produit` existe en base. Corrigé au passage 2 relations cassées du modèle : `lier_origine` pointait vers `fournisseur`/`famille_produit_id` (copier-coller) → `origine`/`origine_id` ; `lier_unite` référençait une colonne `unite_id` inexistante → remplacé par `lier_unite_vente`/`lier_unite_achat` (colonnes réelles), avec mise à jour des 2 `with()` dans `produit_controller.php` qui l'utilisaient |
| commande | ✅ (ajouté 2026-09-28) | non concerné (pas de `lier_centrale`, `centrale_id` est un simple belongsTo). **`lier_chantier` identifié par `chantier_code_complet` (2026-10-13)** : `colonne_code()` utilise `$colonnes_code_speciales` (chantier → `chantier_code_complet`), donc le GET renvoie `"lier_chantier": {"chantier_code_complet": "C136194     DIFFUS"}` (avant : `chantier_code`, non unique) et le POST résout `"chantier": {"chantier_code_complet": "…"}` ; code inconnu ou `null` → `chantier_id = 0`. Ancien format `"chantier": {"chantier_code": "…"}` toujours accepté (compatibilité), mais ambigu : `chantier_code` n’étant pas unique, il peut désigner le chantier d’un autre client |
| groupe_tarif | ✅ (ajouté 2026-09-29) | non concerné (pas de `lier_*`, fiche liée *depuis* ajout/produit/service/zone/formule via `groupe_tarif_id`, jamais l'inverse). Corrigé au passage : validation `groupe_tarif_libelle` `max:50` → `max:25` (colonne `varchar(25)`, MySQL non strict tronquait en silence — même bug déjà vu et corrigé sur `mode_reg`) |
| famille_article | ✅ (ajouté 2026-09-29) | non concerné (pas de `lier_*`, fiche liée *depuis* ajout/produit/service/zone/formule via `famille_article_id`/`famille_produit_id`/`famille_service_id`, jamais l'inverse). Corrigé au passage : même bug de validation `famille_article_libelle` `max:50` → `max:25` (colonne `varchar(25)`) |
| sous_famille_client | ✅ (ajouté 2026-10-02) | non concerné (pas de `lier_*_centrale`). A un `lier_famille_client` : payload `"famille_client": {"famille_client_code": "..."}` résolu par `resoudre_liaisons()` (GET renvoie la même forme sous la clé `lier_famille_client`). ⚠️ Une `famille_client_code` inconnue donne `famille_client_id = 0` (convention « fiche liée non trouvée → 0 ») et la validation `required\|numeric` l'accepte : la sous-famille est enregistrée sans famille. `famille_client` est aussi une fiche de l'API (voir ligne suivante) : l'envoyer avant ses sous-familles. `supprimer()` bloque si utilisée par `parametre` ou `client` |
| centrale | ✅ (ajouté 2026-10-09) | non concerné (pas de `lier_*_centrale` ; droit `profil_centrale`). Identifiée par `centrale_code`. Liaisons imbriquées : `societe` (**`Societe_Code`**, casse exacte), `activite` (`activite_code`), `groupe_centrale_tarif` (`groupe_centrale_tarif_code`), `region_commerciale`, `producteur`, `site`, `energie` (`null` → `0`). **Le scope global `active` du modèle cache les centrales désactivées** : le GET, le POST (recherche par code) et le DELETE le retirent (`withoutGlobalScope('active')`), donc une centrale désactivée est renvoyée avec `centrale_active = 0`, se met à jour sans être recréée en double, et peut être supprimée (avant, `supprimer()` plantait sur `$centrale->centrale_code` pour une centrale inactive). **Indicateurs production / facturation / formulation** : `enregistrer()` les recalcule à partir du seul champ de formulaire `centrale_production_facturation_formulation` (1, 2 ou 3, exclusifs) et les remettrait tous à 0 s'il est absent ; `enregistrer_api()` le déduit de `centrale_production` / `centrale_facturation` / `centrale_formulation` (celui envoyé à 1 gagne, priorité production > facturation > formulation ; s'ils sont tous envoyés à 0 ils passent à 0 ; absents, l'état de la centrale existante est conservé) et respecte le champ du formulaire s'il est envoyé. **Tokens `exterieur`** : 12 champs techniques masqués (`centrale_adresse_ip`, `centrale_envoi_donnees`, `centrale_recept_donnees`, `centrale_prog_envoi`, `centrale_prog_recept`, `centrale_version_*`, `centrale_heure_derniere_communication`, `centrale_modele_pdf`) via `$champs_invisibles_api_exterieur` du modèle ; les tokens `bhp` voient tout. Traça d'envoi `T_Centrale` écrite pour toutes les centrales actives, y compris la nouvelle (`tracabilite_envoi.centrale_code` est un `varchar(3)` : un code de centrale plus long y est tronqué). Corrigé dans `supprimer()` : le garde-fou `client_centrale` testait `centrale_code`, vide sur 1 495 lignes sur 14 327 écrites par Laravel — il teste maintenant `centrale_id`. En pratique la suppression d'une centrale réelle est toujours refusée (utilisée par paramètre, commandes, etc.). Les champs absents de la validation de `enregistrer()` (versions logicielles, dernière communication, modèle PDF…) ne sont pas enregistrés par ce POST : les versions passent par `/connexion_centrale` |
| moyen_dechargement | ✅ (ajouté 2026-10-13) | non concerné (pas de `lier_*`, droit `profil_fichier_divers`). Fiche liée *depuis* `commande`/`devis`/`bl`/`parametre` via `moyen_dechargement_id` (la commande renvoie `lier_moyen_dechargement: {moyen_dechargement_code}`). Champs : `moyen_dechargement_code` (**2 caractères au plus**, unique), `_libelle` (25), `_tps_dechargement` (heure), `_couleur` (25, `NOT NULL` sans défaut : `enregistrer_api()` garde la couleur existante si elle est absente ou `null`, `''` pour une création). Traça d'envoi `T_Moyen_Dechargement` vers toutes les centrales actives (fiche commune). `supprimer()` bloque si utilisé par `parametre`, `devis`, `commande` ou `bl` (réponse `success:true` + message côté API). Le modèle a un scope global `order` (tri par code). Testé : GET code et ALL, création sans couleur, modification avec/sans couleur, code trop long refusé, suppression d'un code utilisé (`CL`), introuvable, suppression, traces (`bhp_test - u1`) |
| bl | ✅ POST / DELETE seulement (ajouté 2026-10-13) | non concerné (pas de `lier_*_centrale`, droit `profil_bl`). **Pas de lecture** (`$fiches_sans_lecture`, GET → 404) et **pas de `tracabilite_envoi`** : un BL vient de BHP, il n'y est pas renvoyé. Construit sur le modèle de `commande` : **le `bl_code` reçu est celui de la centrale, le BL est enregistré sous `str_pad(centrale_code, 3, "0", STR_PAD_LEFT) . bl_code`** (ex. `centrale_code` `5` + `P00044786` → `005P00044786` ; `C05` + `T0000001` → `C05T0000001` ; colonne `varchar(12)` : 9 caractères au plus reçus avec une centrale de 3). `centrale_code` se lit à la racine du payload ou dans l'objet `centrale`, il est **obligatoire** (POST et DELETE : `{"code": "…", "centrale_code": "…"}`), et donne aussi `centrale_id` quand l'objet `centrale` n'est pas envoyé (centrale inconnue → refus). Deux centrales peuvent donc envoyer le même `bl_code`. Les lignes (`ligne_bl.bl_code`), la traça et la réponse (`bl_code`) utilisent le code complet. Le code complet identifie le BL, les fiches liées sont des objets imbriqués résolus par `resoudre_liaisons()` (`client`, `chantier` → `chantier_code_complet`, `centrale`, `commande`, `vehicule`, `chauffeur`, `formule`, `zone`, `tva`, `moyen_dechargement`, `classe_consistance`, `specificite`, `designation_beton`, `modele_impression`, `modele_qr_code`, `reglage_trappe` ; relations ajoutées au modèle : les 3 dernières), et les lignes du BL (`ligne_bl`) sont lues sous **`"lignesbl"`** (nom envoyé par BHP ; `"ligne"` est aussi accepté, comme pour la commande) et remplacent intégralement les lignes existantes, dans une transaction annulée si le BL est refusé. Chaque ligne envoie `article_code` + `ligne_bl_type_article` : 1 service, 2 ajout, 3 et 5 produit, 4 zone, 9 commentaire (pas d'article), autre (0) formule — comme `ligne_bl_detail_bl()` ; sans `lignesbl` ni `ligne`, les lignes existantes sont conservées. **`enregistrer(Request, $api)`** : mode API distinct du formulaire web (qui ne valide qu'~50 des ~170 colonnes de `t_bl`) — (1) toutes les colonnes sont validées et enregistrées, règle déduite du type SQL (`regles_colonnes_api()` : entier, décimal, date, `string max:N` selon la longueur) ; (2) heures acceptées en `H:i:s` comme en `H:i` ; (3) indicateurs 0/1 (les 15 colonnes passées en `tinyint(1)` par la migration `2026_10_14_1717_..._t_bl_champs_checkbox_boolean`) : lus avec `boolean()` dans les deux modes, jamais `has()` (une case précédée d'un input hidden à 0, ou un champ envoyé à 0 par l'API, est toujours présente et `has()` la ferait valoir 1) ; en API, absents ils gardent leur valeur ; **les booléens JSON `true`/`false` envoyés par BHP pour les autres colonnes `tinyint(1)` (`bl_tournee_mortier`, `bl_blocage_cycle`, `bl_optimalax`, `bl_option_demat`, `bl_option_imp_bl_si_demat`, `bl_sans_production`…) sont ramenés à 1/0 avant la validation** (sinon la règle « entier » refusait `false`) ; (4) colonne `NOT NULL` envoyée à `null` : ignorée ; (5) `bl_code` limité à 12 (colonne `varchar(12)`, le formulaire accepte 16) ; (6) code de fiche liée inconnu (`client`, `chantier`, … ou `article_code` d'une ligne) : BL refusé avant toute écriture (`_liaisons_introuvables`, posé par `resoudre_liaisons()`) ; (7) traça `BL` avec auteur `token - user_bhp` et date BHP. `supprimer()` : droit `profil_bl` = 5, supprime le BL et ses lignes (aucun contrôle d'usage, par exemple BL déjà facturé : conservé tel quel). `adresse_facturation` n'a pas de code (fiche annulée) : seul `adresse_facturation_id` entier est pris tel quel. Rejoué avec le vrai payload de BHP (`BL.json` : `centrale_code` `121` + `bl_code` `001238` → `121001238`, 2 lignes `lignesbl`, booléens JSON) : création, rejeu sans doublon, `true`/`false`, indicateur absent conservé, ancienne clé `ligne`, suppression. Testé aussi : création avec 6 lignes (types 0 à 9), mise à jour, indicateurs, lignes remplacées/conservées, client et article inconnus, `bl_code` trop long, heure invalide, texte trop long, `NOT NULL` à `null`, GET refusé, suppression |
| chantier_formule | ✅ (ajouté 2026-10-14) | non concerné. Formules autorisées d'un chantier : table intermédiaire `t_chantier_formule` (modèle `chantier_formule`, ni code ni centrale). Le chantier est identifié par `chantier_code_complet`, ses formules par `formule_code`. **GET** `/transfert/chantier_formule?code=<chantier_code_complet>\|ALL` (branche dédiée `demander_chantier_formule()`, pas la lecture générique) : un élément par chantier qui a un catalogue, formules triées — `[{"chantier_code_complet": "…", "formule": [{"formule_code": "B25"}, {"formule_code": "C204917"}]}]` ; avec `code=ALL`, un chantier sans catalogue est absent ; avec un code précis, un chantier qui existe mais n'a aucune formule est renvoyé avec `"formule": []` (BHP peut ainsi savoir que le catalogue est vide ; le POST n'enlevant jamais de formule, c'est à BHP de vider le sien) et un chantier inconnu donne `[]` ; `id_tracabilite_envoi` marque la traça envoyée. **POST** (`chantier_formule_controller::enregistrer_api()`, même forme, une liste de chantiers possible) : les formules reçues sont **ajoutées** au catalogue du chantier (**attach, pas sync**, changé le 2026-10-14 : aucune formule n'est retirée, celles déjà présentes ne sont pas dupliquées, le formulaire web `formule_controller::enregistrer_liste_formule()` remplace au contraire toute la liste) ; `formule` accepte aussi une liste de codes ou un objet unique, les doublons sont ignorés, liste vide = rien ne change, clé `formule` absente = refus. La réponse donne `formules_ajoutees` et `formules_deja_presentes`. Chantier ou formule inconnus : le chantier est refusé avant toute écriture (`errors: {"formule.NOPE": […]}`). Droit `profil_chantier` (écriture refusée pour 0 et 1). **DELETE** `{"chantier_code_complet": "…"}` (ou `code`) : vide **tout** le catalogue du chantier (droit 5) — c'est le seul moyen de retirer des formules par l'API, il n'existe pas de retrait formule par formule ; chantier inconnu → 404, catalogue déjà vide → `success:true`. Traça standard `Catalogue formule` (auteur `token - user_bhp`, date BHP) ; **aucune `tracabilite_envoi`** : ni l'API ni le formulaire web (`enregistrer_liste_formule`, `supprimer_liste_chantier_formule`) n'en écrivent, BHP est prévenu par la validation du chantier : `chantier_controller::enregistrer()` écrit la traça `T_CatalogueFormuleChantier` (code = `chantier_code_complet`, centrales du chantier), et BHP relit alors le catalogue avec `code=<chantier_code_complet>`. ⚠️ `chantier_code_complet` est utilisé tel quel, **espaces de remplissage compris** (`"14          17"` : code client sur 12 caractères) : un code tronqué est « introuvable ». Testé : GET (ALL, un chantier, inconnu), aller-retour GET → POST sans changement, ajout sans retrait ni doublon (POST rejoué), refus sans modification, liste vide, chantier sans catalogue, DELETE |
| pesee | ✅ POST seulement (ajouté 2026-10-16) | non concerné. **Ni GET (`$fiches_sans_lecture`) ni DELETE (`$fiches_sans_suppression`, nouvelle liste : `supprimer_fiche()` la refuse comme une fiche inconnue)** : BHP envoie ses pesées, c'est tout. `pesee_controller::enregistrer_api()` reprend la logique de l'ancien script d'intégration (`action=integration`), avec **les noms des colonnes de `t_pesee` dans le payload** (le script recevait des paramètres abrégés et **divisait par 1000** consignes, résultat et `data_*` : ici les valeurs sont reçues dans l'unité de la base, sans conversion — à confirmer côté BHP). Payload : `centrale_code` à la racine et **le BL en fiche liée `"bl": {"bl_code": "000110"}`** (`lier_bl` ; `bl_code` à la racine reste accepté), tous deux obligatoires, `pesee_date`, `pesee_heure` (`H:i:s` ou `H:i`), `pesee_no_exec`, `pesee_no_gachee`, `pesee_type_donnee`, `pesee_consigne`, `pesee_consigne_reelle`, `pesee_resultat`, `pesee_acquitement_ht`, `pesee_data_1/2/3`, `pesee_no_case_origine`, `pesee_no_case_dosee`, `pesee_stock_case_courant`, `pesee_prefa` (0/1, `true`/`false` accepté), `pesee_no_voie`, `pesee_no_ligne`, `pesee_qdc` (`double(7,3)` : arrondi à 3 décimales par la base), `pesee_type_produit`, et les produits en objets imbriqués : `"produit_formule": {"produit_code": "…"}` (→ `produit_formule_id`, relation `pesee::lier_produit_formule` ajoutée ; `lier_produit` reste, utilisée par le mapper Massia) et `"produit_dose": {"produit_code": "…"}` (→ `produit_dose_id`) ; `null` → 0. **BL retrouvé** par `str_pad(centrale_code, 3, "0", STR_PAD_LEFT) . bl_code` (même règle que la fiche `bl`), le `bl_code` reçu étant d'abord complété de zéros à gauche jusqu'à 6 caractères (9 si `pesee_prefa` = 1), puis, à défaut, avec le code de la centrale de substitution V2 (`centrale_substitution_v2_id`) ; BL ou centrale inconnus : refus. `centrale_id` de la pesée = celui du BL. **Produit inconnu ou absent → 0** (pesée enregistrée quand même, comme avant ; un id brut sans l'objet imbriqué est ignoré). Les coûts `pesee_cout_produit_dose` / `pesee_cout_produit_formule` sont **calculés** (`produit_cout_kg` + `t_produit_transport.produit_transport_prix` de la centrale du BL), jamais reçus. **Pesée déjà présente** (même BL, gâchée, voie, ligne, produit dosé, case dosée, résultat, heure, type de donnée ; `pesee_no_voie` et `pesee_no_ligne` ont été ajoutés à la clé de l'ancien script, pour ne pas écraser deux pesées différentes à zéro dans la même minute) : succès sans création (retry de BHP sans doublon). `pesee_type_donnee` = 4 : `bl_quantite_produite` du BL augmente de `pesee_data_1`. Droit `profil_bl` (création refusée pour 0, 1, 3). Comme le script d'origine : **aucune traça ni `tracabilite_envoi`** (des centaines de pesées par BL). Réponse : `success`, `message`, `errors`, `id_tracabilite_envoi_bhp`, `id_pesee`, `bl_code`. Rejoué avec le vrai payload de BHP (9 pesées du BL `000110`, centrale `01` → BL `001000110`) : 9 créées, rejeu sans doublon. ⚠️ `pesee_no_ligne`, `pesee_qdc` et `pesee_type_produit` existent dans la base de dev mais **aucune migration du dépôt ne les crée** : à vérifier sur les autres bases. Testé : création (préfa, type 4, dose inconnue, booléen JSON), rejeu sans doublon ni incrément, coût avec transport, centrale à 2 caractères (`02` → `002…`), BL/centrale inconnus, validation, liste dont un élément est refusé, GET et DELETE refusés |
| heures_bl | ✅ GET seulement (ajouté 2026-11-06) | non concerné. Les heures des BL et leur type, **lecture seule** : pas de contrôleur dans `$controleurs`, donc POST et DELETE répondent « Fiche inconnue ». Branche dédiée de `demander_fiche()` qui appelle `bl_controller::demander_heures_bl()` (pas la lecture générique : une ligne par BL, 17 colonnes seulement). **Le BL est identifié par son `bl_code` complet** (celui de `t_bl`, préfixe de centrale compris, que BHP renvoie tel quel) : `GET /transfert/heures_bl?code=<bl_code>`, ou une période sur `bl_date_livraison` : `?date_debut=2026-11-03[&date_fin=2026-11-05][&centrale_code=01]` (`date_fin` = `date_debut` par défaut, **31 jours au plus**). `code=ALL` ou aucun filtre est refusé (`success:false`) : la table contient plusieurs centaines de milliers de BL. Réponse : liste, un élément par BL, aux noms des colonnes de `t_bl` — `bl_code` (**sans** le code centrale sur 3 caractères : c’est `centrale_code`, renvoyé à côté, qui le porte), `centrale_code`, `bl_heure_fab`, `bl_attente_chantier`, `bl_heure_dep_centrale`, `bl_heure_arr_chantier`, `bl_heure_dep_vidange`, `bl_heure_fin_vidange`, `bl_heure_dep_chantier`, `bl_heure_arr_centrale` (format `HH:MM:SS`) et leurs types `bl_heure_fab_type`, `bl_heure_dep_centrale_type`, `bl_heure_arr_chantier_type`, `bl_heure_deb_vidange_type`, `bl_heure_fin_vidange_type`, `bl_heure_deb_chantier_type`, `bl__heure_arr_centrale_type` (`bl_heure_fab` est ajoutée à la liste demandée, son type `bl_heure_fab_type` en dépendant ; `bl_heure_fab_type` peut être `null` en base). Aucun BL trouvé : `[]`. Comme la lecture générique, un `id_tracabilite_envoi` passé par un token BHP marque la traça d’envoi comme envoyée (`marquer_tracabilite_envoyee()`), sauf si la demande est refusée (`success:false`). Testé : un BL par code, code inconnu, période, filtre centrale, refus (sans filtre, `ALL`, > 31 jours, fin avant début, date invalide), POST/DELETE refusés |
| commande_achat | ✅ GET / POST / DELETE (ajouté 2026-11-09) | non concerné (droit `profil_fichier_crm`, traça d'envoi `T_Commande_Achat` comme dans le formulaire web). Champs (colonnes de `t_commande_achat`, GET et POST) : `commande_achat_code` (**25 caractères au plus**, unique), `commande_achat_reference_commande` (50), `commande_achat_type_produit` (`0` = produit, `1` = ajout manuel). **Liaisons** : `fournisseur` → `{"fournisseur_code": ...}` (résolu par `resoudre_liaisons()`, GET : `lier_fournisseur`) ; l'article est sous `produit` → `{"produit_code": ...}` en POST (GET : `lier_produit`) **dans les deux cas** : un produit si le type vaut `0`, le **code de l'ajout** (`ajout_code`, renvoyé sous la clé `produit_code`) s'il vaut `1`, car `produit_id` contient l'id de l'un ou de l'autre (`lier_produit`/`lier_ajout` du modèle sont donc déclarées dans `relationsConditionnelles()`, ignorées par la résolution générique, et chargées par `commande_achat::charger_lier_produit()` — même principe que `composition::charger_lier_produit()`). `produit: null` / `fournisseur: null` vident la liaison (`0`). **Code inconnu** (fournisseur ou article) : fiche refusée (`success:false`, `message` « Fiche liée introuvable ! », `errors` par clé), rien n'est enregistré. **Changement de type sans `produit`** (ex. `0` → `1`) : `produit_id` est remis à `0` (l'ancien id désignerait un article de l'autre table). Mise à jour partielle : une clé absente du payload est conservée. Validation : type `0` ou `1` seulement (l'ancienne règle `numeric|max:1` acceptait `-5` ou `0.5`), code `max:25` (la colonne est un `varchar(25)`, la règle d'origine n'avait pas de limite). DELETE `?code=` : droit `profil_fichier_crm = 5`, 404 si le code est inconnu ; **aucun contrôle d'usage** (`t_entree_matiere.commande_achat_id` peut pointer vers la fiche supprimée — comportement d'origine du formulaire web, conservé). Auteur de traça `token - user_bhp` + date BHP, repli `$this->user->name` pour le web. Testé : GET, création type 0 et type 1, mise à jour partielle, codes inconnus, changement de type, `null`, validations, objet unique et liste, DELETE, formulaire web et DataTable inchangés, nettoyage des traces. |
| entree_matiere | ✅ POST / DELETE seulement (ajouté 2026-11-09) | non concerné. Équivalent de `public/trans/action_trans_entree_matiere.php` (`integration` / `suppression`). **Pas de lecture** (`$fiches_sans_lecture`). **Identité** : BHP envoie `entree_matiere_code` (30 caractères au plus), qui sert **tel quel** — en POST comme en DELETE (`code` accepté en DELETE). Sans lui, repli sur l'ancienne règle : `centrale_code` + `fournisseur_code` + `entree_matiere_code_bl` (12 au plus), chacun à la racine ou dans l'objet `centrale` / `fournisseur`, et le code enregistré est `str_pad(centrale_code, 3, "0", STR_PAD_LEFT) . '_' . fournisseur_code . '_' . code BL`, comme l'ancien script. Avec `entree_matiere_code`, `centrale` et `fournisseur` (racine ou objet) ne sont **obligatoires qu'à la création** (un code envoyé mais inconnu est toujours refusé) et `entree_matiere_code_bl` est une simple donnée, mise à jour si elle est envoyée. POST : création ou mise à jour d'après ce code (`entree_matiere_code` est unique), une entrée supprimée est **réactivée** (`entree_matiere_supprimee = 0`). Champs = colonnes de `t_entree_matiere` : `entree_matiere_date`, `entree_matiere_quantite` (**valeur réelle**, plus le ×100 de l'ancien script), `entree_matiere_unite` (2), `entree_matiere_information` (50), `entree_matiere_code_interne_societe` (30), `entree_matiere_type_produit` (`5` = ajout, sinon produit ; `"05"` accepté). Liaisons en objets imbriqués : `origine`, `transporteur`, `commande_achat` (`{"x_code": ...}`, `resoudre_liaisons()`, `lier_origine` ajoutée au modèle) et `produit` → `{"produit_code": ...}` : un produit, ou le code d'un **ajout** si le type vaut `5` (même principe que `commande_achat`). `null` vide la liaison (`0`) ; une clé absente est conservée en mise à jour et vaut `0` à la création (comme les entrées de l'ancien script) ; changement de type sans `produit` : `produit_id` remis à `0`. **Code inconnu** (centrale, fournisseur, produit, origine, transporteur, commande d'achat) : entrée refusée (`success:false`, `errors` par clé) — l'ancien script mettait `0`. Le **transporteur**, lu mais jamais enregistré par l'ancien script, est enregistré (`transporteur_id` existe et la liste Smart l'affiche). DELETE : **suppression logique** (`entree_matiere_supprimee = 1`, la ligne reste), 404 si l'entrée est inconnue, succès sans nouvelle traça si elle est déjà supprimée. Pas de contrôle de droit (aucun dans l'ancien script ni dans le contrôleur), pas de `tracabilite_envoi` ; traça `Entrée matière` avec auteur `token - user_bhp` + date BHP. ⚠️ **L'envoi automatique du fichier FTP/SFTP** de l'ancien script (`parametre_envoi_fichier_ftp_automatique` → `trans_externe/extraction_entree_matiere.php`) **n'est pas repris** pour le moment. Quand une colonne n'est pas envoyée à la création, `BaseModel` la remplit (texte vide, `0`, date du jour). Testé : création complète et minimale, mise à jour partielle sans doublon, type `"05"`, identité à la racine et imbriquée, 8 codes inconnus ou absents, validations, GET refusé, suppression logique / 2ᵉ suppression / inconnue, réactivation, traces, table remise à l'identique. |
| etat_stock | ✅ POST / DELETE seulement (ajouté 2026-11-09) | non concerné. Équivalent de `public/trans/action_trans_etat_stock.php` (`integration` / `suppression`). **Pas de lecture** (`$fiches_sans_lecture`). POST : `centrale` (`centrale_code` à la racine ou objet `centrale`), `produit` → `{"produit_code": ...}` (un produit, ou le code d'un **ajout** si `etat_stock_type_produit` vaut `05` ; `lier_produit` déclarée en `relationsConditionnelles()`), `etat_stock_type_produit` (`00` à `05`, varchar(2) ; `5` ou `0` entiers acceptés), `etat_stock_stock_courant` (**valeur réelle signée** : plus le ×100 ni le signe à part de l'ancien script ; décimal(8,2)), `etat_stock_unite` (2), `etat_stock_date`, `etat_stock_heure` (`H:i` ou `H:i:s`). **Mise à jour au lieu d'insertion** : l'ancien script insérait à chaque appel, l'état d'un même article (centrale + type + produit) est ici mis à jour s'il existe — un rejeu ne crée pas de doublon. Centrale ou article inconnu : état refusé (l'ancien script l'ignorait en silence). DELETE : supprime **tous** les états de la centrale (`centrale_code` — BHP vide la centrale puis renvoie ses états, comme l'ancien script) ; centrale inconnue : refusée (404). Pas de traça ni de `tracabilite_envoi` (relevés répétés), pas de contrôle de droit. Testé : création, rejeu avec autre valeur (type en entier, heure sans secondes), ajout et type `"5"`, 5 refus, 8 validations, GET refusé, DELETE d'une centrale sans toucher aux autres, table remise vide. |
| gamme_vidange | ✅ POST / DELETE seulement (ajouté 2026-10-13) | non concerné (pas de `lier_*`, droit `profil_fichier_norme`). **Pas de lecture** : `demander_fiche()` la refuse comme une fiche inconnue (404, liste `$fiches_sans_lecture`) ; BHP la crée, la modifie et la supprime, Smart ne la lui renvoie pas. **Pas de `tracabilite_envoi`** (ni à l'enregistrement ni à la suppression) : seule la traça standard est écrite (auteur `token - user_bhp`, date BHP). Champs : `gamme_vidange_code` (12, unique) et `gamme_vidange_libelle` (25). `supprimer()` bloque si la gamme est utilisée par une `formule` ou un `formule_detail` (réponse `success:true` + message côté API). Testé : création, modification sans doublon, liste, validation, suppression, GET refusé, aucune ligne `t_tracabilite_envoi` créée |
| formule_variant | ✅ (ajouté 2026-10-09) | non concerné (pas de `lier_*`, droit `profil_formule`). Champs : `formule_variant_code` (12 caractères au plus, unique par validation — pas d'index en base) et `formule_variant_libelle` (50). **`formule_variant_active` est renvoyé en GET mais ignoré en POST** : changer la variante active passe par `activer()` (route web), qui lance le job `envoyer_formule_vers_production_apres_change_formule_variant_active` ; une variante créée par le transfert est donc toujours inactive. Elle est aussi **vide** : le transfert d'une formule n'intègre les compositions et le détail que pour la variante active (`formule_variant::getActive()`), et la copie d'une variante existante (`dupliquer()`) reste une action web. `supprimer()` refuse la variante active (réponse `success:true` + message côté API) et **supprime en cascade** les `t_composition` et `t_formule_detail` de la variante supprimée, comme le fait le formulaire web (13 308 compositions par variante dans la base de dev) ; testé uniquement sur une variante temporaire. La traça d'envoi `T_Formule_Variant` est écrite pour toutes les centrales actives (fiche non liée aux centrales) |
| ventilation | ✅ (ajouté 2026-10-07) | non concerné (pas de `lier_*_centrale`, droit `profil_centrale`). Lien `lier_modele_impression` : `"modele_impression": {"modele_impression_code": "..."}` résolu par `resoudre_liaisons()` (`null` ou code inconnu → `modele_impression_id = 0`, la validation `numeric` l'accepte : la ventilation est alors enregistrée sans modèle) ; envoyer `modele_impression` avant ses ventilations. L'`enregistrer()` d'origine n'écrivait aucune traça : ajouté `ecrire_traca_std` + `ecrire_tracabilite_envoi('T_Ventilation')`. `supprimer()` d'origine ne vérifie aucun usage (le seul contrôle présent en commentaire concernait `nature_incident`, copié d'une autre fiche) : une ventilation encore utilisée par un chantier (`chantier.ventilation_id`) peut être supprimée. Table vide en base de dev |
| modele_impression | ✅ (ajouté 2026-10-07) | non concerné (pas de `lier_*`, droit `profil_centrale`). Référencée par `ventilation.modele_impression_id` et `chantier.modele_impression_id` (`chantier::lier_modele_impression` : envoyer `"modele_impression": {"modele_impression_code": "..."}` dans un chantier). Le formulaire web ne gère qu'une partie des colonnes ; `executable`, `modele_bl`, les décalages (`dec_verticale_*`, `dec_horiz_*`) et les noms d'imprimantes ne passent que par l'API. Corrigés au passage : (1) les règles de validation s'appelaient `dec_vertical_bl`/`dec_vertical_pesses` (colonnes réelles `dec_verticale_bl`/`dec_verticale_pesees`) et `dec_horiz_*` n'avaient aucune règle → ces champs n'étaient jamais enregistrés ; (2) `supprimer()` testait `$parametre` (variable inexistante) au lieu de `$ventilation` → erreur à chaque suppression et blocage jamais déclenché. Le contrôle sur `chantier` reste commenté dans `supprimer()` (comme à l'origine), donc un modèle encore utilisé par un chantier peut être supprimé. Migration `2026_10_06_1700_V905000_BAM_t_modele_impression_id_modele_impression` nécessaire sur les bases qui ont encore l'ancienne clé `id_modele_imp`. Table vide en base de dev |
| modele_qr_code | ✅ (ajouté 2026-10-05) | non concerné (pas de `lier_*`). Champs : `modele_qr_code_code` (max 12) et `modele_qr_code_trame` (max 255, refusée au-delà). Référencée par `chantier.modele_qr_code_id` (aucune relation `lier_modele_qr_code` sur `chantier`, donc non résolue par `resoudre_liaisons()` à l'envoi d'un chantier) ; `supprimer()` d'origine ne vérifie pas cet usage, conservé tel quel (aucun chantier ne l'utilise dans la base de dev). Table vide en base de dev |
| banque | ✅ (ajouté 2026-10-05) | non concerné (pas de `lier_*_centrale`). `commune_id` résolu dans `enregistrer_api()` depuis `"commune": {commune_code_postal, commune_ville, commune_code_insee}` via `commune::chercher_id_commune()` (comme client/chantier, `t_commune` n'ayant pas de `*_code`). Le GET renvoie `lier_commune` avec toutes les colonnes de `t_commune` (ids internes inclus) faute de colonne code. `enregistrer()` remet `commune_id`/`banque_client` à 0 s'ils sont absents (le formulaire web les envoie toujours) : `enregistrer_api()` conserve donc la valeur existante pour une mise à jour partielle. Colonnes `banque_bic`/`iban`/`libelle1,2`/`rib_*` `NOT NULL` : un `null` envoyé est stocké `''` (testé). `supprimer()` bloque si utilisée par un client (testé) |
| commercial | ✅ (ajouté 2026-10-05) | non concerné (pas de `lier_*_centrale`). Liaisons imbriquées : `"fonction": {"fonction_code": "..."}` et `"commercial_responsable": {"commercial_code": "..."}` (le responsable est un autre commercial ; `null` → `0`). Corrigé au passage : `commercial::lier_commercial_responsable()` pointait vers un modèle `commercial_responsable` **inexistant** (ni classe ni table) → silencieusement ignoré par `resoudre_liaisons()` ; il pointe maintenant vers `commercial`. À la création sans `fonction`, `fonction_id` est forcé à 0 (colonne `NOT NULL` sans défaut, l'insert plantait sinon). `commune_id` existe en base mais n'est pas géré par `enregistrer()` (ni par le formulaire web) : non traité. `supprimer()` bloque si utilisé par un devis (testé) |
| echeance | ✅ (ajouté 2026-10-05) | non concerné (pas de `lier_*`, référencée par `chantier.echeance_id`, `client.echance_id` et `parametre.echance_id` — **`echance_id` sans « e » est le vrai nom de colonne** pour client/parametre, pas une faute du code ; la relation correspondante sur `client` s'appelle `lier_echance`, donc clé JSON `echance` en POST/GET côté client). `echeance_actif` : le `0` explicite est bien conservé (validation `boolean`, hidden `0` dans le formulaire). `supprimer()` bloque si utilisée par parametre/client/chantier (testé sur `F03000`, utilisée par un client) |
| famille_client | ✅ (ajouté 2026-10-02) | non concerné (pas de `lier_*`, référencée par `sous_famille_client.famille_client_id`). `supprimer()` bloque si une sous-famille l'utilise (réponse `success:true` côté API avec le message de blocage, comme les autres fiches, pour éviter qu'un retry BHP boucle). Nom de table de traça d'origine conservé : `T_Famille_Client` (C majuscule) ; ajouté au passage l'écriture de traça d'envoi sur la suppression, qui n'existait pas alors que la création l'avait |
| typologie_client | ✅ (ajouté 2026-10-02) | non concerné (pas de `lier_*`). Comme `typologie_article`/`reglage_trappe`, `enregistrer()`/`supprimer()` d'origine sans contrôle de droit ni vérification d'usage avant suppression ; conservé tel quel. Table vide en base de dev au moment des tests |
| categorie_client | ✅ (ajouté 2026-10-02) | non concerné (pas de `lier_*`, référencée depuis `client.categorie_client_id` — `supprimer()` bloque si un client l'utilise ; droit `profil_fichier_crm`). Table vide en base de dev au moment des tests |
| ajout | ✅ (ajouté 2026-10-02) | ✅ — `parametre_integration_ajouts` (**pluriel**, d'où `$colonnes_parametre_integration` dans `api_transfert_controller` : sans ça `resoudre_centrales()` cherchait `parametre_integration_ajout`, inexistante, et retombait toujours sur le mode local). Liaisons imbriquées résolues par `resoudre_liaisons()` : `unite`, `tva`, `famille_article`, `groupe_tarif`, `typologie_article`, `fournisseur`. Corrigé au passage dans `supprimer()` : le contrôle d'usage dans les compositions testait `composition_type = 6` (« rien ») au lieu de `5` (ajout manuel) — il ne bloquait donc jamais (161 compositions de type 5 pointent vers des ajouts en base, 0 de type 6) |
| typologie_article | ✅ (ajouté 2026-10-02) | non concerné (pas de `lier_*`, référencée depuis `formule`/`zone` via `lier_typologie_article` mais jamais l'inverse). Comme `reglage_trappe`, `enregistrer()`/`supprimer()` d'origine n'avaient aucun contrôle de droit ni vérification d'usage avant suppression ; conservé tel quel. Longueurs de validation cohérentes avec les colonnes (`varchar(12)`/`varchar(50)`) |
| reglage_trappe | ✅ (ajouté 2026-09-29) | non concerné (pas de `lier_*`, référencée depuis `vehicule.reglage_trappe_id` mais sans relation `lier_*` sur `vehicule`, donc pas de blocage de suppression prévu — contrairement à groupe_tarif/famille_article, `enregistrer()`/`supprimer()` d'origine n'avaient aucun contrôle de droit `profil_fichier_*` ; conservé tel quel, pas ajouté de contrôle qui n'existait pas) |

**commande** a un traitement propre, comme formule :
- GET (`demander_fiche`) : chaque commande reçoit un tableau imbriqué **`ligne`** (toutes ses `ligne_commande`, retrouvées par `commande_code`), chaque ligne avec un champ **`article_code`** résolu selon `ligne_commande_type_article` : 0→`formule`, 1→`service`, 2→`ajout` (catalogue `t_ajout`), 3 et 5→`produit`, 4→`zone` (résolution groupée par type, pas requête par requête — reste correct même en `code=ALL`). Type `9` (ligne "commentaire", découvert en vérifiant les vraies données) et tout type non couvert : `article_code` reste `null`.
- POST (`enregistrer_api`) : symétrique — chaque ligne du payload envoie `article_code` (même nom que le GET) + `ligne_commande_type_article`, résolu en sens inverse (code → id) par `integrer_lignes_commande_api()`, qui **remplace tout** (delete + réinsertion) pour ce `commande_code`, comme `composition` côté formule. La ligne de type 0 (formule) fait autorité sur `formule_id` de la commande (cascade, comme `ligne_commande_enregistrer()` côté web).
- ⚠️ **Ordre important** : les lignes sont remplacées **avant** d'appeler `enregistrer()`, car celle-ci valide (portage de `commande_valider_tr.php`) que chaque ligne *déjà en base* référence un article rattaché à la centrale soumise — avec d'anciennes lignes d'une autre centrale, cette validation échouerait à tort si elle passait après. Le tout est dans une **transaction** (`DB::beginTransaction`/`commit`/`rollBack` selon `success` de la réponse `enregistrer()`) : si l'enregistrement de la commande échoue pour une autre raison, le remplacement des lignes est annulé avec. Testé de bout en bout (payload réel, échec puis succès, rollback vérifié).
- **Non répliqué** dans `integrer_lignes_commande_api()` (le payload BHP est supposé déjà cohérent) : plafond de quantité du type 3 (`produit_maximum`), unicité (une seule ligne type 0/5, une seule ligne type 4), recalcul de prix des BL existants (`repercuterPrixLigneCommandeSurBl`). Le prix (`ligne_commande_prix_force_prix`) est toujours fourni par l'appelant, jamais recalculé côté serveur (idem web).
- `commande_controller` a le même bug de coercion booléenne que les autres fiches (`$request->has($champ) ? 1 : 0` sur une bonne dizaine de champs `commande_confirmer_*`/`commande_complement`/etc.) — pas corrigé, cf. section formule plus haut.

**formule** a un traitement propre en plus du pattern standard :
- `enregistrer_api()` résout `centrale_id` depuis `centrale_code` (pas de relation `lier_centrale` sur ce modèle) et le merge dans la requête — nécessaire pour le bloc `formule_detail` de `enregistrer()`, qui lit `$request->input('centrale_id')` directement.
- `formule_detail` est envoyé imbriqué (`"formule_detail": {...}`) mais lu à plat par `enregistrer()` : `enregistrer_api()` aplatit l'objet dans la requête (en excluant `id_formule_detail`/`formule_id`/`centrale_id`/`created_at`/`updated_at` pour ne pas écraser ceux déjà résolus), et fixe `formule_detail->formule_variant_id` à la variante active (`formule_variant::getActive()`), jamais renseigné auparavant.
- `composition` (tableau de lignes) est intégré par `integrer_composition_api()` : remplace tout (delete + réinsertion) pour le couple formule/centrale/variante active. Chaque ligne envoie `composition_produit_code`/`composition_produit_libelle` tels quels (mêmes noms que le GET) ; `produit_id` est résolu via `produit_code` seulement pour `composition_type` 0-4 (produit catalogue), pas pour 5 (ajout manuel) ni 6 (rien).
- `demander_fiche()` (GET) renvoie aussi `composition` et `formule_detail` imbriqués pour la centrale de `centrale_code` (variante active), symétrique du POST. `centrale_code` est **obligatoire** pour `fiche=formule` en GET (sinon réponse `{success:false, message:"Centrale obligatoire."}`).
- **`composition` et `formule_detail` sont traités comme des fiches à part entière (2026-10-09)**, avec les mêmes règles que le premier niveau (`preparer_chargement()` + `masquer_cles_relations()` dans `api_transfert_controller`) : colonnes de la table **sans la clé primaire ni `created_at`/`updated_at`** (plus d'`id_composition` / `id_formule_detail` dans la réponse), champs invisibles du token `exterieur` retirés, et relations `lier_*` **de leur modèle** chargées avec leur code, la clé interne étant masquée : `composition` renvoie `lier_centrale` (`centrale_code`), `lier_formule` (`formule_code`) et `lier_formule_variant` (`formule_variant_code`), `formule_detail` renvoie `lier_formule_variant`. Les colonnes `centrale_id`, `formule_id`, `produit_id`, `formule_variant_id` restent présentes. `formule_detail` n'a pas de `lier_formule` ni de `lier_centrale` (absents du modèle) : à ajouter si BHP doit les recevoir.
- **`composition::lier_produit` (2026-10-12)** : relation `belongsTo` dont la table dépend du type de la ligne — `t_produit` pour `composition_type` 0 à 4, `t_ajout` pour 5 (`produit_id` contient dans les deux cas l'id de l'article ; les autres types, dont 6 « rien », retombent sur `t_produit` et renvoient `null`). Elle marche en chargement ligne par ligne (`$composition->lier_produit`) mais **pas avec `with('lier_produit')` / `load()`** : Laravel construit alors la relation sur un modèle vide, sans type, et interroge `t_produit` pour toutes les lignes (une ligne de type 5 reviendrait `null`). Pour une collection, utiliser `composition::charger_lier_produit($compositions)`, qui charge en deux requêtes (une par table) et choisit la table ligne par ligne. Le GET d'une formule l'utilise : chaque ligne renvoie `lier_produit` = `{"produit_code": "..."}` (types 0 à 4 : code du produit ; **type 5 : code de l'ajout, lui aussi sous le nom `produit_code`** — alias SQL `ajout_code AS produit_code`, pour que la forme soit la même quel que soit le type) ou `null` (article absent / type 6) ; la clé interne est masquée, et un code invisible pour les tokens `exterieur` n'est pas renvoyé. `getBelongsToRelations()` et `resoudre_liaisons()` ignorent les relations listées par `relationsConditionnelles()` du modèle. ⚠️ À l'envoi (`integrer_composition_api()`), une ligne de type 5 garde `produit_id = 0` (choix d'origine : l'ajout manuel n'est pas cherché dans le catalogue, son code est stocké tel quel) : son `lier_produit` est donc `null` tant que le POST ne résout pas l'ajout par `composition_produit_code`. Toutes les formules d'une requête sont chargées en **une requête** par table (`code=ALL` passe de 5,4 s à 2,8 s sur la base de dev, mêmes lignes). Un GET renvoyé tel quel en POST fonctionne : les objets `lier_*` sont ignorés par `integrer_composition_api()` (lignes construites champ par champ) et par l'aplatissement de `formule_detail`.
- **`lier_*` de `formule` et `formule_detail` (vérifiés et corrigés le 2026-10-13)** : tous les `lier_*` pointent sur une colonne, une table et un code existants (lignes de dev toutes résolues). Ajoutés : `formule::lier_classe_reduction_prg`, `lier_famille_beton_echantillon` (+ règle de validation `famille_beton_echantillon_id`, jusque-là jamais enregistré) et `formule_detail::lier_formule`, `lier_gwr`. Écriture : les `lier_*` de `formule` se lisent **à la racine** du payload (`"gamme_vidange": {"gamme_vidange_code": "…"}`, `"classe_reduction_prg": {…}`…), ceux de `formule_detail` **dans l'objet `formule_detail`** (`"formule_detail": {"gamme_vidange": {"gamme_vidange_code": "…"}, "gwr": {"gwr_code": "…"}}`), résolus par `enregistrer_api()` (`resoudre_liaison_detail()`) ; `null` ou code inconnu → 0. À défaut d'objet, `formule_detail.gamme_vidange_id` (entier, forme du GET) est accepté. Gamme absente du détail : la gamme déjà enregistrée est conservée. **Bug corrigé** : `formule_detail.gamme_vidange_id` était aplati à la racine et écrasait la gamme de la *formule* (un aller-retour GET→POST la corrompait), alors que le détail la lisait sous `formule_detail_gamme_vidange_id`, jamais renseigné par l'API (détail toujours à 0). Testé : objets imbriqués, détail sans gamme (conservée), forme du GET, `null`, GET, aller-retour complet. **Code inconnu refusé (2026-10-13, `formule` uniquement)** : un objet lié envoyé avec un code qui n'existe pas (racine : tva, type_beton, gamme_vidange… ; détail : `formule_detail.gamme_vidange`, `formule_detail.gwr`) fait refuser la formule *avant toute écriture* — `success:false`, `message: "Fiche liée introuvable !"`, `errors: {"gamme_vidange": ["Le code « X » de gamme_vidange est introuvable."]}` (toutes les liaisons en erreur sont listées ; clé `formule_detail.<fiche>` pour le détail). Un objet à `null` (liaison vidée → 0) ou sans clé de code n'est pas concerné. Dans une liste, seule la formule en erreur est refusée. Les autres fiches gardent la convention « code inconnu → 0 » de `resoudre_liaisons()`. Implémenté dans `formule_controller::liaisons_introuvables()` / `resoudre_liaison_detail()`
- **Booléens (corrigé le 2026-09-24)** : `enregistrer()` forçait les 8 booléens (`formule_active`, `formule_protegee`, `formule_definir_production`, `formule_tarif_imprimable`, `formule_lavage`, `formule_normalisee`, `formule_tps_std`, `formule_volume_std`) via `$request->has($champ) ? 1 : 0` : un `0` explicite envoyé par BHP était enregistré à `1`. Le bloc `merge()` est supprimé ; `resources/views/formule/form.blade.php` a maintenant un `<input type="hidden" value="0">` devant chaque checkbox (`value="1"`), comme les autres fiches, et la validation `boolean` + `fill(validated())` suffit. Un booléen absent du payload n'est plus forcé à 0 (valeur conservée en modification, défaut de colonne en création). Les autres fiches câblées (chauffeur, client, vehicule, chantier, zone...) n'avaient déjà plus ce bug.
- **`formule_lavage`** : checkbox et validation existaient mais la colonne n'avait jamais été créée (ligne commentée dans la migration V900) — la valeur était ignorée silencieusement. Migration `2026_09_24_1443_V904005_BAM_t_formule_champs_checkbox_boolean` : crée la colonne et passe les 7 autres checkbox (`int(1)`/`bit(1)`) en `boolean`.
- **Validation de `formule_detail` avant `$formule->save()` (corrigé le 2026-09-24)** : avant, un `formule_detail` invalide (ex: `formule_na` manquant) renvoyait `success:false` alors que la formule était déjà écrite, sans détail, traça ni centrales.

`classe_consistance` a par ailleurs un ancien endpoint API distinct et toujours actif (`routes/api.php`, groupe `v1/classe_consistance`, `POST /enregistrer`). `classe_consistance_controller::enregistrer()` avait une détection `$request->is('api/*')` pour résoudre son propre id via son code (redondante avec `enregistrer_api()` depuis que la fiche est câblée sur `/transfert/`) — retirée le 2026-09-05, c'était un test. `afficher_formulaire()` garde en revanche sa détection `$request->is('api/*') || $request->expectsJson()` pour servir les routes GET `/api/v1/classe_consistance/{id}` et `/all` en JSON, non touchée.

---

## Tests (`tests/Feature/ApiTransfert/`)

Une classe PHPUnit par fiche, dans l'ordre du tableau ci-dessus (`OrigineTransfertTest`, `FournisseurTransfertTest`, ... `ProduitTransfertTest`) + `GeneriqueTransfertTest` (401 sans token, 404 fiche inconnue, nom de fiche insensible à la casse, objet unique normalisé en liste, `tracabilite_envoi_envoye` en GET avec token `bhp`, DELETE avec `code` en query string).

Toutes héritent d'`ApiTransfertTestCase`, qui :
- crée un vrai token Sanctum `BHP_TEST` (ability `bhp`) et met les droits de `$droitsProfil` à 5 sur le profil de `User::first()` (en oubliant les guards pour qu'un changement de droit en cours de test soit vu) ;
- fournit 13 scénarios standard hérités : GET (401, liste, par code, code inconnu), POST (création, mise à jour sans doublon, liste de 2 fiches, sans code, sans champ obligatoire, ligne invalide dans la liste), DELETE (ok, code inconnu, sans droit → `success:true` mais fiche conservée) ; la traça est vérifiée (auteur `BHP_TEST - Brody`, `tracabilite_date_heure` = `tracabilite_envoi_date_heure_bhp`, date d'intégration réelle renseignée).

Chaque classe fille déclare sa config (`$fiche`, `$table`, `$colonneCode`, `$droitsProfil`, `$champObligatoire`, `payloadValide()`, `champModifiable()`) et ajoute ses scénarios propres (longueurs max, fiches liées imbriquées, centrales selon `parametre_integration_<fiche>`, suppressions bloquées « utilisée dans... », booléens à 0...). Un test hérité sans objet pour une fiche est surchargé en `markTestSkipped()`.

Les tests tournent sur la base de dev (`.env`) avec `DatabaseTransactions` : tout est annulé en fin de test. Éviter de les lancer pendant qu'on édite les mêmes fiches dans l'appli (risque de deadlock MySQL, faux échec).

```
php artisan test tests/Feature/ApiTransfert                       # toutes les fiches
php artisan test --filter=OrigineTransfertTest                    # une fiche
php artisan test tests/Feature/ApiTransfert/VehiculeTransfertTest.php   # vehicule (--filter matcherait aussi TypeVehicule)
```

Au 2026-09-24 : 696 tests — 684 passés, 0 échec, 12 skippés (faute de données en base ou sans objet pour la fiche). Pour une nouvelle fiche câblée, créer `<Fiche>TransfertTest` sur le même modèle.

Le 2026-10-05, `ChantierTransfertTest` lit `t_chantier_centrale` par ids (`chantier_id`/`centrale_id`, jointure sur `t_centrale` pour comparer les codes) et ajoute `test_post_rattache_les_centrales_par_id` ; à relancer une fois la migration `2026_10_05_1540_V905000_BAM_t_chantier_centrale_avec_id` appliquée (pas encore exécuté à cette date).

À compléter au fil de l'eau, un contrôleur à la fois — voir `Architecture.md` (§6, bloc « Intégration BHP ») pour le suivi haut niveau.
