Ajout des commentaires dans le code

app/Controllers/StructureController.php

@@ -17,6 +17,15 @@ use DateTimeImmutable;
 use PDO;
 use Throwable;
 
+/**
+ * Lieux d'affectation : planning hebdomadaire par lieu et référentiel.
+ *
+ * Vue complémentaire de celle par agent : ici on regarde QUI est présent sur un
+ * lieu, là on regarde OÙ va un agent. Les deux lisent les mêmes créneaux.
+ *
+ * Consultation ouverte aux trois rôles dans leur périmètre ; création et
+ * modification réservées au Service Enfance.
+ */
 final class StructureController
 {
     private StructureModel $structureModel;
@@ -32,6 +41,19 @@ final class StructureController
         $this->access = new Access($pdo);
     }
 
+    /**
+     * GET api/structure_overview.php — semaine d'un lieu, agent par agent.
+     *
+     * La liste d'agents ne se limite PAS aux agents rattachés au lieu : elle
+     * inclut ceux qui y sont ponctuellement planifiés, distingués par le drapeau
+     * `lieu_principal`. Un agent peut travailler sur plusieurs lieux la même
+     * semaine, et l'omettre donnerait une vue fausse de l'effectif présent.
+     *
+     * Les créneaux sont indexés par agent en PHP plutôt que par une requête par
+     * agent : une seule lecture, puis regroupement en mémoire.
+     *
+     * Paramètres GET : structure_id, week.
+     */
     public function overview(): void
     {
         $structureId = filter_input(INPUT_GET, 'structure_id', FILTER_VALIDATE_INT);
@@ -79,6 +101,16 @@ final class StructureController
         ]);
     }
 
+    /**
+     * GET api/structure_planning_pdf.php — même vue, au format PDF.
+     *
+     * Reprend volontairement le calcul de overview() plutôt que de le
+     * factoriser : les deux méthodes doivent rester alignées, toute évolution
+     * de l'une appelle la même dans l'autre.
+     *
+     * Endpoint PDF : les erreurs sortent en texte brut avec un code HTTP, jamais
+     * en JSON (voir AgentController).
+     */
     public function pdf(): void
     {
         $structureId = filter_input(INPUT_GET, 'structure_id', FILTER_VALIDATE_INT);
@@ -131,6 +163,20 @@ final class StructureController
         );
     }
 
+    /**
+     * POST api/create_structure.php — création d'un lieu d'affectation.
+     *
+     * Le code est normalisé avant contrôle : espaces remplacés par des
+     * underscores, puis passage en majuscules. Il sert d'identifiant lisible
+     * (nom de fichier PDF, exports), d'où le format restreint à
+     * [A-Z0-9_-]{2,50}. Un doublon ressort en 409, pas en 422 : c'est un conflit
+     * avec l'existant.
+     *
+     * `type_affectation` (PERISCOLAIRE | EXTRASCOLAIRE) détermine le contexte
+     * par défaut du lieu ; il reste croisé avec le calendrier des vacances.
+     *
+     * Charge utile : code, nom, adresse, type_affectation, csrf_token.
+     */
     public function create(): void
     {
         $this->access->requireService();
@@ -175,6 +221,14 @@ final class StructureController
         ]);
     }
 
+    /**
+     * POST api/update_structure.php — change le type d'un lieu.
+     *
+     * Seul le type est modifiable : le code sert de référence stable, et le nom
+     * n'est pas exposé à l'édition dans cette version.
+     *
+     * Charge utile : structure_id, type_affectation, csrf_token.
+     */
     public function updateType(): void
     {
         $this->access->requireService();
@@ -214,6 +268,11 @@ final class StructureController
         ]);
     }
 
+    /**
+     * Décode « AAAA-Www ». Copie locale, comme dans les autres contrôleurs.
+     *
+     * @return array{0: int, 1: int}|null [année ISO, semaine], ou null.
+     */
     private function parseWeek(string $value): ?array
     {
         if (!preg_match('/^(\d{4})-W(\d{2})$/', $value, $matches)) {