Ajout des commentaires dans le code

assets/js/page-bootstrap.js

@@ -1,7 +1,24 @@
+/**
+ * Amorçage de page — À CHARGER EN DERNIER, après core.js et tous les modules.
+ *
+ * Deux responsabilités :
+ *  1. appeler `init()` sur chaque module déclaré par le PageController ;
+ *  2. appliquer les filtres venus de l'URL (structure_id, agent_id, week, month,
+ *     focus…), que PHP a assainis et republiés dans `window.PTA_PAGE_CONFIG`.
+ *
+ * Ce second point est ce qui rend les LIENS PROFONDS opérants : le tableau de
+ * bord, la file de validation et la vue annuelle renvoient tous vers un écran
+ * pré-positionné sur le bon lieu, le bon agent et la bonne semaine.
+ *
+ * Les initialisations sont `async` mais lancées SANS `await` en fin de fichier :
+ * elles concernent des écrans différents et jamais plus d'une n'agit sur une
+ * page donnée.
+ */
 (() => {
     'use strict';
 
     const PTA = window.PTA;
+    // core.js absent ou en erreur : rien à amorcer.
     if (!PTA) return;
 
     const page = window.PTA_PAGE_CONFIG || {};
@@ -10,6 +27,13 @@
 
     modules.forEach((name) => PTA.modules[name]?.init?.());
 
+    /**
+     * Écran de saisie : positionne lieu, agent et semaine depuis l'URL.
+     *
+     * L'ordre des étapes est CONTRAINT : la liste des agents dépend du lieu, et
+     * la semaine ne peut être chargée qu'une fois l'agent connu — d'où les
+     * `await` successifs.
+     */
     async function initialisePlanning() {
         const planning = PTA.modules.planning;
         if (!planning) return;
@@ -46,6 +70,7 @@
         }
     }
 
+    /** Planning par lieu : pré-sélectionne le lieu et charge la semaine. */
     async function initialiseStructureOverview() {
         if (!params.structureId) return;
         const select = document.querySelector('#overview-structure');
@@ -56,6 +81,11 @@
         await PTA.modules.structureOverview?.load?.();
     }
 
+    /**
+     * Planning par agent : pré-sélectionne l'agent et le mois.
+     * Le chargement n'est déclenché que si un agent est désigné ; sans agent, il
+     * n'y a rien à afficher.
+     */
     async function initialiseAgentOverview() {
         if (params.agentId) {
             const select = document.querySelector('#overview-agent');
@@ -71,6 +101,7 @@
         if (params.agentId) await PTA.modules.agentOverview?.load?.();
     }
 
+    /** Contrôle de couverture : pré-sélectionne le lieu et rafraîchit. */
     function initialiseCoverage() {
         if (!params.structureId) return;
         const select = document.querySelector('#coverage-structure-filter');