Ajout des commentaires dans le code

assets/js/teams.js

@@ -1,10 +1,26 @@
+/**
+ * Équipes des mercredis et des vacances (`PTA.modules.teams`), écran teams.php.
+ *
+ * Une équipe rassemble des agents sur un lieu et une période, avec des règles
+ * d'encadrement propres à l'accueil collectif de mineurs (effectifs par tranche
+ * d'âge, taux d'encadrement, proportion d'agents diplômés). Le serveur calcule
+ * l'effectif requis et les contrôles ; ce module se contente de les afficher.
+ *
+ * Les contrôles suivent la forme commune {niveau, code, message}. AUCUN n'est
+ * bloquant : ils signalent, l'arbitrage reste humain.
+ *
+ * La page se recharge intégralement (`load()`) après chaque modification :
+ * ajouter ou retirer un membre change les contrôles de toute l'équipe.
+ */
 (() => {
     'use strict';
     const PTA = window.PTA;
+    // core.js absent : la page reste lisible, simplement non interactive.
     if (!PTA) return;
     const { readJsonResponse, apiErrorMessage, escapeHtml, formatDate } = PTA.utils;
     const el = (id) => document.getElementById(id);
 
+    /** Message dans le bandeau de la page. */
     function message(text, type = 'info') {
         const box = el('team-list-message');
         if (!box) return;
@@ -12,6 +28,10 @@
         box.textContent = text;
     }
 
+    /**
+     * Appel d'API mutualisé : lit le JSON et transforme toute réponse non-OK en
+     * exception. Toutes les actions de la page passent par ici.
+     */
     async function api(url, options = {}) {
         const response = await fetch(url, options);
         const data = await readJsonResponse(response);
@@ -19,11 +39,13 @@
         return data;
     }
 
+    /** Rend un contrôle, sa classe CSS dérivant de son niveau. */
     function controlHtml(control) {
         const level = String(control.niveau || 'INFO').toLowerCase();
         return `<div class="control-item control-${escapeHtml(level)}"><strong>${escapeHtml(control.niveau)}</strong><span>${escapeHtml(control.message)}</span></div>`;
     }
 
+    /** Carte complète d'une équipe : paramètres, membres, contrôles, actions. */
     function teamHtml(team) {
         const options = el('team-agent-options')?.innerHTML || '';
         const members = (team.members || []).map((member) => `
@@ -58,6 +80,7 @@
             </article>`;
     }
 
+    /** Recharge toutes les équipes de la période filtrée. */
     async function load() {
         const start = el('team-filter-start')?.value || '';
         const end = el('team-filter-end')?.value || '';
@@ -72,6 +95,7 @@
         } catch (error) { message(error.message, 'error'); }
     }
 
+    /** Crée une équipe (toujours en BROUILLON), puis recharge la liste. */
     async function create(event) {
         event.preventDefault();
         const box = el('team-create-message');
@@ -101,6 +125,10 @@
         } catch (error) { box.className = 'message message-error'; box.textContent = error.message; }
     }
 
+    /**
+     * Ajout et retrait de membres, par délégation sur la liste des équipes —
+     * elle est reconstruite à chaque chargement.
+     */
     async function handle(event) {
         const card = event.target.closest('.team-card');
         if (!card) return;
@@ -130,6 +158,11 @@
         }
     }
 
+    /**
+     * Fait avancer une équipe dans son cycle de vie
+     * (BROUILLON → A_CONTROLER → VALIDEE). Aucune transition n'est imposée : le
+     * suivi est indicatif, pas un verrou.
+     */
     async function status(event) {
         const select = event.target.closest('.team-status');
         if (!select) return;