Ajout des commentaires dans le code

app/Controllers/AnnualOverviewController.php

@@ -14,12 +14,28 @@ use App\Models\QuotaModel;
 use PDO;
 use Throwable;
 
+/**
+ * Vue annuelle d'un agent et validation de l'année en une opération.
+ *
+ * L'année de référence est l'année CIVILE (01/01 → 31/12), jamais l'année
+ * scolaire ni la date d'anniversaire du contrat : c'est la période sur laquelle
+ * s'apprécie le quota annualisé (voir QuotaModel).
+ *
+ * Réservé au Service Enfance : valider une année couvre par nature tous les
+ * lieux où l'agent est intervenu.
+ */
 final class AnnualOverviewController
 {
     public function __construct(private PDO $pdo)
     {
     }
 
+    /**
+     * GET api/annual_overview.php — répartition de l'année d'un agent.
+     *
+     * L'année est facultative et retombe sur l'année en cours.
+     * Paramètres GET : agent_id, year (facultatif, borné à [2000, 2100]).
+     */
     public function overview(): void
     {
         (new Access($this->pdo))->requireService();
@@ -42,12 +58,27 @@ final class AnnualOverviewController
     }
 
     /**
+     * POST api/annual_validate.php — contrôle puis validation de toute l'année.
+     *
      * Contrôle puis validation en une seule opération de tous les plannings
      * en brouillon de l'agent pour l'année civile affichée.
      *
      * Aucune validation partielle : si une erreur est trouvée, aucun planning
      * n'est validé. Les semaines concernées sont retournées au front afin de
-     * pouvoir les ouvrir dans un nouvel onglet et les corriger.
+     * pouvoir les ouvrir dans un nouvel onglet et les corriger. Un succès
+     * partiel laisserait l'utilisateur devant une année à moitié validée, sans
+     * moyen simple de savoir ce qui reste.
+     *
+     * Trois issues, alignées sur PlanningController::validate() :
+     *  - 422 + status « errors »  : au moins une ERREUR, rien n'est validé ;
+     *  - 409 + status « warning » : quota annuel dépassé, confirmation attendue
+     *    par un rappel avec force_quota: true ;
+     *  - 200 + status « validated » ou « nothing_to_validate ».
+     *
+     * Contrairement à validate() unitaire, le quota est ici évalué à l'échelle
+     * de l'ANNÉE (annualForApi) et non de la semaine.
+     *
+     * Charge utile : agent_id, year, force_quota (bool), csrf_token.
      */
     public function validateYear(): void
     {
@@ -153,6 +184,24 @@ final class AnnualOverviewController
         }
     }
 
+    /**
+     * Contrôles bloquants d'un planning, dans la variante « année ».
+     *
+     * DIFFÉRENCE VOULUE avec PlanningController::validate() : les chevauchements
+     * inter-lieux sont recherchés via externalOverlaps() (tous statuts) et non
+     * validatedExternalOverlaps() (validés seulement). Une validation annuelle
+     * traite en un bloc l'ensemble des brouillons de l'agent : ils vont tous
+     * devenir opposables, deux brouillons qui se recouvrent doivent donc être
+     * signalés dès maintenant.
+     *
+     * Un contrôle INFO est ajouté quand rien n'a été trouvé, pour que
+     * l'interface affiche « aucune anomalie » plutôt qu'une liste vide
+     * indistincte d'une absence de contrôle.
+     *
+     * @param array<string, mixed> $planning
+     *
+     * @return array<int, array{niveau: string, code: string, message: string}>
+     */
     private function controlsForPlanning(PlanningModel $model, array $planning): array
     {
         $planningId = (int) $planning['id_planning'];
@@ -203,6 +252,13 @@ final class AnnualOverviewController
         return $controls;
     }
 
+    /**
+     * Empile un contrôle au format commun {niveau, code, message}.
+     * Copie de PlanningController::addControl(), les deux contrôleurs n'ayant
+     * pas de base commune.
+     *
+     * @param array<int, array{niveau: string, code: string, message: string}> $controls
+     */
     private function addControl(array &$controls, string $level, string $code, string $message): void
     {
         $controls[] = ['niveau' => $level, 'code' => $code, 'message' => $message];