# Skill "module Vente" — recette à répliquer sur les autres modules
> Référence produite le 21/07/2026 sur le périmètre **Vente** (Clients, Cartes, Encaissements,
> Grand Livre). Objectif : servir de check-list/copier-coller quand on refait le même travail sur
> un autre module (Achat, Coffre, Compte, Stocks...). À lire avec `DESIGN.md` (journal Phase 4) et
> `CLAUDE.md` (règles générales du projet).
## 1. Composants du design system utilisés (public/css/design/components.css)
| Besoin | Classe / mécanisme |
|---|---|
| Panneau unique filtre+tableau (remplace card-dans-card) | `.ssm-panel` / `.ssm-panel-header` / `.ssm-panel-body` |
| Onglets horizontaux hors card-header (ex. Clients/Groupes) | `.ssm-tabs` / `.ssm-tabs-link` |
| Rangée de filtres + action à droite garantie | `.ssm-panel-toolbar` (flex) + `.ssm-panel-actions` (`margin-left:auto`) |
| Bouton plein écran (attaché au coin du card, pas d'espace réservé) | `.ssm-panel-fullscreen-btn` (position absolute) + JS `ssm_panel_fullscreen(selector)` |
| Boutons Imprimer/Exporter génériques au niveau du tableau | bloc statique `.ssm-table-toolbar` + JS `ssm_table_toolbar(panelSelector, {titre, filtres})` |
| Totaux/KPI en carte (ex. Situation client) | `.ssm-kpi-row` / `.ssm-kpi` / `.ssm-kpi-label` / `.ssm-kpi-value` / `.ssm-kpi-sub` |
| Totaux "juste des chiffres" sans carte (ex. soldes Grand Livre) | `.ssm-stat-row` / `.ssm-stat` / `.ssm-stat-label` / `.ssm-stat-value` (`.ssm-stat-positive/negative`, `.is-loading`) / `.ssm-stat-sub` / `.ssm-stat-skeleton` |
| Case à cocher "option" stylée (ex. Bons/Facturation) | `.ssm-options-row` / `.ssm-option-toggle` |
| Sous-menu de module avec thumb glissant | `.ssm-module-nav` (piste) + `.ssm-module-nav-thumb` (JS positionne, ne pas styliser en CSS statique) |
| Navigation AJAX inter-pages (pas de rechargement complet) | attribut `data-ssm-nav="1"` sur les `` + conteneur `#ssm_module_content` |
## 2. Principe transversal : navigation AJAX inter-pages
**Zéro changement de contrôleur nécessaire.** `Controller::view()` détecte l'en-tête `X-Ssm-Nav`
(posé par `ssm_nav_ajax()`, ajax.js) et renvoie directement le contenu de la vue au lieu du layout
complet. Pour équiper un module :
1. Dans le sous-menu du module (équivalent de `menu_client.php`), ajouter `data-ssm-nav="1"` sur
chaque ` `, plus `role="tablist"`/`role="tab"`/`aria-selected` et le span
``.
2. Dans **chaque vue** du module, envelopper tout ce qui suit l'include du sous-menu dans
`...
` (ouvrir juste après l'include, fermer à la toute fin
du fichier, après le ``). Sans ce wrapper, la navigation retombe automatiquement sur
un remplacement complet de `#body_app` (pas de régression, juste moins fin).
3. Rien d'autre : `ssm_nav_ajax()` gère seul l'historique (pushState/popstate), le thumb glissant
+ sa direction, l'animation d'entrée/sortie du contenu, et la réinitialisation des select2
(`ssm_init_select2()`) du contenu injecté.
**Piège vécu et corrigé (2)** : naviguer (clic sur un onglet du sous-menu, `data-ssm-nav`) alors
qu'une modale Bootstrap est ouverte (ex. "Ajouter" sur Clients) détruit le DOM de cette modale
(elle vit dans `#ssm_module_content`, remplacé par la navigation) **sans que Bootstrap ait pu
nettoyer son `.modal-backdrop`** (ajouté comme frère de ``, donc en dehors de la zone
remplacée) ni les classes qu'il pose sur `` (`modal-open`, `padding-right`). Résultat : un
fond invisible reste bloqué pour toujours et intercepte tous les clics sur toute l'application, y
compris la top bar — symptôme signalé : "je change vers Carte, plus aucune modale ne fonctionne,
ni la top bar, ni rien". Fix (systémique, dans `ssm_nav_ajax()`, profite à tous les modules) :
avant tout remplacement de contenu, fermer les modales ouvertes (`$('.modal.show').modal('hide')`)
**et** nettoyer sans condition tout backdrop/classe body restants (`$('.modal-backdrop').remove()`
+ `$('body').removeClass('modal-open')`) — ne jamais compter sur le cycle de vie normal de
Bootstrap quand le DOM de la modale peut disparaître de force.
**Piège vécu et corrigé (3), plus sournois** : même en fermant proprement la modale précédente, un
retour utilisateur a persisté ("carte → retour vers client → ajouter → modale affichée mais sans
focus, rien ne fonctionne dedans"). Cause trouvée **en pilotant un vrai Chromium headless**
(Playwright, voir méthode ci-dessous) : `#ssm_module_content.ssm-content-in-droite`/`-gauche`/`-in`
(l'animation d'entrée de la nav AJAX, `components.css`) utilise `animation-fill-mode: both` pour
éviter un flash — mais `both` laisse l'état final de la keyframe (`transform: translateX(0)`, pas
`none`) **posé en permanence** sur `#ssm_module_content` tant que la classe reste sur l'élément, ce
qui n'était jamais retiré après la fin de l'animation. Or **n'importe quel `transform` (même
`translateX(0)`, sans mouvement visible) crée un nouveau conteneur/contexte d'empilement pour tout
descendant `position:fixed`** — exactement le même piège que celui déjà documenté plus haut pour le
plein écran (§3), mais cette fois c'est une **modale Bootstrap** qui se retrouvait piégée : rendue
plus petite que l'écran, et son `.modal-backdrop` (resté enfant de ``, donc hors du piège)
passait par-dessus et interceptait tous les clics - la modale semblait "morte" sans aucune erreur
JS visible. Fix : retirer la classe d'animation (`ssm_module_nav_transition()`, ajax.js) une fois
la durée de l'animation écoulée (`setTimeout`, même délai que le nettoyage de la couche de sortie)
- aucune différence visuelle (l'état "animé fini" et l'état "pas de classe" sont identiques), mais
ça referme le conteneur d'empilement. **Leçon générale** : toute classe qui pose un `transform`
(animation ou transition, `fill-mode: both` ou `forwards` compris) sur un ancêtre de modale/popup
doit être retirée une fois l'animation terminée, jamais laissée en place indéfiniment.
**Méthode utilisée pour trouver ce bug** : impossible à voir par simple lecture de code ou curl (il
faut un vrai rendu + de vrais clics). Un Chromium headless piloté par Playwright (installé à la
volée dans le scratchpad de session : `npm init -y && npm install playwright && npx playwright
install chromium`, pas de dépendance ajoutée au projet) a permis de rejouer le scénario exact
(login → Clients → Cartes (nav AJAX) → Clients (nav AJAX) → clic Ajouter → clic dans un champ) et
d'inspecter en direct le DOM (`page.evaluate(() => ...)` : z-index/position calculés,
`document.elementFromPoint()` pour voir QUEL élément reçoit vraiment le clic, `getComputedStyle`)
- c'est `elementFromPoint()` au centre du champ qui a révélé que c'était le `.modal-backdrop` et
pas le champ qui recevait le clic, pointant directement vers un problème d'empilement plutôt qu'un
handler manquant.
**Piège vécu et corrigé** : ne jamais passer `cache:false` à `$.ajax()` pour ces requêtes — jQuery
ajoute alors `?_=` à l'URL, et le routeur (`public/index.php`) construit `$paths` via
`explode('/', $_SERVER['REQUEST_URI'])` **sans jamais retirer la query string** → le nom du
contrôleur se retrouve pollué et `namespace_resolve()` échoue (404 => `public/404.php` injecté à
la place du contenu). Symptôme observé : "Retour à l'Accueil" + menu disparu.
## 3. Piège CSS le plus coûteux de la session : `overflow:hidden` casse `position:sticky`
`.ssm-panel` avait `overflow:hidden` (pour clipper les coins carrés du header/body contre le cadre
arrondi). N'importe quel ancêtre à `overflow != visible` devient le scroll-port de référence pour
`position:sticky`, et comme `.ssm-panel` ne défile jamais lui-même, ça annulait tout header de
tableau sticky à l'intérieur. **Fix retenu** : ne jamais mettre `overflow:hidden` sur un
conteneur qui pourrait accueillir un descendant sticky — clipper les coins via un `border-radius`
explicite sur le header (coins hauts) et le body (coins bas) à la place.
## 4. Autre piège CSS répété deux fois : la spécificité `:has()`
Une règle `:has(> selecteur)` (attribut + classe + pseudo-classe) est plus spécifique qu'une classe
seule ou même deux classes combinées, et gagne **même avec `!important` sur l'autre règle** si
elle n'a pas elle-même `!important`. Rencontré sur :
- Le plein écran (`.ssm-panel--fullscreen` vs `:has(> .ssm-panel-fullscreen-btn){position:relative}`)
→ fix retenu au final : poser les styles critiques (position/inset/z-index/background) en
**inline avec `element.style.setProperty(prop, val, 'important')` depuis le JS**, qui bat
n'importe quelle règle de feuille de style externe, présente ou future. C'est la solution la
plus robuste pour tout ce qui doit *garantir* d'être au-dessus de tout — ne pas hésiter à
l'utiliser directement plutôt que de chasser un conflit de spécificité CSS.
- Les filtres/totaux en version mobile (`body[data-design] .input-group.input-group-sm` plus
spécifique que la media query) → fix retenu : `!important` sur la media query.
## 5. Impression / export générique (sans backend dédié par module)
`ssm_table_toolbar(panelSelector, {titre, filtres: {"Libellé": "#selecteur"}})` (ajax.js) :
- Injecte une modale commune (une seule pour toute l'appli) au premier appel.
- La modale propose : titre modifiable, afficher les filtres (case), afficher la pagination
actuelle "Page X sur Y" (case), afficher les infos de bas de tableau (case), et une liste de
colonnes à cocher (générée depuis les vraies `` de la table, tout coché sauf "Action").
- Imprime/exporte **exactement ce qui est affiché à l'écran** (respecte le sélecteur de lignes
10/20/50/100/Tout) — pas de re-pagination côté impression.
- Les boutons doivent être placés en HTML **statique** juste au-dessus de la `` visée
(`.ssm-table-toolbar` avec 2 boutons `.ssm-table-print`/`.ssm-table-export`) — **ne jamais**
essayer d'injecter dynamiquement dans `.dataTables_filter` (tenté puis abandonné : trop fragile,
boutons disparus en prod).
- Si le module a un mécanisme d'impression **métier** déjà existant (ex. Grand Livre avec
récapitulatif de solde) : le garder tel quel, à côté des filtres comme une action normale
(type "Ajouter"), et ajouter le mécanisme générique **en plus**, au niveau du tableau — ce sont
deux besoins différents, ne pas les fusionner.
## 6. DataTables : configuration commune (déjà dans `init_datatable()`, ajax.js)
- Longueur de page 10/20/50/100/Tout déjà active par défaut (`lengthChange:true`).
- Traductions françaises **en dur** dans `language` (pas `oLanguage` — clé legacy qui attend
l'ancien format hongrois et ignore silencieusement les sous-clés modernes) — ne plus dépendre
d'un fetch vers `cdn.datatables.net` (échouait silencieusement en local, retombait sur
l'anglais).
- En-tête de tableau sticky déjà actif (`thead th{position:sticky;top:0}` + fond opaque
obligatoire). Topbar déjà `position:sticky;top:0;z-index:20` pour rester au-dessus.
## 7. Perf : vérifier les modèles avant de répliquer un module lourd en données
Le module Encaissements cachait un vrai problème de fond (pas lié au design) : une requête
`UNION ALL` à 8 branches, jointes sur des colonnes sans index, exécutée jusqu'à 3 fois par appel
(deux `fetchAll()` uniquement pour compter + une fois sans LIMIT pour sommer en PHP). Avant de
refaire le design d'un module aux requêtes complexes, vérifier rapidement :
- Y a-t-il un `count(...->fetchAll())` qui devrait être un `SELECT COUNT(*) FROM (...)` ?
- Une somme/total calculée en bouclant du PHP qui devrait être un `SELECT SUM(...)` ?
- Les colonnes de jointure (`source`, `id_source`, `zone`, `id_client`...) ont-elles un index ?
Voir `database/migrations/007_index_encaissements_performance.sql` comme modèle de migration
d'index, et le commit `ab0b6f1` pour le patron de correction PHP.
## 7bis. Totaux qui se rafraîchissent au changement de filtre : ne jamais recharger tout le bloc
Piège vécu sur les soldes du Grand Livre : `load_portion()` remplace toute la zone cible par un
loader générique le temps de la requête → le bloc entier "disparaît" à chaque changement de filtre
("moche" signalé par l'utilisateur). Pour un simple total/compteur qui se met à jour souvent :
1. Rendre la structure HTML (libellés, icônes) **une seule fois**, jamais recréée.
2. Le contrôleur renvoie du **JSON** (`header('Content-Type: application/json'); echo json_encode(...);`),
pas un fragment de vue.
3. Le JS fait un `$.post(..., callback, 'json')`, ajoute `.is-loading` sur les seuls éléments
`.ssm-stat-value` avant l'appel, remplace juste leur texte au retour (`ssm_stat_set()`,
ajax.js) et retire `.is-loading`. Voir `Livre.php::solde()` / `GrandLivreController::solde()`.
4. Avant le tout premier chargement (aucune donnée encore reçue) : un squelette animé
(`.ssm-stat-skeleton`) plutôt qu'un 0 ou un vide.
## 8. Check-list pour un nouveau module
1. Lire ce fichier + `DESIGN.md` (journal) + regarder `app/views/vente/Clients.php` et
`app/views/vente/portion/menu_client.php` comme référence vivante.
2. Sous-menu du module : copier `menu_client.php` (thumb, `data-ssm-nav`, rôles ARIA).
3. Chaque page du module : `.ssm-panel` (ou `.card` si déjà en place et sans besoin de sticky),
`.ssm-panel-toolbar`/`.ssm-panel-actions`, bouton plein écran, `.ssm-table-toolbar` +
`ssm_table_toolbar(...)`, wrapper `#ssm_module_content`.
4. Icônes sur les `` (sémantiques par colonne : calendrier, personne, argent...).
5. Modales : `data-mode="ajout"|"modification"` + `.ssm-modal-icon` (header) + `.ssm-field-icon`
sur les labels + boutons `.ssm-btn`/`.ssm-btn-primary` (voir `carte.php`/`reglage_carte.php`,
`Nouveau_client.php`) — **checklist à part entière, à ne PAS considérer optionnelle/à part** :
- **Boutons `.ssm-btn` partout, y compris les déclencheurs de niveau page** ("Ajouter" du panel,
boutons toggle de dropdown) : sans cette classe précise, le bouton est invisible au scanner de
raccourcis Ctrl+`` (§31, `ssm_raccourci_candidats()` ne regarde QUE `.ssm-btn`) — un
bouton stylé en `.ssm-btn` "visuellement" mais resté en `btn btn-sm bg-primary` ne recevra
jamais Ctrl+A/Ctrl+, même si tout le reste (icônes, data-mode) est fait. Vérifier
avec Ctrl+ en conditions réelles, pas juste visuellement.
- **Notification + fermeture automatique** (§10) sur CHAQUE flux ajout/modification en modale
qui ne fait pas un rechargement de page complet : `ssm_notify()` (jamais `toastr` sur un flux
repris) + `ssm_modal_auto_close('#afficher_div', 5000)` pour un ajout (le formulaire revient
vierge), fermeture directe pour une modification. Utiliser le callback de `load_portion(...,
function(){...})`, jamais un `setTimeout` arbitraire après un appel fire-and-forget.
- Cas où l'auto-fermeture ne s'applique PAS (documenter pourquoi, ne pas l'ajouter quand même) :
un flux qui fait un `location.reload()`/redirection complète de page après l'ajout (l'auto-
fermeture n'a pas de sens juste avant que toute la page change) — remplacer `toastr` par
`ssm_notify` quand même, c'est gratuit et cohérent visuellement.
6. Si le module a des requêtes lourdes/anciennes : passage rapide perf (section 7) avant de se
concentrer sur le visuel.
7. Tester : `php -l`, vérif accolades CSS, login + curl sur chaque page (normal ET avec
`X-Ssm-Nav: 1`), Ctrl+`` sur chaque bouton d'action principal de chaque page (pas
seulement visuel - vérifier que le clic/la modale se déclenche vraiment), puis commit avec
message détaillé (quoi + pourquoi + comment testé).
## 9. Réglages d'affichage par tableau + thème par module (21/07/2026, pilote Vente/Clients)
Demande explicite : laisser l'utilisateur personnaliser l'affichage (alignement, couleurs) mais
**jamais de couleur libre** — uniquement des presets fermés, validés par le design system, pour
garantir un bon rendu quel que soit le choix.
**Par tableau** (bouton engrenage, à gauche du bouton plein écran) :
- HTML : envelopper les deux boutons dans `.ssm-panel-toolbelt` (remplace le
`.ssm-panel-fullscreen-btn` seul en position absolute) :
```html
...
```
- JS : un seul appel dans le script de la vue, comme `ssm_panel_fullscreen()`/`ssm_table_toolbar()` :
`ssm_panel_settings('#mon_panel_id', 'cle_stable_unique')` (ex. `'vente_clients'`). Le panel
**doit avoir un id** (sert de scope aux règles CSS de couleur par colonne). Cet appel branche le
bouton ET applique automatiquement le réglage déjà enregistré au chargement (pas besoin d'ouvrir
la modale pour que ça s'applique).
- Le composant est 100% générique (`ssm_panel_settings`, `ssm_ensure_reglage_modal`, `ssm_reglage_appliquer`
dans `ajax.js` + `App\controllers\parametre\ReglageAffichageController` + `AffichageTable` model) —
aucune modification serveur nécessaire par module, juste ces deux ajouts HTML/JS par panel.
- Presets fermés (voir `AffichageTable::PRESETS_*`/`COULEURS_COLONNE`/`ALIGNEMENTS_COLONNE`) :
entête défaut/accent/sombre/succès/attention et bordure de card défaut/accent/succès/attention/
alerte (portée sur tout le tableau) ; **alignement ET couleur de texte sont réglables par
colonne** (retour utilisateur du 21/07/2026 : "un alignement pour chaque colonne", pas un seul
pour toute la table) — la colonne est identifiée par le **texte de son ``** (comme
`ssm_export_colonnes_html()`), pas son index : robuste si des colonnes sont réordonnées plus tard.
- Persistance : `parametre_affichage_table` (migrations 010 + 011), une ligne par (utilisateur,
cle_table), colonne JSON `colonnes` = `{"Nom de colonne": {"couleur":"accent","alignement":"droite"}}`.
- **Piège vécu et corrigé** : un premier essai appliquait l'alignement au niveau du panel entier
(classe `.ssm-panel.ssm-align-droite`, sans `!important`) — silencieusement sans effet, car la
quasi-totalité des tableaux posent déjà `className: 'text-center'`/`'text-right'` via les
`columnDefs` de DataTables, et les classes Bootstrap `.text-center`/`.text-right` sont elles-mêmes
en `!important`. Sans `!important` d'un côté ET une spécificité au moins égale de l'autre, le
réglage perdait systématiquement face à la classe posée par la vue elle-même ("j'ai choisi
droite mais rien n'est fait", signalé par l'utilisateur). Fix retenu : les règles générées pour
l'alignement ET la couleur par colonne sont désormais scopées par l'**id du panel** (`#mon_panel
table.dataTable tbody td:nth-child(N)`, spécificité largement suffisante) et systématiquement en
`!important` — voir `ssm_reglage_appliquer()` (ajax.js). À reproduire pour tout nouveau réglage
de ce type : ne jamais compter sur la seule spécificité face à du Bootstrap `!important` déjà en
place sur les cellules de tableau.
**Par module** (bouton "Thème" à l'extrême droite du sous-menu, ex. `menu_client.php`) :
- Envelopper le `` existant dans `.ssm-module-nav-bar`, puis appeler
`echo ssm_module_theme_menu_html('nom_du_module');` (vendor/function.php) juste après — génère
le dropdown des 4 directions + un "Revenir au thème global" si une surcharge existe déjà.
`'nom_du_module'` doit être une clé de `namespace_resolve()` (ex. `'vente'`, `'coffre'`...).
- Persistance : `parametre_style_module` (migration 010), scope (utilisateur, module) — n'affecte
QUE les pages de ce module ; les autres gardent le thème global (`parametre_style_user`). Voir
`vendor/function.php::style()` : override résolu via `namespace_resolve($GLOBALS['paths'][1])`
et mis en cache session dans `$_SESSION['style_module'][$module]` (jamais dans
`$_SESSION['style_mode']`/`style_nom`, qui restent le cache du thème global — piège à éviter si
on retouche cette fonction : ne jamais faire fuiter la surcharge d'un module dans le cache global).
**Piège évité d'entrée** : `menu_client.php` est inclus aussi bien en navigation normale qu'en
navigation AJAX inter-pages (`X-Ssm-Nav`, qui ne passe PAS par `Layout::donnees()` donc pas de
variable `$layout` disponible à cet endroit) — `ssm_module_theme_menu_html()` s'appuie uniquement
sur `design_directions()` (fonction globale) et `$GLOBALS['style']` (toujours peuplé, `style()` est
appelé sans condition dans `public/index.php` avant le routage), jamais sur `$layout`.
**Sous-module Client (Vente) entièrement équipé** (21/07/2026) : `client_data`/`groupe_data`
(Clients.php), `matricules` (Cartes.php), `encaissement_data` (Encaissements.php), `livre_data`
(Livre.php) ont tous le bouton réglage (`vente_clients`/`vente_groupes`/`vente_cartes`/
`vente_encaissements`/`vente_livre` comme `cle_table`). Prochain sous-module à équiper : **Gestion
des bons** (menu séparé, voir `namespace_resolve()` → `bons`) — même recette, 2 lignes HTML +
1 ligne JS par panel (§9 ci-dessus) + un `ssm_module_theme_menu_html('bons')` dans son propre menu.
## 10. Notification + fermeture automatique après ajout/modification en modale (21/07/2026)
Retour utilisateur sur le flux "Ajouter/Modifier un client" (`vente/modal/Nouveau_client.php` via
`ClientsController::modal()`) : après un **ajout**, le contrôleur recharge la modale avec un
formulaire **vierge** (pratique pour enchaîner plusieurs ajouts) ; après une **modification**, ce
même formulaire vierge n'a pas de sens - il faut fermer directement.
- **Notification** : `ssm_notify(message, type, duree)` (ajax.js) remplace `toastr.success(...)`
sur ce flux - carte alignée sur les tokens du thème (pas l'habillage générique de toastr),
empilée en haut à droite. **Ne remplace pas toastr partout** (encore utilisé ailleurs, migration
au fil de l'eau comme le reste de la Phase 4) - juste sur les flux repris avec cette recette.
- **Fermeture automatique (ajout uniquement)** : `ssm_modal_auto_close(modalSelector, duree)`
injecte une barre rouge qui se rétrécit en haut de `.modal-content` (profite du `overflow:hidden`
déjà en place) ; à la fin du délai (5000ms par défaut), ferme la modale (`.modal('hide')`) - SAUF
si l'utilisateur a interagi entretemps (clic/saisie/changement dans `.modal-body`/`.modal-footer`),
auquel cas la fermeture est annulée silencieusement.
- **Piège vécu et corrigé** : le formulaire rechargé repeuple son select2 des groupes via
`.trigger('change')` **programmatique** (`remplir_groupe()`, script de `Nouveau_client.php`) -
ce `change` synthétique remontait dans le délégué d'écoute et annulait la fermeture automatique
à peine démarrée, avant même que l'utilisateur touche à quoi que ce soit. Fix : ignorer tout
événement sans `e.originalEvent` (un événement réellement émis par le navigateur en a toujours
un ; un `.trigger()` JS n'en a jamais) - ne réagir qu'aux vraies interactions utilisateur.
- **Usage dans le handler de succès** (voir `Clients.php`, `#ajouter_client`) :
```js
var etait_ajout = (param['id'] == 0); // lu AVANT le rechargement (le formulaire revient vierge apres)
load_portion('/Clients/modal', 'modal_div', param, function() {
ssm_notify(msg, 'success');
if (etait_ajout) ssm_modal_auto_close('#afficher_div', 5000);
else $('#afficher_div').modal('hide');
Clients.draw();
});
```
- **Reste à faire** : seul `Clients.php` (`#ajouter_client`) a été repris ; répliquer sur les
autres modales ajout/modification du même module (Groupes, Cartes...) puis des autres modules,
au fur et à mesure - même recette, quelques lignes par handler de succès.
- **Détail de ce qui a été ajouté/modifié** (retour utilisateur du 21/07/2026) : `ssm_notify()`
accepte un 4e paramètre `details` (`[{label, valeur}]`) affiché sous le message principal - les
entrées vides sont ignorées automatiquement. Construit côté appelant à partir des **champs
pertinents** du formulaire (pas les id techniques ni les options booléennes) juste avant l'appel
à `load_portion` (les valeurs du formulaire sont encore là, avant qu'il ne revienne vierge) :
```js
var details = [
{ label: 'Nom', valeur: param['nom'] },
{ label: 'Groupe', valeur: $('#id_groupe option:selected').text().trim() },
{ label: 'Plafond', valeur: param['plafond'] ? Nombre(parseFloat(param['plafond'])) + ' MAD' : '' },
];
```
**Piège vécu et corrigé** : `Nombre()` (ajax.js) appelle `number.toFixed(...)` directement sans
convertir son argument - lui passer `param['plafond']` (une **chaîne**, issue de `.val()`) fait
planter `Number.prototype.toFixed` (indisponible sur `String`) **avant même l'appel à
`load_portion`**, empêchant silencieusement tout l'ajout (formulaire jamais envoyé, bouton
simplement resté caché). Toujours passer un vrai nombre à `Nombre()` : `Nombre(parseFloat(valeur))`.
Trouvé uniquement grâce au test navigateur (Playwright) - rien dans la réponse serveur ou la
console ne l'aurait signalé sans capturer les `pageerror`.
**Méthode de test utilisée** : Chromium headless piloté par Playwright (voir §9 pour l'installation
à la volée) - a permis de vérifier en conditions réelles les 3 scénarios (ajout puis silence →
fermeture automatique après 5s ; ajout puis interaction → fermeture annulée ; modification →
fermeture directe) avant de livrer, y compris le piège du `change` synthétique qu'une simple
relecture de code n'aurait pas révélé.
## 11. Dispositions de navigation alternatives : palette / rail / dock (21/07/2026)
Retour utilisateur : implémenter les 3 propositions de `left et top .md` (racine du projet, prompts
4a/4b/4c) comme de vraies dispositions **choisies par l'utilisateur** (pas des maquettes), chacune
**adaptée à nos 4 directions visuelles** (jamais les couleurs en dur des prompts), en réutilisant
les vraies données de l'appli plutôt que les arbres de menu/notifications fictifs des prompts.
**Architecture** :
- `parametre_layout_user` (migration 012) : préférence par utilisateur parmi
`classique` (défaut, comportement historique inchangé) / `palette` / `rail` / `dock`. Cache
session `$_SESSION['layout_mode']`, résolu dans `Layout::donnees()` — même schéma que
`parametre_style_module` (§9).
- `Layout::menu_arbre()` : regroupe le menu **déjà filtré par droits** (`Layout::menu_config()`,
la vraie source) en arbre section→pages, injecté une fois en JSON (`window.SSM_MENU_ARBRE`,
`top_bar.php`) — jamais de section/page inventée, contrairement aux prompts qui décrivaient un
menu fictif. Les entrées sans sous-menu (Accueil, Compte Journalier, Stock...) sont regroupées
sous deux sections synthétiques "Général"/"Exploitation" (présentation uniquement).
- `/Home/activite_json` : réutilise `JournalActivite::derniers()` (déjà construit pour le bandeau
classique, §9/§10) en JSON brut, pour les timelines de rail/dock.
- `/Home/notifications_groupees` : réutilise `Statistiques::notification_{vente,achat,coffre,banque}()`
(déjà utilisées par les dropdowns de la disposition classique) regroupées par domaine **réel**
de l'appli — pas les catégories fictives "Messages/Système" des prompts (aucun système de
messagerie n'existe dans SSTM).
- `public/css/design/layouts.css` + `public/js/ssm_layouts.js` : chargés **uniquement** si
`layout_mode != 'classique'` (voir `header.php`/`top_bar.php`) — zéro impact sur les comptes
restés en disposition classique (le défaut, pour tous les comptes existants).
- `app/views/layout/nav/_{palette,rail,dock}.php` : partials inclus depuis `top_bar.php`
(`include('nav/_' . $mode . '.php')`), markup minimal, toute la logique dans `ssm_layouts.js`.
- `left_bar.php` : le menu classique (`