Ajout des commentaires dans le code

app/Controllers/RoleController.php

@@ -12,12 +12,41 @@ use App\Models\AgentModel;
 use App\Models\StructureModel;
 use PDO;
 
+/**
+ * Sélection du rôle et de l'identité de travail.
+ *
+ * ATTENTION : ce n'est PAS une authentification. L'utilisateur choisit
+ * librement qui il est, sans mot de passe ni vérification. C'est la faille
+ * ouverte la plus importante du projet, assumée pour cette version. Un passage
+ * en production doit remplacer cet écran par une authentification réelle — le
+ * reste de la mécanique de droits (Access, vues SQL) n'a pas à bouger, il
+ * suffit que la session soit renseignée par un compte vérifié.
+ *
+ * Contrairement aux autres pages, ce contrôleur n'est pas appelé par runPage() :
+ * il s'exécute AVANT tout contrôle d'accès, puisqu'il est ce qui permet d'en
+ * avoir un.
+ */
 final class RoleController extends Controller
 {
     public function __construct(private PDO $pdo)
     {
     }
 
+    /**
+     * Affiche le sélecteur et traite sa soumission.
+     *
+     * Trois chemins dans une seule méthode, faute de routeur :
+     *  - GET ?action=reset : abandon du rôle courant, puis redirection ;
+     *  - POST              : tentative de sélection, puis redirection vers
+     *                        l'accueil du rôle ou réaffichage avec $error ;
+     *  - GET simple        : affichage du formulaire.
+     *
+     * Le CSRF est vérifié à la main plutôt que par Csrf::assertPayload() : les
+     * données arrivent ici en formulaire classique ($_POST / $_GET) et non en
+     * JSON, et un échec doit produire une page HTML, pas une réponse JSON.
+     * Un jeton invalide sur le reset est ignoré EN SILENCE : l'utilisateur est
+     * simplement renvoyé au sélecteur, sans message d'échec inutile.
+     */
     public function index(): void
     {
         $access = new Access($this->pdo);