# Chantier — Endpoint apply XLSX → BDD pour les templates rapport > ## ✅ CHANTIER LIVRÉ EN PRODUCTION > **Vérifié le 2026-05-29** — Ne plus relire pour valider la livraison. **Date** : 2026-05-07 (livraison initiale + itérations correctives session entière) **Repo** : coolcare-app (port à prévoir sur missioflow-app à l'identique une fois validé en prod) **Type** : Nouvelle feature admin (refonte de l'outil de review templates) **Origine** : Suite logique du chantier review (admin/report_templates_review.php) — il fallait pouvoir réellement appliquer en BDD les sélections faites dans l'UI au lieu de juste exporter un JSON inutilisable. ## Contexte L'outil [admin/report_templates_review.php](public/admin/report_templates_review.php) permettait depuis 2026-04-28 de comparer un XLSX cahier des charges (livré par Aurélien) contre la BDD `report_template_steps` et de cocher item par item ce que l'on voulait garder. Mais l'application des sélections n'existait pas (lecture seule, exportait juste un JSON). Ce chantier livre l'endpoint complet d'application avec toutes les sécurités nécessaires pour qu'Aurélien puisse l'utiliser en autonomie sur la prod sans casser une intervention en cours, **plus** une vue de comparaison 3 colonnes post-apply pour la validation visuelle, **plus** un bouton apply massif pour traiter les ~20 templates en une passe. ## Décisions architecturales ### Cible exclusive `report_template_*` uniquement (`report_template_steps`, `report_template_step_options`, `report_template_phases`, `report_templates`). **Ne touche jamais** `intervention_workflow_*`. Les workflows en cours gardent leur snapshot intact. ### Soft delete vs hard delete **Soft delete** (`deleted_at DATETIME NULL`). Trois raisons : 1. `intervention_workflow_steps.template_step_id_source` pointe vers `report_template_steps.id`. Hard delete = FK orpheline sur les workflows historiques (PDF rétrospectifs cassés). 2. Si Aurélien livre v8 supprimant un step puis v9 le réintroduisant, on flippe `deleted_at = NULL` au lieu d'INSERT — préservation des ids et des liens FK. 3. Rollback manuel trivial (`UPDATE deleted_at = NULL`). Convention : `WHERE deleted_at IS NULL` partout dans le code de lecture template. ### Granularité par template + Apply massif 1 appel API = 1 template. Le front itère sur les N templates (avec barre de progression). Permet de stopper proprement sur erreur, et d'appliquer un template en test sans risquer le tout-ou-rien. **Bouton "Apply TOUS"** (ajout 2026-05-07 fin de session) : itère côté front sur tous les templates avec `db_template_id`, en séquentiel. Confirmation explicite (taper `APPLY ALL`), progression live ligne par ligne, récap final cumulé avec liste des échecs. Pas d'endpoint serveur dédié — chaque template reste sa propre transaction, le bouton orchestre côté JS. ### Garde-fous obligatoires (Aurélien-ready) Tous activés en permanence, pas de mode "permissif" : - **Pre-check workflows en cours** : refuse 409 si `intervention_workflows.status IN ('not_started','in_progress')` pour ce `template_id_source`. Renvoie la liste des workflows bloquants pour que l'admin puisse aller les terminer manuellement. - **Pre-check cross-template parent_step_id** : `fk_steps_parent` n'a pas de garde-fou DB "même template_id". Si un step d'un autre template référence un step de celui qu'on modifie, refuse 409 (situation pathologique mais possible en théorie). - **Lock migration_id** : refuse soft delete si le step lui-même OU **n'importe quel descendant récursif** porte un `migration_id` dans `rules_json`. Défense en profondeur (front lock visuel + service refus). - **sha256 verification** : le XLSX uploadé à l'apply doit avoir le même sha256 que celui calculé au diff initial. Refuse 422 sinon (évite "j'ai uploadé v07 au diff puis v08 à l'apply par erreur"). - **dry_run par défaut** : `dry_run=1` si non spécifié explicitement. L'apply réel nécessite `dry_run=0` POSTé délibérément. - **Radios front (XOR)** : impossible de cocher (1,1) ou (0,0). API refuse aussi ces cas en defense-in-depth. ### Cascade soft delete Quand on soft delete un step (action `SOFT_DELETE_DB`, l'admin retire un step orphelin sans le remplacer) : 1. Recherche récursive de tous les descendants via `parent_step_id`. 2. Vérifie qu'aucun descendant ne porte `migration_id` (sinon refus avec id du protégé). 3. Soft delete du step + de tous ses enfants (depth-first) + de toutes leurs options (`report_template_step_options.deleted_at`). Note : le `ON DELETE CASCADE` du DDL ne s'applique que sur hard delete. La cascade soft est implémentée manuellement dans le service. ### INSERT_REPLACE_DB : reparent au lieu de cascade (fix bug 2026-05-07) **Bug** : quand l'admin coche XLSX sur un parent `common_divergent` (ex: `ETAT DE LA MACHINE A L'ARRIVEE` avec is_required différent), l'apply ancien faisait `softDeleteStepCascade(ancien parent)` qui tuait silencieusement TOUS les enfants actifs (DESCRIPTION/ACTIONS/PROBLEME RESOLU?), ignorant les sélections `keep_db` cochées par l'admin pour ces enfants. Résultat : 60+ enfants soft-deleted sur 18 templates malgré l'intention de les conserver. **Fix** : pour `INSERT_REPLACE_DB`, ne plus cascader. Étapes : 1. `insertStepFromXlsx` insère le nouveau parent depuis XLSX → nouvel id 2. `reparentActiveChildren(oldParentId, newParentId)` re-rattache tous les enfants actifs vers le nouveau parent 3. `softDeleteStepWithoutCascade(oldParentId)` soft delete l'ancien parent **sans cascade** (les enfants ont déjà migré) La cascade complète n'est utilisée que pour `SOFT_DELETE_DB` pur (admin retire un orphelin), pas pour `INSERT_REPLACE_DB`. ### Bump version_label Format `.YYYYMMDD`. Exemples : - `v1` → `v1.20260507` - `v1.20260101` → `v1.20260507` (suffixe horodaté remplacé) - `v07.20260101.beta` → `v07.20260101.beta.20260507` (suffixe non-strict, on append) ### Audit log Table dédiée `report_templates_apply_audit` avec : - `apply_run_id` UUID v4 partagé par toutes les opérations d'un même appel (rollback unitaire possible) - `old_state_json` / `new_state_json` (snapshot complet par opération) - `dry_run` (les essais sont aussi loggés) - `source_xlsx_filename` + `source_xlsx_sha256` (traçabilité du XLSX source) - `verified_at` (rempli quand l'admin clique "tout est OK" après vérif visuelle) ### Snapshot pré-apply + Comparaison 3 colonnes (ajout 2026-05-07 fin de session) Table dédiée `report_templates_backup` (1 ligne par `apply_run_id`) avec : - `snapshot_json` : image complète pré-apply (`{phases:[], steps:[], options:[]}` actifs, indexes par id) - `version_label_before` - Lien 1-1 avec `report_templates_apply_audit` via `apply_run_id` Le service `apply()` capture 2 snapshots autour de l'écriture : 1. `dbBefore` : juste avant `executeAllPairs` (insère dans `report_templates_backup` si `dry_run=0`) 2. `dbAfter` : juste après `commit` ou `rollback` Puis `buildComparisonData()` combine `xlsx` (extrait du diff payload) + `dbBefore` + `dbAfter` en 3 listes plates et les renvoie dans la réponse JSON. Le front les affiche côte-à-côte dans la **modale étape 3/3** (CSS `.cmp-aligned-row`, 3 colonnes XLSX/Avant/Après avec badges OBLIGATOIRE, options, parent_item alignés). Cette modale est la **seule garantie visuelle** que l'admin a après un apply réel — d'où l'importance de la rendre exhaustive. ### Workflow UI 3 étapes 1. **Preview** : appel `dry_run=1`, modale affiche les opérations + résumé 2. **Confirmation** : checkbox + retape le nom du sheet (friction volontaire) 3. **Apply réel** : `dry_run=0`, retour stats + **comparaison 3 colonnes** (XLSX / ancienne BDD / nouvelle BDD) ### Renumber sort_order canonique (fix bug 2026-05-07) L'ancien `renumberSortOrdersForTemplate` triait par `(phase.sort_order, sort_order, id)`. Bug rencontré : si le XLSX numérote un step à `sort_order=44` qui collisionne avec un step BDD préservé (enfant migration_id ou autre), le tri par `id` plaçait le nouveau step XLSX entre le parent BDD (id