Ajout des commentaires dans le code

app/Controllers/VacationController.php

@@ -14,6 +14,22 @@ use DateTimeImmutable;
 use PDO;
 use Throwable;
 
+/**
+ * Périodes de vacances scolaires.
+ *
+ * Ces périodes déterminent le contexte PÉRISCOLAIRE ou EXTRASCOLAIRE de chaque
+ * journée, qui conditionne à son tour les motifs pertinents et l'application
+ * filtrée des semaines types. C'est donc un référentiel structurant, pas un
+ * simple calendrier d'affichage.
+ *
+ * L'import depuis l'API publique data.education.gouv.fr se fait en DEUX temps
+ * volontairement séparés : preview() propose sans rien écrire, save() enregistre
+ * après validation manuelle. Aucune donnée externe n'entre en base sans qu'un
+ * humain l'ait relue — les libellés et découpages de l'API varient d'une
+ * académie à l'autre.
+ *
+ * Réservé au Service Enfance.
+ */
 final class VacationController
 {
     private VacationModel $vacationModel;
@@ -25,6 +41,10 @@ final class VacationController
         $this->access = new Access($pdo);
     }
 
+    /**
+     * GET api/vacation_periods.php — périodes enregistrées.
+     * Paramètre GET : school_year (facultatif, « 2026-2027 »).
+     */
     public function index(): void
     {
         $this->access->requireService();
@@ -38,6 +58,19 @@ final class VacationController
         ]);
     }
 
+    /**
+     * GET api/preview_school_holidays.php — propositions de l'API officielle,
+     * SANS aucune écriture en base.
+     *
+     * Le 502 (et non 500) en cas d'échec dit ce qui s'est passé : c'est le
+     * service distant qui n'a pas répondu, pas PTA qui a échoué. Le conteneur
+     * php a besoin d'un accès réseau sortant pour cet appel.
+     *
+     * Les `warnings` signalent les périodes que le service n'a pas su
+     * interpréter ; elles sont montrées à l'utilisateur plutôt que tues.
+     *
+     * Paramètres GET : academy, year (année civile).
+     */
     public function preview(): void
     {
         $this->access->requireService();
@@ -78,6 +111,21 @@ final class VacationController
         ]);
     }
 
+    /**
+     * POST api/save_vacation_periods.php — enregistre les périodes retenues.
+     *
+     * Le plafond de 50 périodes correspond à un large excédent d'une année
+     * scolaire complète ; il borne le coût d'un envoi malformé ou répété.
+     *
+     * Les libellés, académies et zones sont tronqués avec les fonctions mb_* aux
+     * longueurs des colonnes : une troncature en octets couperait un caractère
+     * accentué en deux et produirait de l'UTF-8 invalide en base.
+     *
+     * `source` distingue MANUEL de DATA_GOUV pour tracer l'origine ; une valeur
+     * inconnue retombe sur MANUEL au lieu de faire échouer l'enregistrement.
+     *
+     * Charge utile : periods[], csrf_token.
+     */
     public function save(): void
     {
         $this->access->requireService();
@@ -136,6 +184,15 @@ final class VacationController
         ]);
     }
 
+    /**
+     * POST api/delete_vacation_period.php — supprime une période.
+     *
+     * Aucun contrôle d'usage : supprimer une période change le contexte
+     * scolaire/extrascolaire des journées concernées, mais ne touche aucun
+     * créneau déjà planifié.
+     *
+     * Charge utile : period_id, csrf_token.
+     */
     public function delete(): void
     {
         $this->access->requireService();
@@ -154,12 +211,17 @@ final class VacationController
         JsonResponse::send(200, ['success' => true, 'message' => 'Période supprimée.']);
     }
 
+    /** Date « AAAA-MM-JJ » réellement existante (le 31/02 est rejeté). */
     private function isDate(string $value): bool
     {
         $date = DateTimeImmutable::createFromFormat('!Y-m-d', $value);
         return $date !== false && $date->format('Y-m-d') === $value;
     }
 
+    /**
+     * Année scolaire « AAAA-AAAA », dont la seconde année doit suivre
+     * immédiatement la première : « 2026-2028 » est refusé.
+     */
     private function isSchoolYear(string $value): bool
     {
         if (!preg_match('/^(\d{4})-(\d{4})$/', $value, $matches)) {