Ajout des commentaires dans le code

app/Models/StructureModel.php

@@ -4,8 +4,24 @@ declare(strict_types=1);
 
 namespace App\Models;
 
+/**
+ * Référentiel des lieux d'affectation (`structure`).
+ *
+ * Toutes les lectures filtrent sur `actif = TRUE` : un lieu désactivé disparaît
+ * des listes et ne peut plus être choisi, mais ses plannings passés restent
+ * intacts. Aucune méthode de désactivation n'est exposée dans cette version, la
+ * bascule se fait en SQL.
+ *
+ * `type_affectation` (PERISCOLAIRE | EXTRASCOLAIRE) donne le contexte par défaut
+ * du lieu ; il reste croisé avec le calendrier des vacances (VacationModel).
+ */
 final class StructureModel extends BaseModel
 {
+    /**
+     * Tous les lieux actifs, triés par nom.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function allActive(): array
     {
         return $this->pdo->query(
@@ -13,6 +29,12 @@ final class StructureModel extends BaseModel
         )->fetchAll();
     }
 
+    /**
+     * Lieu actif par identifiant.
+     *
+     * @return array<string, mixed>|null null si inexistant OU désactivé — les
+     *         appelants traitent les deux cas de la même façon.
+     */
     public function findActive(int $id): ?array
     {
         $stmt = $this->pdo->prepare(
@@ -22,6 +44,10 @@ final class StructureModel extends BaseModel
         return $stmt->fetch() ?: null;
     }
 
+    /**
+     * Vrai si le code est déjà pris, DÉSACTIVÉS COMPRIS : le code reste unique
+     * en base, réutiliser celui d'un lieu fermé violerait la contrainte.
+     */
     public function codeExists(string $code): bool
     {
         $stmt = $this->pdo->prepare('SELECT 1 FROM structure WHERE code = :code LIMIT 1');
@@ -29,6 +55,14 @@ final class StructureModel extends BaseModel
         return $stmt->fetchColumn() !== false;
     }
 
+    /**
+     * Crée un lieu actif et renvoie sa fiche complète.
+     *
+     * La fiche est reconstituée en PHP plutôt que relue en base : l'appelant en
+     * a besoin pour l'insérer dans la liste affichée sans recharger la page.
+     *
+     * @return array<string, mixed>
+     */
     public function create(string $code, string $name, ?string $address, string $typeAffectation): array
     {
         $stmt = $this->pdo->prepare(
@@ -51,6 +85,10 @@ final class StructureModel extends BaseModel
         ];
     }
 
+    /**
+     * Change le type d'un lieu. La valeur est contrôlée par le contrôleur, ce
+     * modèle ne fait qu'écrire.
+     */
     public function updateType(int $structureId, string $typeAffectation): void
     {
         $stmt = $this->pdo->prepare(
@@ -62,6 +100,20 @@ final class StructureModel extends BaseModel
         ]);
     }
 
+    /**
+     * Agents à afficher pour un lieu et une semaine.
+     *
+     * Réunit DEUX populations, d'où les LEFT JOIN et le OR de la clause WHERE :
+     *  - les agents RATTACHÉS au lieu (a.id_structure), même sans planning ;
+     *  - les agents PLANIFIÉS sur le lieu cette semaine, quel que soit leur
+     *    rattachement (sem.id_semaine IS NOT NULL).
+     *
+     * Omettre la seconde donnerait une vue fausse de l'effectif présent, un
+     * agent pouvant travailler sur plusieurs lieux la même semaine.
+     * `id_structure_principale` permet à l'interface de les distinguer.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function agentsForOverview(int $structureId, int $year, int $week): array
     {
         $stmt = $this->pdo->prepare(
@@ -88,6 +140,14 @@ final class StructureModel extends BaseModel
         return $stmt->fetchAll();
     }
 
+    /**
+     * Créneaux d'un lieu sur une semaine, tous agents confondus.
+     *
+     * Une seule lecture, regroupée ensuite par agent en PHP par l'appelant,
+     * plutôt qu'une requête par agent. Heures en HH:MM, format d'affichage.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function entriesForOverview(int $structureId, int $year, int $week): array
     {
         $stmt = $this->pdo->prepare(