Ajout des commentaires dans le code

assets/js/coverage.js

@@ -1,3 +1,21 @@
+/**
+ * Contrôle de couverture (`PTA.modules.coverage`).
+ *
+ * Chargé par DEUX écrans, avec des rôles différents :
+ *  - coverage.php    : consultation des alertes de la semaine ;
+ *  - administration.php : édition des règles de couverture des lieux.
+ * Les sélecteurs des deux moitiés sont donc absents l'un chez l'autre, d'où les
+ * `if (!element) return;` systématiques.
+ *
+ * Une « alerte » est une plage où le nombre d'agents planifiés passe sous le
+ * minimum attendu du lieu. Le serveur découpe au quart d'heure puis refusionne
+ * les créneaux consécutifs identiques ; ce module se contente d'afficher les
+ * intervalles reçus.
+ *
+ * L'ÉDITEUR DE RÈGLES fonctionne en REMPLACEMENT INTÉGRAL : `collectRules()` lit
+ * la totalité de l'écran et l'envoie d'un bloc. Un jour vidé de ses plages
+ * supprime les règles correspondantes — c'est le comportement voulu.
+ */
 (() => {
     'use strict';
 
@@ -34,6 +52,7 @@
     let alerts = [];
     let loading = false;
 
+    /** Pastille d'onglet « Couverture », masquée quand il n'y a rien à signaler. */
     function setBadge(count) {
         if (!badge) return;
         badge.textContent = String(count);
@@ -47,6 +66,11 @@
         messageElement.textContent = text;
     }
 
+    /**
+     * Rend le tableau des alertes.
+     * Les lieux NON CONFIGURÉS sont affichés séparément : sans règle, ils ne
+     * peuvent produire aucune alerte et passeraient à tort pour conformes.
+     */
     function renderAlerts(data) {
         alerts = Array.isArray(data.alerts) ? data.alerts : [];
         const summary = data.summary || {};
@@ -93,6 +117,13 @@
         }
     }
 
+    /**
+     * Recharge les alertes de la semaine et du lieu sélectionnés.
+     * Appelée aussi par l'éditeur de planning après un enregistrement, en mode
+     * silencieux : la couverture dépend de ce qui vient d'être saisi.
+     *
+     * @param {{silent?: boolean}} options
+     */
     async function refresh(options = {}) {
         if (loading) return;
         const week = weekInput?.value;
@@ -119,6 +150,11 @@
         }
     }
 
+    /**
+     * Ouvre l'écran de saisie sur le lieu et la semaine du manque, avec un
+     * `notice` qui rappelle la plage à couvrir : sans lui, l'utilisateur
+     * arriverait sur une semaine complète sans savoir où agir.
+     */
     function openGap(alert) {
         if (!alert) return;
         const params = new URLSearchParams({
@@ -129,6 +165,10 @@
         window.location.href = `planning.php?${params.toString()}`;
     }
 
+    /**
+     * Balisage d'une plage de couverture : début, fin, effectif minimal.
+     * `step="900"` contraint la saisie au quart d'heure, comme partout ailleurs.
+     */
     function coverageRuleRow(rule = {}) {
         return `
             <div class="coverage-rule-row">
@@ -148,6 +188,10 @@
             </div>`;
     }
 
+    /**
+     * Rend l'éditeur : une section par jour ouvré, TOUJOURS les cinq, même sans
+     * règle. C'est ce qui permet d'ajouter une plage sur un jour vide.
+     */
     function renderRuleEditor(rules = []) {
         if (!ruleEditor) return;
         const grouped = new Map();
@@ -168,6 +212,7 @@
         if (saveRulesButton) saveRulesButton.disabled = false;
     }
 
+    /** Charge les règles du lieu sélectionné dans l'éditeur. */
     async function loadRules() {
         const structureId = ruleStructureSelect?.value;
         if (!structureId || !ruleEditor) {
@@ -195,6 +240,11 @@
         }
     }
 
+    /**
+     * Lit la totalité de l'éditeur et produit la liste à envoyer.
+     * Une ligne entièrement vide est ignorée sans erreur : c'est une plage
+     * ajoutée puis abandonnée, pas une saisie incomplète.
+     */
     function collectRules() {
         const rules = [];
         ruleEditor?.querySelectorAll('.coverage-rule-day').forEach((daySection) => {
@@ -210,6 +260,11 @@
         return rules;
     }
 
+    /**
+     * Enregistre les règles du lieu — REMPLACEMENT INTÉGRAL.
+     * Chevauchements et horaires incohérents sont refusés côté serveur, dont le
+     * message est affiché tel quel.
+     */
     async function saveRules() {
         const structureId = ruleStructureSelect?.value;
         if (!structureId || !saveRulesButton || !ruleMessage) return;