Ajout des commentaires dans le code

app/Controllers/TeamController.php

@@ -15,6 +15,21 @@ use DateTimeImmutable;
 use PDO;
 use Throwable;
 
+/**
+ * Équipes des mercredis et des vacances.
+ *
+ * Une équipe rassemble des agents sur un lieu et une période, avec des règles
+ * d'encadrement propres à l'accueil collectif de mineurs : effectifs d'enfants
+ * par tranche d'âge, taux d'encadrement (1 agent pour 8 enfants de moins de
+ * 6 ans, 1 pour 12 au-delà, par défaut) et proportion minimale d'agents
+ * diplômés. Ces paramètres sont réglables par équipe, les seuils réglementaires
+ * pouvant évoluer.
+ *
+ * Une équipe suit son propre cycle de vie, distinct de celui des plannings :
+ * BROUILLON → A_CONTROLER → VALIDEE.
+ *
+ * Réservé au Service Enfance.
+ */
 final class TeamController
 {
     private TeamModel $teamModel;
@@ -30,6 +45,21 @@ final class TeamController
         $this->access = new Access($pdo);
     }
 
+    /**
+     * api/teams.php — liste (GET) ou création (POST) d'une équipe.
+     *
+     * Endpoint à double verbe, comme AgentController::assignments(). Le GET
+     * accepte un intervalle de dates facultatif pour ne montrer que les équipes
+     * actives sur une période.
+     *
+     * Les valeurs numériques sont bornées par max() plutôt que rejetées : un
+     * effectif négatif n'a pas de sens mais ne doit pas bloquer la création, un
+     * ratio à zéro provoquerait une division par zéro au calcul du taux
+     * d'encadrement.
+     *
+     * Charge utile (POST) : structure_id, type_equipe, libelle, date_debut,
+     * date_fin, effectifs et ratios facultatifs, csrf_token.
+     */
     public function index(): void
     {
         $this->access->requireService();
@@ -90,6 +120,20 @@ final class TeamController
         }
     }
 
+    /**
+     * POST api/team_members.php — ajoute ou retire un agent d'une équipe.
+     *
+     * `action` vaut ADD (défaut) ou REMOVE. Trois fonctions possibles :
+     * RESPONSABLE, ANIMATION, RESTAURATION_ENTRETIEN — elles conditionnent le
+     * calcul du taux d'encadrement.
+     *
+     * L'exception d'ajout ressort en 422 avec SON message : le modèle y place
+     * les refus métier lisibles (agent déjà membre, par exemple), destinés à
+     * l'utilisateur.
+     *
+     * Charge utile : action, team_id, agent_id, fonction_equipe, commentaire,
+     * csrf_token.
+     */
     public function member(): void
     {
         $this->access->requireService();
@@ -127,6 +171,15 @@ final class TeamController
         }
     }
 
+    /**
+     * POST api/team_status.php — fait avancer une équipe dans son cycle de vie.
+     *
+     * Aucune transition n'est imposée : tout statut valide est acceptable depuis
+     * n'importe quel autre, y compris un retour en arrière. Le suivi est
+     * indicatif, pas un verrou.
+     *
+     * Charge utile : team_id, statut (BROUILLON|A_CONTROLER|VALIDEE), csrf_token.
+     */
     public function status(): void
     {
         $this->access->requireService();