Ajout des commentaires dans le code

app/Views/layouts/footer.php

@@ -1,4 +1,27 @@
 <?php
+/**
+ * Pied de page commun : publication de la configuration JavaScript et injection
+ * des scripts.
+ *
+ * C'EST LE SEUL PONT ENTRE PHP ET LE JAVASCRIPT. Deux objets globaux sont
+ * publiés dans un <script> inline :
+ *  - window.PTA_CONFIG      : jeton CSRF, profil d'accès, permissions et
+ *    référentiel des motifs — données valables pour toute l'application ;
+ *  - window.PTA_PAGE_CONFIG : modules à initialiser et paramètres d'URL déjà
+ *    assainis — données propres à la page courante.
+ * core.js recopie le premier dans `PTA.config` ; page-bootstrap.js consomme le
+ * second.
+ *
+ * Ce <script> porte le nonce de la CSP : sans lui, il serait bloqué et TOUTE
+ * l'interface cesserait de fonctionner. Tout script inline ajouté à une vue doit
+ * faire de même (voir App\Core\Security).
+ *
+ * ORDRE DE CHARGEMENT IMPOSÉ : core.js d'abord (il publie window.PTA), puis les
+ * modules de la page, puis page-bootstrap.js en dernier (il appelle leurs init).
+ *
+ * VERSION DES ASSETS : incrémenter le `?v=` ici, dans layouts/header.php ET
+ * dans Views/pages/role.php après toute modification de JS ou de CSS.
+ */
 /** @var string $csrfToken */
 /** @var array $motifs */
 /** @var array $scripts */

app/Views/layouts/header.php

@@ -1,4 +1,21 @@
 <?php
+/**
+ * En-tête HTML commun à toutes les pages : <head>, bandeau et barre de navigation.
+ *
+ * LA NAVIGATION EST DÉFINIE À DEUX ENDROITS, à tenir cohérents :
+ *  - $navigation ci-dessous, qui associe une clé de page à son URL et son libellé ;
+ *  - acces_role_page en base, qui décide des pages RÉELLEMENT autorisées.
+ * Une page absente de $navigation n'apparaîtra jamais, même autorisée en base ;
+ * une page absente de la base n'apparaîtra pas non plus, même déclarée ici.
+ *
+ * $navigationGroups n'est qu'un regroupement d'affichage : une page oubliée
+ * dans les groupes reste atteignable via le groupe « Autres » (voir plus bas).
+ *
+ * VERSION DES ASSETS : le `?v=` de la feuille de style est à incrémenter après
+ * toute modification de CSS ou de JS, ICI, dans layouts/footer.php ET dans
+ * Views/pages/role.php, qui porte son propre <head>. Sans cela, nginx
+ * (expires 7d) et les navigateurs continuent de servir l'ancienne version.
+ */
 /** @var string $pageTitle */
 /** @var string $pageSubtitle */
 /** @var string $activePage */