Ajout des commentaires dans le code

app/Controllers/PtaController.php

@@ -15,6 +15,21 @@ use DateTimeImmutable;
 use PDO;
 use Throwable;
 
+/**
+ * PTA détaillé d'un agent : contraintes prioritaires et souhaits de lieux.
+ *
+ * Ces deux référentiels décrivent ce qui DOIT ou NE DOIT PAS être planifié pour
+ * un agent. Ils sont consultatifs : rien ici n'empêche techniquement une saisie
+ * contraire, l'arbitrage reste à l'agent de planification.
+ *
+ * Les deux endpoints d'écriture sont à double action, pilotée par le champ
+ * `action` de la charge utile (« SAVE » par défaut, ou « DELETE ») : c'est un
+ * écart au reste de l'API, où un endpoint = une opération. La branche DELETE
+ * sort par JsonResponse::send(), qui termine le script — le code de SAVE qui
+ * suit n'est donc jamais atteint dans ce cas.
+ *
+ * Réservé au Service Enfance.
+ */
 final class PtaController
 {
     private PtaModel $ptaModel;
@@ -30,6 +45,15 @@ final class PtaController
         $this->access = new Access($pdo);
     }
 
+    /**
+     * GET api/pta_summary.php — synthèse du PTA d'un agent à une date donnée.
+     *
+     * La date sert de point d'observation : elle détermine la période de quota
+     * retenue et les contraintes en vigueur ce jour-là. Elle retombe sur
+     * aujourd'hui si elle n'est pas fournie.
+     *
+     * Paramètres GET : agent_id, date (facultative, « AAAA-MM-JJ »).
+     */
     public function summary(): void
     {
         $this->access->requireService();
@@ -50,6 +74,24 @@ final class PtaController
         }
     }
 
+    /**
+     * POST api/pta_constraint.php — enregistre ou supprime une contrainte.
+     *
+     * Deux types seulement, volontairement fermés : MEDICALE et
+     * TEMPS_PARTIEL_THERAPEUTIQUE. Une date de fin vide signifie « sans terme
+     * connu », cas courant d'un aménagement médical en cours.
+     *
+     * Le commentaire est OBLIGATOIRE : une contrainte restreint la planification
+     * d'un agent, elle doit rester justifiable a posteriori.
+     *
+     * Les maximums arrivent en HEURES depuis le formulaire et sont convertis en
+     * MINUTES pour la base, unité de tous les cumuls de l'application.
+     *
+     * Charge utile : action (SAVE|DELETE), agent_id, csrf_token, puis selon
+     * l'action constraint_id, ou type_contrainte / date_debut / date_fin /
+     * commentaire / quotite_temporaire / maximum_heures_jour /
+     * maximum_heures_semaine / interdit_matin|midi|soir.
+     */
     public function constraint(): void
     {
         $this->access->requireService();
@@ -115,10 +157,26 @@ final class PtaController
             ]);
             JsonResponse::send(201, ['message' => 'La contrainte prioritaire a été enregistrée.', 'id_contrainte' => $id]);
         } catch (Throwable $e) {
+            // INCOHÉRENCE CONNUE : le détail de l'exception est renvoyé au
+            // navigateur SANS AUCUNE condition de debug, contrairement au reste
+            // du projet. Idem dans wish(). À aligner sur
+            // Security::debugEnabled() — voir la note de PlanningController::save().
             JsonResponse::send(500, ['error' => 'Impossible d’enregistrer la contrainte.', 'details' => $e->getMessage()]);
         }
     }
 
+    /**
+     * POST api/pta_wish.php — enregistre ou supprime un souhait de lieu.
+     *
+     * Deux types : PREFERENCE (l'agent souhaite y être affecté) et INTERDICTION
+     * (il ne doit pas l'être). La priorité, de 1 à 5, permet d'ordonner
+     * plusieurs préférences entre elles ; la distance en kilomètres sert à
+     * arbitrer les affectations éloignées.
+     *
+     * Charge utile : action (SAVE|DELETE), agent_id, csrf_token, puis selon
+     * l'action wish_id, ou structure_id / type_souhait / priorite /
+     * distance_km / commentaire.
+     */
     public function wish(): void
     {
         $this->access->requireService();