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 */

app/Views/pages/administration.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/administration.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/agents.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/agent_overview.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/annual.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/annual_overview.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/coverage.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/coverage_alerts.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/dashboard.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/dashboard.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/faq.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/faq.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/pending.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/pending_validation.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/planning.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/planning_editor.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/pta.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/pta.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/role.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ * Sélecteur de rôle — SEULE vue à ne pas passer par layouts/header.php.
+ *
+ * Elle s'affiche avant qu'un rôle soit choisi, donc avant tout contrôle
+ * d'accès, et ne peut pas afficher la barre de navigation qui en dépend. Elle
+ * porte donc son propre <head> : c'est le TROISIÈME endroit où incrémenter le
+ * `?v=` des assets, avec layouts/header.php et layouts/footer.php.
+ *
+ * Rappel : sélection n'est pas authentification. L'utilisateur choisit
+ * librement son identité (voir App\Core\Access::select()).
+ */
 /** @var string $csrfToken */
 /** @var array $agents */
 /** @var array $structures */

app/Views/pages/structures.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/structure_overview.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/teams.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/teams.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/pages/vacations.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Vue de page : assemble l'en-tête commun, le partiel de contenu et le pied.
+ * Toutes les variables utilisées viennent de PageController::renderPage(), qui
+ * les a extraites dans la portée de ce fichier.
+ */
 require dirname(__DIR__) . '/layouts/header.php';
 require dirname(__DIR__) . '/partials/vacation_calendar.php';
 require dirname(__DIR__) . '/layouts/footer.php';

app/Views/partials/administration.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Référentiels : agents, lieux d'affectation, postes, horaires de couverture.
+ * Modules JS : `administration` et `coverage`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
     <section id="assignment-view" class="app-view page-content">
         <div class="admin-grid">
             <section class="card admin-card">

app/Views/partials/agent_overview.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Planning mensuel d'un agent, tous lieux confondus.
+ * Module JS : `agentOverview`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
     <section id="agent-view" class="app-view page-content">
         <section class="card">
             <div class="section-heading">

app/Views/partials/annual_overview.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * Calendrier annuel d'un agent et validation de l'année entière.
+ * Le calendrier est intégralement construit côté serveur (AnnualOverviewModel) ;
+ * ce partiel ne fournit que les conteneurs vides.
+ * Module JS : `annualOverview`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
 $currentYear = (int) date('Y');
 ?>
 <section class="page-content annual-overview-page">

app/Views/partials/coverage_alerts.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Alertes de couverture d'une semaine.
+ * Module JS : `coverage`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
 <section id="coverage-view" class="app-view page-content">
     <section class="card coverage-header-card">
         <div class="section-heading">

app/Views/partials/dashboard.php

@@ -1,4 +1,13 @@
 <?php
+/**
+ * Tableau de bord du Service Enfance : quatre blocs alimentés par un unique
+ * appel à api/dashboard_summary.php.
+ * Module JS : `dashboard`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
 /** @var string $currentWeek */
 ?>
 <section id="dashboard-view" class="app-view page-content dashboard-page">

app/Views/partials/faq.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Guide d'utilisation. Page entièrement STATIQUE : aucun script, aucun appel
+ * API, aucune donnée métier. Elle reste néanmoins soumise à acces_role_page.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
 /** @var array $accessProfile */
 /** @var array $allowedPages */
 

app/Views/partials/pending_validation.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * File des plannings en attente de validation.
+ * Module JS : `pendingValidation`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
 <section id="pending-validation-view" class="app-view page-content">
     <section class="card pending-validation-header-card">
         <div class="section-heading">

app/Views/partials/planning_editor.php

@@ -1,4 +1,17 @@
 <?php
+/**
+ * Écran de saisie du planning — le plus dense de l'application.
+ * Contient les deux modes exclusifs (éditeur de semaine type et saisie semaine
+ * par semaine), le formulaire jour par jour, le tableau de visualisation, le
+ * panneau de quota et les modales de semaine type.
+ * La numérotation des étapes se resserre quand le rôle n'a pas droit aux
+ * semaines types (voir $usesTemplates ci-dessous).
+ * Modules JS : `planning`, `weekTemplates`, `weekTemplateEditor`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
 // Les rôles sans droit aux semaines types n'ont qu'un seul mode de saisie :
 // le sélecteur de méthode disparaît et la numérotation des étapes se resserre.
 $usesTemplates = !empty($permissions['can_use_templates']);

app/Views/partials/pta.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * PTA détaillé d'un agent : contraintes, souhaits de lieux, répartition.
+ * Module JS : `pta`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
 <section class="page-content pta-page">
     <section class="card">
         <div class="section-heading">

app/Views/partials/structure_overview.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Planning d'un lieu sur une semaine, en lecture seule.
+ * Module JS : `structureOverview`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
     <section id="structure-view" class="app-view page-content">
         <section class="card">
             <div class="section-heading">

app/Views/partials/teams.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Équipes des mercredis et des vacances.
+ * Module JS : `teams`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
+?>
 <section class="page-content team-page">
     <section class="card">
         <div class="section-heading">

app/Views/partials/vacation_calendar.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * Périodes de vacances scolaires : aperçu depuis l'API officielle, validation
+ * manuelle, puis enregistrement. Aucune donnée externe n'entre en base sans
+ * relecture humaine.
+ * Module JS : `vacationCalendar`.
+ *
+ * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
+ * posés ici sont les points d'ancrage du module JS : les renommer casse le
+ * module sans aucune erreur visible.
+ */
 $currentYear = (int) date('Y');
 $currentMonth = (int) date('n');
 $schoolYearStart = $currentMonth >= 8 ? $currentYear : $currentYear - 1;