Ajout des commentaires dans le code

app/Controllers/DashboardController.php

@@ -25,6 +25,8 @@ use PDO;
  */
 final class DashboardController
 {
+    /** Nombre d'éléments détaillés par bloc : un aperçu, pas une liste complète.
+     *  Chaque bloc renvoie vers l'écran dédié pour la suite. */
     private const APERCU_MAX = 5;
     private const QUOTA_APERCU_MAX = 8;
 
@@ -45,6 +47,19 @@ final class DashboardController
         $this->vacationModel = new VacationModel($pdo);
     }
 
+    /**
+     * GET api/dashboard_summary.php — données du tableau de bord.
+     *
+     * Deux portées :
+     *  - scope=badges : uniquement le compteur de plannings en attente. Cette
+     *    variante est appelée depuis TOUTES les pages pour alimenter la pastille
+     *    de navigation ; elle doit rester à une seule requête SQL ;
+     *  - portée complète : les quatre blocs de l'écran, ce qui représente
+     *    plusieurs dizaines de requêtes et n'est acceptable que sur le tableau
+     *    de bord lui-même.
+     *
+     * Paramètres GET : scope (badges|absent), week, year (facultatifs).
+     */
     public function summary(): void
     {
         $this->access->requireService();
@@ -264,6 +279,12 @@ final class DashboardController
     }
 
     /**
+     * Décode la semaine demandée, avec repli SILENCIEUX sur la semaine courante.
+     *
+     * Contrairement aux endpoints de saisie, une semaine illisible n'est pas une
+     * erreur ici : le tableau de bord doit toujours s'afficher, quitte à montrer
+     * la semaine en cours. Fuseau explicite, le conteneur PHP tournant en UTC.
+     *
      * @return array{value: string, iso_year: int, iso_week: int, start: DateTimeImmutable}
      */
     private function resolveWeek(mixed $value): array
@@ -294,6 +315,9 @@ final class DashboardController
         ];
     }
 
+    /**
+     * Année du suivi de quota, avec repli sur l'année ISO de la semaine affichée.
+     */
     private function resolveYear(mixed $value, int $fallback): int
     {
         $year = filter_var($value, FILTER_VALIDATE_INT, ['options' => ['min_range' => 2000, 'max_range' => 2100]]);