Ajout des commentaires dans le code

app/Models/VacationModel.php

@@ -7,8 +7,26 @@ namespace App\Models;
 use DateTimeImmutable;
 use PDO;
 
+/**
+ * Périodes de vacances scolaires (`periode_vacance`).
+ *
+ * Ces périodes déterminent le contexte PÉRISCOLAIRE / EXTRASCOLAIRE de chaque
+ * journée : une date incluse dans une période active est extrascolaire, sinon
+ * elle est périscolaire. C'est cette qualification qui pilote le filtrage des
+ * semaines types (WeekTemplateModel) et le contexte affiché dans l'éditeur.
+ *
+ * Les périodes peuvent être saisies à la main ou importées depuis
+ * data.education.gouv.fr, la colonne `source` conservant l'origine.
+ */
 final class VacationModel extends BaseModel
 {
+    /**
+     * Périodes actives, éventuellement restreintes à une année scolaire.
+     *
+     * @param string|null $schoolYear Ex. « 2026-2027 », ou null pour tout.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function all(?string $schoolYear = null): array
     {
         $sql = "SELECT id_periode, libelle, date_debut, date_fin, annee_scolaire,
@@ -28,6 +46,22 @@ final class VacationModel extends BaseModel
         return $stmt->fetchAll();
     }
 
+    /**
+     * Enregistre un lot de périodes, en INSERT ou mise à jour.
+     *
+     * Le ON DUPLICATE KEY UPDATE s'appuie sur la clé d'unicité du schéma : un
+     * réimport de la même période met à jour son libellé et sa zone au lieu de
+     * la dupliquer, et la RÉACTIVE (`actif = TRUE`) si elle avait été retirée.
+     * Les DATES ne sont volontairement pas mises à jour : ce sont elles qui
+     * identifient la période, les modifier reviendrait à en créer une autre.
+     *
+     * Le lot est transactionnel : soit toutes les périodes sélectionnées entrent,
+     * soit aucune.
+     *
+     * @param array<int, array<string, mixed>> $periods Déjà validées par le contrôleur.
+     *
+     * @return int Nombre de périodes traitées.
+     */
     public function saveMany(array $periods): int
     {
         if ($periods === []) {
@@ -69,6 +103,11 @@ final class VacationModel extends BaseModel
         return count($periods);
     }
 
+    /**
+     * Supprime définitivement une période (et non une désactivation).
+     *
+     * @return bool false si la période n'existait pas.
+     */
     public function delete(int $id): bool
     {
         $stmt = $this->pdo->prepare('DELETE FROM periode_vacance WHERE id_periode = :id');
@@ -76,6 +115,16 @@ final class VacationModel extends BaseModel
         return $stmt->rowCount() > 0;
     }
 
+    /**
+     * Périodes actives qui INTERSECTENT l'intervalle demandé.
+     *
+     * Le test `debut <= fin_demandee AND fin >= debut_demande` est un
+     * recouvrement, pas une inclusion : une période à cheval sur les bornes doit
+     * remonter, sans quoi les jours de vacances en début ou fin d'intervalle
+     * seraient qualifiés à tort de périscolaires.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function periodsBetween(string $startDate, string $endDate): array
     {
         $stmt = $this->pdo->prepare(
@@ -97,6 +146,13 @@ final class VacationModel extends BaseModel
      * Retourne le type de période pour les cinq jours ouvrés d'une semaine ISO.
      * Une date comprise dans une période de vacances confirmée est EXTRASCOLAIRE,
      * sinon elle est PERISCOLAIRE.
+     *
+     * Toujours cinq entrées, lundi à vendredi : le modèle métier s'arrête au
+     * vendredi. Une semaine peut être MIXTE (vacances commençant en cours de
+     * semaine), c'est à l'appelant d'en tirer les conséquences —
+     * DashboardController::weekPayload() par exemple.
+     *
+     * @return array<int, array{date: string, type_affectation: string, vacances: array<string, mixed>|null}>
      */
     public function typesForIsoWeek(int $year, int $week): array
     {