From 1a67080268ac9d525ab4588e62e3cce9add88432 Mon Sep 17 00:00:00 2001
From: PTA <antoineloic056@gmail.com>
Date: Tue, 25 Aug 2026 15:12:11 +0200
Subject: [PATCH] update

---
 CLAUDE.md                                     |   15 +
 api/acces_compte_creer.php                    |   20 +
 api/acces_compte_jeton.php                    |   19 +
 api/acces_compte_statut.php                   |   19 +
 api/acces_comptes.php                         |   20 +
 api/acces_comptes_manquants.php               |   19 +
 app/Controllers/AccessAccountController.php   |  366 +++++
 app/Controllers/PageController.php            |   26 +-
 app/Models/AgentModel.php                     |   47 +-
 app/Models/CompteModel.php                    |   44 +-
 app/Views/layouts/footer.php                  |    6 +-
 app/Views/layouts/header.php                  |    2 +-
 app/Views/pages/role.php                      |    2 +-
 app/Views/partials/administration.php         |  121 +-
 app/Views/partials/faq.php                    |    2 +
 app/Views/partials/manage_agents.php          |   17 +-
 assets/js/access-tokens.js                    |  345 +++++
 assets/js/administration.js                   |    9 +-
 assets/js/agent-access.js                     |  158 ++
 assets/js/page-bootstrap.js                   |   13 +-
 assets/style.css                              |   14 +
 ...migration_v7_9h_jetons_service_enfance.sql |   56 +
 docs/README.md                                | 1287 ++++++++++++++++-
 docs/README_DOCKER.md                         |  129 --
 docs/README_V7_27.md                          |  121 ++
 25 files changed, 2646 insertions(+), 231 deletions(-)
 create mode 100644 api/acces_compte_creer.php
 create mode 100644 api/acces_compte_jeton.php
 create mode 100644 api/acces_compte_statut.php
 create mode 100644 api/acces_comptes.php
 create mode 100644 api/acces_comptes_manquants.php
 create mode 100644 app/Controllers/AccessAccountController.php
 create mode 100644 assets/js/access-tokens.js
 create mode 100644 assets/js/agent-access.js
 create mode 100644 database/migration_v7_9h_jetons_service_enfance.sql
 delete mode 100644 docs/README_DOCKER.md
 create mode 100644 docs/README_V7_27.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 890c0c1..02926b8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -139,6 +139,15 @@ et haché par `password_hash()`. La règle « qui doit avoir un mot de passe »
 qu'une attente horodatée de cinq minutes : **un jeton validé sans mot de passe n'ouvre rien**. La DSI
 peut effacer un mot de passe, jamais en poser un — sans quoi elle connaîtrait celui de tout le monde.
 
+Depuis la V7.27 (`README_V7_27.md`), le Service Enfance distribue lui-même les jetons des rôles
+`AGENT` et `RESPONSABLE_STRUCTURE`, depuis l'onglet « Administration »
+(`AccessAccountController`, `api/acces_*.php`). **La délégation s'arrête à ces deux rôles** : un
+compte `SERVICE_ENFANCE` créé par le Service Enfance serait une auto-promotion, un compte `DSI` lui
+ouvrirait le journal de ses propres actions. La borne est posée des deux côtés —
+`AccessAccountController::ROLES_DELEGUES` en PHP, `can_manage_field_access` en base — et ne doit être
+élargie ni d'un côté ni de l'autre. La DSI reste seule sur les comptes privilégiés, les mots de passe
+et le journal.
+
 `Access` relit le compte à **chaque requête** (`v_acces_compte`, filtrée sur `actif` et
 `identite_active`) : c'est ce qui fait qu'un jeton révoqué, un agent désactivé ou un lieu fermé
 referment la session en cours. Ne pas mettre ce résultat en cache entre deux requêtes.
@@ -242,6 +251,12 @@ les navigateurs et le `expires 7d` de nginx servent l'ancienne version.
 - Un `planning` = un agent × une semaine ISO × un lieu, statut `BROUILLON` ou `VALIDE`. Il contient
   des `creneau_horaire` porteurs d'un `motif_planning`. Le flag `compte_dans_quota` du motif décide
   de l'imputation (CONGE, AUTRE_ABSENCE et JNT ne comptent pas).
+- **Un compte d'accès coupé retire l'agent des listes d'AFFECTATION** (V7.29) : sélecteur de la
+  saisie (`AgentModel::listForLocation()`) et composition des équipes (`allSelectable()`). Un agent
+  **sans compte** reste proposé — c'est l'état normal avant distribution des jetons, le filtrer
+  viderait les listes d'une installation neuve. Les écrans de consultation et le référentiel
+  « Agents » continuent de le montrer : c'est de là qu'on lui rétablit son accès. `allActive()` reste
+  la liste non filtrée ; ne pas confondre les deux.
 - Un agent peut être planifié sur plusieurs lieux la même semaine ; `id_structure` sur l'agent n'est
   qu'un rattachement par défaut. D'où les contrôles de chevauchement inter-structures.
 - Les vacances scolaires (`periode_vacance`) déterminent le contexte périscolaire/extrascolaire ;
diff --git a/api/acces_compte_creer.php b/api/acces_compte_creer.php
new file mode 100644
index 0000000..79dd943
--- /dev/null
+++ b/api/acces_compte_creer.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/app/autoload.php';
+
+/**
+ * POST — crée un compte de terrain et renvoie son jeton, affiché une seule fois.
+ * Charge utile : role (AGENT | RESPONSABLE_STRUCTURE), agent_id, structure_id,
+ * commentaire, csrf_token.
+ *
+ * Point d'entrée mince : toute la logique est dans le contrôleur appelé.
+ * Voir CLAUDE.md, section « Deux types de points d'entrée ».
+ */
+use App\Controllers\AccessAccountController;
+use App\Core\JsonResponse;
+
+JsonResponse::bootstrap();
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new AccessAccountController($pdo))->creerCompte();
diff --git a/api/acces_compte_jeton.php b/api/acces_compte_jeton.php
new file mode 100644
index 0000000..e34f0c4
--- /dev/null
+++ b/api/acces_compte_jeton.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/app/autoload.php';
+
+/**
+ * POST — régénère le jeton d'un compte de terrain ; l'ancien est révoqué.
+ * Charge utile : compte_id, csrf_token.
+ *
+ * Point d'entrée mince : toute la logique est dans le contrôleur appelé.
+ * Voir CLAUDE.md, section « Deux types de points d'entrée ».
+ */
+use App\Controllers\AccessAccountController;
+use App\Core\JsonResponse;
+
+JsonResponse::bootstrap();
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new AccessAccountController($pdo))->regenererJeton();
diff --git a/api/acces_compte_statut.php b/api/acces_compte_statut.php
new file mode 100644
index 0000000..ca2422e
--- /dev/null
+++ b/api/acces_compte_statut.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/app/autoload.php';
+
+/**
+ * POST — active, désactive ou supprime un compte de terrain.
+ * Charge utile : compte_id, action (ACTIVER | DESACTIVER | SUPPRIMER), csrf_token.
+ *
+ * Point d'entrée mince : toute la logique est dans le contrôleur appelé.
+ * Voir CLAUDE.md, section « Deux types de points d'entrée ».
+ */
+use App\Controllers\AccessAccountController;
+use App\Core\JsonResponse;
+
+JsonResponse::bootstrap();
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new AccessAccountController($pdo))->changerStatutCompte();
diff --git a/api/acces_comptes.php b/api/acces_comptes.php
new file mode 100644
index 0000000..3656731
--- /dev/null
+++ b/api/acces_comptes.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/app/autoload.php';
+
+/**
+ * GET — comptes d'accès des agents et des responsables de lieu (Service Enfance).
+ * Les comptes Service Enfance et DSI n'y figurent jamais.
+ * Paramètres : role, actif, q.
+ *
+ * Point d'entrée mince : toute la logique est dans le contrôleur appelé.
+ * Voir CLAUDE.md, section « Deux types de points d'entrée ».
+ */
+use App\Controllers\AccessAccountController;
+use App\Core\JsonResponse;
+
+JsonResponse::bootstrap();
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new AccessAccountController($pdo))->comptes();
diff --git a/api/acces_comptes_manquants.php b/api/acces_comptes_manquants.php
new file mode 100644
index 0000000..bc895ff
--- /dev/null
+++ b/api/acces_comptes_manquants.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+require_once dirname(__DIR__) . '/app/autoload.php';
+
+/**
+ * POST — génère un jeton pour chaque agent et chaque lieu actif qui n'en a pas.
+ * Charge utile : csrf_token.
+ *
+ * Point d'entrée mince : toute la logique est dans le contrôleur appelé.
+ * Voir CLAUDE.md, section « Deux types de points d'entrée ».
+ */
+use App\Controllers\AccessAccountController;
+use App\Core\JsonResponse;
+
+JsonResponse::bootstrap();
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new AccessAccountController($pdo))->genererJetonsManquants();
diff --git a/app/Controllers/AccessAccountController.php b/app/Controllers/AccessAccountController.php
new file mode 100644
index 0000000..ea58c0b
--- /dev/null
+++ b/app/Controllers/AccessAccountController.php
@@ -0,0 +1,366 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controllers;
+
+use App\Core\Access;
+use App\Core\Csrf;
+use App\Core\Journal;
+use App\Core\JsonResponse;
+use App\Core\Request;
+use App\Models\CompteModel;
+use DomainException;
+use PDO;
+
+/**
+ * Jetons d'accès de terrain (V7.27) : le Service Enfance équipe ses agents et
+ * ses responsables de lieu.
+ *
+ * POURQUOI CE CONTRÔLEUR EXISTE À CÔTÉ DE DsiController : c'est le Service
+ * Enfance qui sait qu'un agent est arrivé, qu'un responsable a perdu son jeton
+ * ou qu'un remplaçant s'en va. Passer par la DSI pour chaque mouvement ajoutait
+ * un délai sans ajouter de contrôle. La DSI conserve tout : ses propres comptes,
+ * ceux du Service Enfance, le journal, la purge.
+ *
+ * LA FRONTIÈRE DE PRIVILÈGE, à ne jamais élargir :
+ *
+ *   - self::ROLES_DELEGUES ne contient QUE AGENT et RESPONSABLE_STRUCTURE.
+ *     Y ajouter SERVICE_ENFANCE ferait du rôle son propre distributeur — une
+ *     auto-promotion sans contrôle externe ; y ajouter DSI lui ouvrirait le
+ *     journal, c'est-à-dire la trace de ses propres actions ;
+ *   - toute méthode qui désigne un compte existant passe par
+ *     compteDelegue() AVANT d'agir. Un identifiant de compte privilégié est
+ *     refusé en 403, jamais silencieusement ignoré ;
+ *   - la liste blanche est doublée en base
+ *     (database/migration_v7_9h_jetons_service_enfance.sql) : une frontière de
+ *     privilège ne doit pas dépendre d'un seul des deux côtés.
+ *
+ * Les deux règles de DsiController restent valables ici :
+ *  1. un jeton en clair ne sort qu'AU MOMENT où il vient d'être produit ;
+ *  2. toute action est journalisée en catégorie ADMINISTRATION, sans jamais
+ *     recopier le jeton dans la trace.
+ */
+final class AccessAccountController
+{
+    /**
+     * Les seuls rôles dont le Service Enfance distribue les jetons.
+     * Lire l'en-tête de classe avant d'y toucher.
+     */
+    private const ROLES_DELEGUES = [Access::ROLE_AGENT, Access::ROLE_RESPONSABLE];
+
+    private Access $access;
+    private CompteModel $comptes;
+
+    public function __construct(private PDO $pdo)
+    {
+        $this->access = new Access($pdo);
+        $this->comptes = new CompteModel($pdo);
+    }
+
+    /**
+     * GET api/acces_comptes.php — comptes de terrain et identités sans compte.
+     *
+     * Paramètres GET : role (dans la liste déléguée), actif, q.
+     */
+    public function comptes(): void
+    {
+        $this->access->requireService();
+
+        $comptes = $this->comptes->lister([
+            'roles' => self::ROLES_DELEGUES,
+            'role' => (string) ($_GET['role'] ?? ''),
+            'actif' => (string) ($_GET['actif'] ?? ''),
+            'q' => (string) ($_GET['q'] ?? ''),
+        ]);
+
+        JsonResponse::send(200, [
+            'comptes' => $comptes,
+            // v_acces_compte_manquant ne produit que des identités AGENT et
+            // RESPONSABLE_STRUCTURE : elle est déjà dans le périmètre délégué.
+            'manquants' => $this->comptes->manquants(),
+            'roles' => $this->rolesDelegues(),
+        ]);
+    }
+
+    /**
+     * POST api/acces_compte_creer.php — crée un compte de terrain et renvoie son
+     * jeton.
+     *
+     * Le libellé n'est pas saisi : pour ces deux rôles il est TOUJOURS déduit de
+     * l'identité (nom de l'agent, nom du lieu), par CompteModel. Un titulaire ne
+     * peut donc pas être maquillé sous un autre nom dans la liste.
+     *
+     * Charge utile : role, agent_id, structure_id, commentaire, csrf_token.
+     */
+    public function creerCompte(): void
+    {
+        $this->access->requireService();
+        Request::requireMethod('POST');
+        $payload = Request::json();
+        Csrf::assertPayload($payload);
+
+        $role = strtoupper(trim((string) ($payload['role'] ?? '')));
+        $this->assertRoleDelegue($role);
+
+        $agentId = filter_var($payload['agent_id'] ?? null, FILTER_VALIDATE_INT) ?: null;
+        $structureId = filter_var($payload['structure_id'] ?? null, FILTER_VALIDATE_INT) ?: null;
+        $commentaire = trim((string) ($payload['commentaire'] ?? ''));
+
+        try {
+            $resultat = $this->comptes->creer(
+                $role,
+                $agentId !== null ? (int) $agentId : null,
+                $structureId !== null ? (int) $structureId : null,
+                '',
+                $commentaire !== '' ? $commentaire : null
+            );
+        } catch (DomainException $e) {
+            JsonResponse::send(422, ['error' => $e->getMessage()]);
+            return;
+        }
+
+        $compte = $resultat['compte'];
+        Journal::administration('COMPTE_CREE', [
+            'cible_table' => 'compte_acces',
+            'cible_id' => (int) $compte['id_compte'],
+            'description' => sprintf(
+                'Création du compte d’accès « %s » (%s) par le Service Enfance.',
+                (string) $compte['identite_libelle'],
+                (string) $compte['role']
+            ),
+            'contexte' => [
+                'role' => $compte['role'],
+                'prefixe' => $compte['jeton_prefixe'],
+                'canal' => 'DELEGATION_SERVICE_ENFANCE',
+            ],
+        ]);
+
+        JsonResponse::send(201, [
+            'message' => sprintf('Compte créé pour %s. Transmettez le jeton : il ne sera plus affiché.', (string) $compte['identite_libelle']),
+            'compte' => $compte,
+            'jeton' => $resultat['jeton'],
+        ]);
+    }
+
+    /**
+     * POST api/acces_compte_jeton.php — régénère le jeton d'un compte de terrain.
+     *
+     * C'est la procédure du jeton perdu comme du jeton compromis : l'ancien
+     * cesse immédiatement de fonctionner.
+     *
+     * Charge utile : compte_id, csrf_token.
+     */
+    public function regenererJeton(): void
+    {
+        $this->access->requireService();
+        Request::requireMethod('POST');
+        $payload = Request::json();
+        Csrf::assertPayload($payload);
+
+        $compteId = (int) (filter_var($payload['compte_id'] ?? null, FILTER_VALIDATE_INT) ?: 0);
+        $compte = $this->compteDelegue($compteId);
+
+        try {
+            $jeton = $this->comptes->regenererJeton($compteId);
+        } catch (DomainException $e) {
+            JsonResponse::send(404, ['error' => $e->getMessage()]);
+            return;
+        }
+
+        $apres = $this->comptes->trouver($compteId) ?? $compte;
+        Journal::administration('JETON_REGENERE', [
+            'cible_table' => 'compte_acces',
+            'cible_id' => $compteId,
+            'description' => sprintf(
+                'Régénération du jeton de « %s » par le Service Enfance : l’ancien jeton est révoqué.',
+                (string) $apres['identite_libelle']
+            ),
+            'contexte' => [
+                'role' => $apres['role'],
+                'prefixe' => $apres['jeton_prefixe'] ?? null,
+                'canal' => 'DELEGATION_SERVICE_ENFANCE',
+            ],
+        ]);
+
+        JsonResponse::send(200, [
+            'message' => 'Nouveau jeton généré. L’ancien ne fonctionne plus.',
+            'compte' => $apres,
+            'jeton' => $jeton,
+        ]);
+    }
+
+    /**
+     * POST api/acces_compte_statut.php — active, désactive ou supprime un compte
+     * de terrain.
+     *
+     * La suppression efface le compte mais PAS ses traces : le journal conserve
+     * le libellé figé de l'acteur.
+     *
+     * Charge utile : compte_id, action (ACTIVER | DESACTIVER | SUPPRIMER),
+     * csrf_token.
+     */
+    public function changerStatutCompte(): void
+    {
+        $this->access->requireService();
+        Request::requireMethod('POST');
+        $payload = Request::json();
+        Csrf::assertPayload($payload);
+
+        $compteId = (int) (filter_var($payload['compte_id'] ?? null, FILTER_VALIDATE_INT) ?: 0);
+        $action = strtoupper(trim((string) ($payload['action'] ?? '')));
+
+        if (!in_array($action, ['ACTIVER', 'DESACTIVER', 'SUPPRIMER'], true)) {
+            JsonResponse::send(422, ['error' => 'Action inconnue.']);
+        }
+
+        // La fiche est lue AVANT l'opération, et sa lecture vaut contrôle de
+        // périmètre : après une suppression, il n'y aurait plus ni rôle à
+        // vérifier ni libellé à écrire dans le journal. Le compte de la session
+        // en cours est hors périmètre par construction (c'est un compte
+        // SERVICE_ENFANCE), il n'y a donc pas d'auto-désactivation à empêcher.
+        $compte = $this->compteDelegue($compteId);
+
+        try {
+            if ($action === 'SUPPRIMER') {
+                $this->comptes->supprimer($compteId);
+            } else {
+                $this->comptes->definirActif($compteId, $action === 'ACTIVER');
+            }
+        } catch (DomainException $e) {
+            JsonResponse::send(422, ['error' => $e->getMessage()]);
+            return;
+        }
+
+        $libelles = [
+            'ACTIVER' => 'Réactivation',
+            'DESACTIVER' => 'Désactivation',
+            'SUPPRIMER' => 'Suppression',
+        ];
+
+        Journal::administration('COMPTE_' . $action, [
+            'cible_table' => 'compte_acces',
+            'cible_id' => $compteId,
+            'description' => sprintf(
+                '%s du compte d’accès « %s » (%s) par le Service Enfance.',
+                $libelles[$action],
+                (string) $compte['identite_libelle'],
+                (string) $compte['role']
+            ),
+            'contexte' => [
+                'role' => $compte['role'],
+                'prefixe' => $compte['jeton_prefixe'],
+                'canal' => 'DELEGATION_SERVICE_ENFANCE',
+            ],
+        ]);
+
+        JsonResponse::send(200, [
+            'message' => sprintf('%s effectuée pour %s.', $libelles[$action], (string) $compte['identite_libelle']),
+        ]);
+    }
+
+    /**
+     * POST api/acces_comptes_manquants.php — équipe d'un coup toutes les
+     * identités actives sans compte.
+     *
+     * Sans danger d'élargissement : v_acces_compte_manquant ne connaît que des
+     * agents et des lieux, jamais un compte privilégié. La réponse porte tous
+     * les jetons produits, en clair — seule occasion de les lire.
+     *
+     * Charge utile : csrf_token.
+     */
+    public function genererJetonsManquants(): void
+    {
+        $this->access->requireService();
+        Request::requireMethod('POST');
+        $payload = Request::json();
+        Csrf::assertPayload($payload);
+
+        try {
+            $produits = $this->comptes->genererManquants();
+        } catch (DomainException $e) {
+            JsonResponse::send(422, ['error' => $e->getMessage()]);
+            return;
+        }
+
+        Journal::administration('JETONS_GENERES_EN_LOT', [
+            'cible_table' => 'compte_acces',
+            'cible_id' => null,
+            'description' => sprintf(
+                'Génération de %d jeton(s) de terrain par le Service Enfance.',
+                count($produits)
+            ),
+            'contexte' => ['nombre' => count($produits), 'canal' => 'DELEGATION_SERVICE_ENFANCE'],
+        ]);
+
+        JsonResponse::send(200, [
+            'message' => $produits === []
+                ? 'Tous les agents et tous les lieux actifs disposent déjà d’un compte.'
+                : sprintf('%d jeton(s) généré(s). Distribuez-les maintenant : ils ne seront plus affichés.', count($produits)),
+            'jetons' => $produits,
+        ]);
+    }
+
+    /**
+     * Relit un compte et REFUSE tout ce qui sort du périmètre délégué.
+     *
+     * Le refus est un 403 explicite et non un 404 : masquer l'existence du
+     * compte n'apporterait rien (le Service Enfance sait parfaitement que la DSI
+     * existe) et rendrait le message incompréhensible à l'utilisateur de bonne
+     * foi qui a suivi un lien périmé.
+     *
+     * @return array<string, mixed> Le compte, garanti dans le périmètre.
+     */
+    private function compteDelegue(int $compteId): array
+    {
+        $compte = $this->comptes->trouver($compteId);
+        if ($compte === null) {
+            JsonResponse::send(404, ['error' => 'Compte introuvable.']);
+        }
+
+        if (!in_array((string) $compte['role'], self::ROLES_DELEGUES, true)) {
+            Journal::refus('COMPTE_HORS_PERIMETRE', 'Tentative de gestion d’un compte privilégié hors délégation.', [
+                'cible_table' => 'compte_acces',
+                'cible_id' => $compteId,
+                'contexte' => ['role_cible' => $compte['role'], 'statut_http' => 403],
+            ]);
+            JsonResponse::send(403, [
+                'error' => 'Les comptes Service Enfance et DSI relèvent de la seule DSI.',
+                'code' => 'ACCESS_DENIED',
+            ]);
+        }
+
+        return $compte;
+    }
+
+    /** Refuse un rôle demandé hors périmètre délégué, avant toute écriture. */
+    private function assertRoleDelegue(string $role): void
+    {
+        if (in_array($role, self::ROLES_DELEGUES, true)) {
+            return;
+        }
+
+        Journal::refus('ROLE_HORS_PERIMETRE', 'Tentative de création d’un compte hors délégation.', [
+            'cible_table' => 'compte_acces',
+            'cible_id' => null,
+            'contexte' => ['role_demande' => $role, 'statut_http' => 403],
+        ]);
+        JsonResponse::send(403, [
+            'error' => 'Vous ne pouvez créer que des comptes Agent et Responsable de structure. Les comptes Service Enfance et DSI relèvent de la DSI.',
+            'code' => 'ACCESS_DENIED',
+        ]);
+    }
+
+    /**
+     * Rôles proposés à la création, avec leur libellé.
+     *
+     * @return array<int, array{code: string, libelle: string, identite: string}>
+     */
+    private function rolesDelegues(): array
+    {
+        return [
+            ['code' => Access::ROLE_AGENT, 'libelle' => 'Agent', 'identite' => 'AGENT'],
+            ['code' => Access::ROLE_RESPONSABLE, 'libelle' => 'Responsable de structure', 'identite' => 'STRUCTURE'],
+        ];
+    }
+}
diff --git a/app/Controllers/PageController.php b/app/Controllers/PageController.php
index 100e3bc..713440e 100644
--- a/app/Controllers/PageController.php
+++ b/app/Controllers/PageController.php
@@ -223,7 +223,9 @@ final class PageController extends Controller
         $this->access->requirePage('teams');
         $this->renderPage('teams', 'Équipes des mercredis et vacances', 'teams', [
             'pageSubtitle' => 'La composition des équipes sur les mercredis et les périodes de vacances.',
-            'agents' => (new AgentModel($this->pdo))->allActive(),
+            // Liste d'AFFECTATION : un agent dont l'accès a été coupé n'est plus
+            // proposé à la composition d'une équipe (V7.29).
+            'agents' => (new AgentModel($this->pdo))->allSelectable(),
             'structures' => (new StructureModel($this->pdo))->allActive(),
             'scripts' => ['teams.js'],
             'modules' => ['teams'],
@@ -254,13 +256,16 @@ final class PageController extends Controller
     {
         $this->access->requirePage('administration');
         $this->renderPage('administration', 'Administration', 'administration', [
-            'pageSubtitle' => 'Les horaires de couverture attendus de chaque lieu : les plages où un effectif minimum doit être présent.',
-            // Depuis la V7.14, cet écran ne porte plus que les règles de
-            // couverture : agents et lieux ont leur propre page (management).
-            // Seule la liste des lieux reste nécessaire, pour son sélecteur.
+            'pageSubtitle' => 'Les horaires de couverture attendus de chaque lieu, et les jetons d\'accès des agents et des responsables.',
+            // Depuis la V7.14, cet écran ne porte plus les agents ni les lieux :
+            // ils ont leur propre page (management). Seule la liste des lieux
+            // reste nécessaire, pour son sélecteur.
             'structures' => (new StructureModel($this->pdo))->allActive(),
-            'scripts' => ['coverage.js'],
-            'modules' => ['coverage'],
+            // V7.27 : la distribution des jetons de terrain rejoint cet écran.
+            // Le contenu de la section vient entièrement de l'API — le HTML
+            // servi ne porte aucune information sur les comptes.
+            'scripts' => ['coverage.js', 'access-tokens.js'],
+            'modules' => ['coverage', 'accessTokens'],
         ]);
     }
 
@@ -289,8 +294,11 @@ final class PageController extends Controller
             'agents' => $agentModel->allActive(),
             'structures' => (new StructureModel($this->pdo))->allActive(),
             'posts' => $agentModel->allPosts(),
-            'scripts' => ['administration.js', 'address-autocomplete.js', 'field-format.js'],
-            'modules' => ['administration', 'addressAutocomplete', 'fieldFormat'],
+            // V7.28 : `agentAccess` ajoute sur chaque ligne le bouton qui coupe
+            // ou rétablit l'accès de l'agent. Il n'ouvre aucun droit nouveau —
+            // il réutilise les endpoints délégués de la V7.27.
+            'scripts' => ['administration.js', 'address-autocomplete.js', 'field-format.js', 'agent-access.js'],
+            'modules' => ['administration', 'addressAutocomplete', 'fieldFormat', 'agentAccess'],
         ]);
     }
 
diff --git a/app/Models/AgentModel.php b/app/Models/AgentModel.php
index bc7bfc5..2f84726 100644
--- a/app/Models/AgentModel.php
+++ b/app/Models/AgentModel.php
@@ -221,7 +221,37 @@ final class AgentModel extends BaseModel
     SQL;
 
     /**
-     * Tous les agents actifs.
+     * Retire des listes D'AFFECTATION les agents dont le COMPTE D'ACCÈS est
+     * désactivé (V7.29).
+     *
+     * Trois précisions, toutes portées par le `NOT EXISTS` :
+     *
+     *  - un agent SANS compte reste proposé. Il n'a simplement pas encore reçu
+     *     son jeton, ce qui est l'état normal avant distribution : le filtrer
+     *     viderait les listes d'une installation neuve ;
+     *  - le filtre porte sur `compte_acces.actif`, PAS sur `agent.actif`, qui
+     *     est déjà exigé par ailleurs. Ce sont deux décisions distinctes :
+     *     fermer une fiche d'agent et couper un accès ;
+     *  - il ne s'applique QU'AUX listes où l'on affecte. Les écrans de
+     *     consultation (planning par agent, vue annuelle, PTA détaillé) et le
+     *     référentiel « Agents » continuent de montrer l'agent — sans quoi on ne
+     *     pourrait plus ni lire son année passée, ni lui rétablir son accès.
+     *
+     * La table compte_acces est garantie présente : SchemaModel::assertCurrent()
+     * refuse de démarrer si les vues de comptes manquent.
+     */
+    private const SANS_COMPTE_COUPE = <<<'SQL'
+        AND NOT EXISTS (
+            SELECT 1 FROM compte_acces ca
+            WHERE ca.id_agent = a.id_agent AND ca.actif = 0
+        )
+    SQL;
+
+    /**
+     * Tous les agents actifs, y compris ceux dont l'accès est coupé.
+     *
+     * Liste de RÉFÉRENTIEL et de CONSULTATION. Pour une liste où l'on affecte,
+     * voir allSelectable().
      *
      * @return array<int, array<string, mixed>>
      */
@@ -232,6 +262,19 @@ final class AgentModel extends BaseModel
         )->fetchAll();
     }
 
+    /**
+     * Agents proposables dans une liste d'affectation : actifs ET dont le compte
+     * d'accès n'a pas été coupé.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    public function allSelectable(): array
+    {
+        return $this->pdo->query(
+            self::AGENT_SELECT . " WHERE a.actif = TRUE" . self::SANS_COMPTE_COUPE . " ORDER BY a.nom, a.prenom"
+        )->fetchAll();
+    }
+
     /**
      * Agents visibles depuis un lieu : ceux qui y sont RATTACHÉS, plus ceux qui
      * y ont un planning, quel que soit leur rattachement.
@@ -328,7 +371,7 @@ final class AgentModel extends BaseModel
              FROM agent a
              LEFT JOIN poste_agent po ON po.id_poste = a.id_poste
              LEFT JOIN structure s ON s.id_structure = a.id_structure
-             WHERE a.actif = TRUE
+             WHERE a.actif = TRUE" . self::SANS_COMPTE_COUPE . "
              ORDER BY lieu_principal_selectionne DESC, a.nom, a.prenom"
         );
         $stmt->execute(['selected_location' => $selectedLocation]);
diff --git a/app/Models/CompteModel.php b/app/Models/CompteModel.php
index 99cda69..951de35 100644
--- a/app/Models/CompteModel.php
+++ b/app/Models/CompteModel.php
@@ -125,9 +125,16 @@ final class CompteModel extends BaseModel
     }
 
     /**
-     * Liste des comptes pour la page DSI.
+     * Liste des comptes pour la page DSI et pour la page « Jetons d'accès » du
+     * Service Enfance.
      *
-     * @param array<string, mixed> $filtres role, actif (0|1), q (texte libre).
+     * `roles` BORNE la liste à un ensemble de rôles. C'est ce qui permet à la
+     * délégation V7.27 de ne jamais laisser voir un compte privilégié : le
+     * contrôleur passe sa liste blanche, et aucun filtre d'interface ne peut
+     * l'élargir — `role` ne fait que restreindre à l'intérieur de `roles`.
+     *
+     * @param array<string, mixed> $filtres role, actif (0|1), q (texte libre),
+     *        roles (array<int, string> facultatif).
      *
      * @return array<int, array<string, mixed>>
      */
@@ -136,10 +143,27 @@ final class CompteModel extends BaseModel
         $conditions = [];
         $params = [];
 
+        $rolesAutorises = array_values(array_filter(array_map(
+            static fn (mixed $role): string => strtoupper(trim((string) $role)),
+            (array) ($filtres['roles'] ?? [])
+        )));
+        if ($rolesAutorises !== []) {
+            $marqueurs = [];
+            foreach ($rolesAutorises as $index => $roleAutorise) {
+                $marqueurs[] = ':role_autorise_' . $index;
+                $params['role_autorise_' . $index] = $roleAutorise;
+            }
+            $conditions[] = 'role IN (' . implode(', ', $marqueurs) . ')';
+        }
+
         $role = (string) ($filtres['role'] ?? '');
-        if ($role !== '') {
+        // Le filtre d'interface ne peut que restreindre : un rôle hors de la
+        // liste blanche ne rend rien, il ne la contourne pas.
+        if ($role !== '' && ($rolesAutorises === [] || in_array(strtoupper($role), $rolesAutorises, true))) {
             $conditions[] = 'role = :role';
             $params['role'] = $role;
+        } elseif ($role !== '') {
+            $conditions[] = '1 = 0';
         }
 
         if (isset($filtres['actif']) && $filtres['actif'] !== '') {
@@ -149,8 +173,18 @@ final class CompteModel extends BaseModel
 
         $recherche = trim((string) ($filtres['q'] ?? ''));
         if ($recherche !== '') {
-            $conditions[] = '(identite_libelle LIKE :q OR libelle LIKE :q OR matricule LIKE :q OR jeton_prefixe LIKE :q)';
-            $params['q'] = '%' . $recherche . '%';
+            // UN MARQUEUR PAR COLONNE, et non un seul répété quatre fois : PDO
+            // tourne ici sans émulation de requêtes préparées (ATTR_EMULATE_
+            // PREPARES = 0), et MariaDB refuse alors un même paramètre nommé
+            // employé plusieurs fois — « Invalid parameter number ». Répéter
+            // « :q » faisait échouer toute recherche en 500.
+            $colonnes = ['identite_libelle', 'libelle', 'matricule', 'jeton_prefixe'];
+            $comparaisons = [];
+            foreach ($colonnes as $index => $colonne) {
+                $comparaisons[] = $colonne . ' LIKE :q_' . $index;
+                $params['q_' . $index] = '%' . $recherche . '%';
+            }
+            $conditions[] = '(' . implode(' OR ', $comparaisons) . ')';
         }
 
         $where = $conditions === [] ? '' : ' WHERE ' . implode(' AND ', $conditions);
diff --git a/app/Views/layouts/footer.php b/app/Views/layouts/footer.php
index 5229d28..afb96a4 100644
--- a/app/Views/layouts/footer.php
+++ b/app/Views/layouts/footer.php
@@ -51,10 +51,10 @@ window.PTA_PAGE_CONFIG = <?= json_encode([
     'params' => $pageConfig,
 ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE) ?>;
 </script>
-<script src="assets/js/core.js?v=7.26"></script>
+<script src="assets/js/core.js?v=7.29"></script>
 <?php foreach ($scripts as $script): ?>
-<script src="assets/js/<?= htmlspecialchars($script) ?>?v=7.26"></script>
+<script src="assets/js/<?= htmlspecialchars($script) ?>?v=7.29"></script>
 <?php endforeach; ?>
-<script src="assets/js/page-bootstrap.js?v=7.26"></script>
+<script src="assets/js/page-bootstrap.js?v=7.29"></script>
 </body>
 </html>
diff --git a/app/Views/layouts/header.php b/app/Views/layouts/header.php
index b0802e1..896c497 100644
--- a/app/Views/layouts/header.php
+++ b/app/Views/layouts/header.php
@@ -104,7 +104,7 @@ $showHelpTab = in_array('faq', $allowedPages, true);
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title><?= htmlspecialchars($pageTitle) ?> — PTA</title>
-    <link rel="stylesheet" href="assets/style.css?v=7.26">
+    <link rel="stylesheet" href="assets/style.css?v=7.29">
 </head>
 <body>
 <main class="app-shell">
diff --git a/app/Views/pages/role.php b/app/Views/pages/role.php
index dc9eab4..b66c6d8 100644
--- a/app/Views/pages/role.php
+++ b/app/Views/pages/role.php
@@ -43,7 +43,7 @@ $titre = $titres[$etape] ?? 'Connexion';
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title><?= htmlspecialchars($titre) ?> — PTA</title>
-    <link rel="stylesheet" href="assets/style.css?v=7.26">
+    <link rel="stylesheet" href="assets/style.css?v=7.29">
 </head>
 <body class="role-page-body">
 <main class="role-page-shell">
diff --git a/app/Views/partials/administration.php b/app/Views/partials/administration.php
index 64536b0..224d72a 100644
--- a/app/Views/partials/administration.php
+++ b/app/Views/partials/administration.php
@@ -1,7 +1,8 @@
 <?php
 /**
- * Administration : horaires de couverture attendus des lieux.
- * Module JS : `coverage`.
+ * Administration : horaires de couverture attendus des lieux, et jetons d'accès
+ * des agents et des responsables de lieu.
+ * Modules JS : `coverage` et `accessTokens`.
  *
  * Partiel de contenu inclus par la vue de page homonyme. Les identifiants HTML
  * posés ici sont les points d'ancrage du module JS : les renommer casse le
@@ -11,6 +12,13 @@
  * page « Management ». Ne restent ici que les règles de couverture, qui ne
  * décrivent ni une personne ni un lieu mais une EXIGENCE DE PRÉSENCE — le
  * paramètre que contrôle l'onglet « Couverture ».
+ *
+ * V7.27 : s'y ajoute la distribution des JETONS DE TERRAIN. Le Service Enfance
+ * équipe ses agents et ses responsables de lieu sans passer par la DSI, mais
+ * RIEN AU-DELÀ : les comptes Service Enfance et DSI n'apparaissent pas ici et
+ * sont refusés par le serveur (AccessAccountController). Les classes `dsi-*`
+ * sont réutilisées telles quelles — elles ne portent qu'une mise en forme, et
+ * les deux écrans montrent la même chose : des comptes et des jetons.
  */
 ?>
     <section id="assignment-view" class="app-view page-content">
@@ -43,4 +51,113 @@
                 <button id="save-coverage-rules" class="button button-primary" type="button" disabled>Enregistrer les horaires de couverture</button>
             </div>
         </section>
+
+        <!--
+            Jetons d'accès de terrain (V7.27).
+
+            Panneau des jetons fraîchement produits : c'est la SEULE occasion de
+            les lire, la base n'en conserve qu'une empreinte. Il reste ouvert
+            tant qu'il n'a pas été explicitement refermé, pour laisser le temps
+            de les recopier ou de les imprimer.
+        -->
+        <section id="access-token-panel" class="card dsi-token-panel" hidden>
+            <div class="section-heading">
+                <div>
+                    <h2>Jetons à transmettre</h2>
+                    <p class="section-subtitle">Ces jetons ne seront plus jamais affichés : la base n’en garde qu’une empreinte. Copiez-les, remettez-les à leurs titulaires, puis refermez ce panneau.</p>
+                </div>
+                <div class="button-group">
+                    <button id="access-token-copy" class="button button-secondary" type="button">Tout copier</button>
+                    <button id="access-token-close" class="button button-secondary" type="button">Fermer</button>
+                </div>
+            </div>
+            <div id="access-token-list" class="dsi-token-list"></div>
+            <div id="access-token-message" class="message" role="status" aria-live="polite"></div>
+        </section>
+
+        <section class="card">
+            <div class="section-heading">
+                <div>
+                    <h2>Jetons d’accès des agents et des responsables</h2>
+                    <p class="section-subtitle">Un compte par agent et par lieu d’affectation. Chacun se connecte avec son jeton : il n’y a pas de mot de passe pour ces deux rôles. Les comptes Service Enfance et DSI ne se gèrent pas ici — ils relèvent de la DSI.</p>
+                </div>
+                <button id="access-generate-missing" class="button button-secondary" type="button">
+                    Générer les jetons manquants <span id="access-missing-count" class="nav-count-badge" hidden>0</span>
+                </button>
+            </div>
+
+            <form id="access-account-form" class="admin-form">
+                <div class="admin-form-grid">
+                    <label class="field">
+                        <span>Type de compte</span>
+                        <select id="access-account-role" required>
+                            <option value="AGENT">Agent</option>
+                            <option value="RESPONSABLE_STRUCTURE">Responsable de structure</option>
+                        </select>
+                    </label>
+                    <label class="field" id="access-account-agent-field">
+                        <span>Agent titulaire</span>
+                        <select id="access-account-agent"><option value="">Choisir un agent sans compte</option></select>
+                    </label>
+                    <label class="field" id="access-account-structure-field" hidden>
+                        <span>Lieu titulaire</span>
+                        <select id="access-account-structure"><option value="">Choisir un lieu sans compte</option></select>
+                    </label>
+                    <label class="field admin-field-wide">
+                        <span>Commentaire (facultatif)</span>
+                        <input id="access-account-comment" type="text" maxlength="255" placeholder="Ex. remplacement congé maternité, jusqu’en septembre">
+                    </label>
+                </div>
+                <p id="access-account-hint" class="hint"></p>
+                <div class="admin-form-actions">
+                    <div id="access-account-message" class="message" role="status" aria-live="polite"></div>
+                    <button class="button button-primary" type="submit">Créer le compte et générer son jeton</button>
+                </div>
+            </form>
+
+            <div class="selection-grid overview-filters">
+                <label class="field">
+                    <span>Type</span>
+                    <select id="access-filter-role">
+                        <option value="">Agents et responsables</option>
+                        <option value="AGENT">Agents</option>
+                        <option value="RESPONSABLE_STRUCTURE">Responsables de structure</option>
+                    </select>
+                </label>
+                <label class="field">
+                    <span>État</span>
+                    <select id="access-filter-state">
+                        <option value="">Tous</option>
+                        <option value="1">Actifs</option>
+                        <option value="0">Désactivés</option>
+                    </select>
+                </label>
+                <label class="field">
+                    <span>Rechercher</span>
+                    <input id="access-filter-search" type="search" maxlength="80" placeholder="Nom, matricule ou début de jeton">
+                </label>
+                <div class="overview-filter-actions">
+                    <button id="access-accounts-refresh" class="button button-secondary filter-button" type="button">Actualiser</button>
+                </div>
+            </div>
+
+            <div id="access-accounts-message" class="message" role="status" aria-live="polite"></div>
+            <div class="table-scroll">
+                <table class="planning-table dsi-accounts-table">
+                    <thead>
+                        <tr>
+                            <th>Titulaire</th>
+                            <th>Type</th>
+                            <th>Jeton</th>
+                            <th>Dernière connexion</th>
+                            <th>État</th>
+                            <th>Actions</th>
+                        </tr>
+                    </thead>
+                    <tbody id="access-accounts-body">
+                        <tr><td colspan="6">Chargement des comptes…</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </section>
     </section>
diff --git a/app/Views/partials/faq.php b/app/Views/partials/faq.php
index 1141ad9..c8b11d6 100644
--- a/app/Views/partials/faq.php
+++ b/app/Views/partials/faq.php
@@ -155,6 +155,8 @@ $sommaire = [
                     <li><strong>Adresse personnelle</strong> : facultative et purement informative. Dès trois caractères saisis, une liste d’adresses officielles est proposée sous le champ (source : Base Adresse Nationale) — cliquez sur la bonne, ou continuez à écrire librement si l’adresse n’y figure pas.</li>
                     <li><strong>Observations utiles à la construction du PTA</strong> : disponibilités particulières, organisation connue… Ces notes se retrouvent sur l’écran « PTA détaillé ».</li>
                     <li>Cliquez sur <strong>Ajouter l’agent</strong>.</li>
+                    <li>Pour <strong>couper l’accès</strong> d’un agent (départ, arrêt long) sans supprimer sa fiche : bouton <strong>Couper l’accès</strong> sur sa ligne, à côté de Modifier. Son jeton reste valable et resservira tel quel au rétablissement. L’agent <strong>disparaît alors des listes d’affectation</strong> — saisie des plannings et composition des équipes — mais reste consultable, et ses créneaux déjà saisis sont conservés.</li>
+                    <li>Enfin, donnez-lui son <strong>jeton d’accès</strong> : onglet <strong>Administration</strong>, encadré « Jetons d’accès des agents et des responsables ». Le jeton n’est affiché <em>qu’une seule fois</em> — recopiez-le avant de refermer le panneau. Perdu, il ne se retrouve pas : il se régénère depuis le même écran, et l’ancien cesse alors de fonctionner. Les comptes Service Enfance et DSI, eux, restent gérés par la DSI.</li>
                 </ol>
                 <p class="hint"><strong>Dates de contrat :</strong> elles bornent la planification. Aucune affectation — pas même un congé — ne peut être posée avant la date de début ou après la date de fin. Un contrat sans date de fin est considéré comme à durée indéterminée. Raccourcir un contrat est refusé tant qu’il reste des affectations au-delà : supprimez-les d’abord.</p>
                 <p class="hint">Pour corriger une fiche existante, utilisez le tableau « Informations des agents » du même onglet : le bouton <strong>Modifier</strong> ouvre la fiche complète, nom, prénom et lieu principal compris. Seuls le <strong>matricule</strong> et la <strong>quotité de travail</strong> restent hors d’atteinte : le premier sert de clé avec les outils RH, la seconde détermine le quota déjà consommé de l’année.</p>
diff --git a/app/Views/partials/manage_agents.php b/app/Views/partials/manage_agents.php
index 6787c60..5407d7d 100644
--- a/app/Views/partials/manage_agents.php
+++ b/app/Views/partials/manage_agents.php
@@ -20,6 +20,11 @@
  * champ + `[data-address-suggestions]` + `[data-address-status]` — mais aucun
  * identifiant n'est connu du module.
  *
+ * V7.28 : chaque ligne d'agent porte, à côté de « Modifier », un bouton
+ * d'activation de son COMPTE D'ACCÈS (module `agentAccess`). Son libellé et son
+ * état sont posés par le JS après appel de l'API — le HTML servi ne dit rien des
+ * comptes, comme sur l'écran DSI.
+ *
  * Même principe pour l'e-mail et le téléphone : `data-format="email|phone"` sur
  * le champ et un `[data-format-status]` frère suffisent au module `fieldFormat`
  * à contrôler la saisie. Ce contrôle ne fait que PRÉVENIR : c'est
@@ -140,7 +145,7 @@
             <div class="section-heading">
                 <div>
                     <h2>Informations des agents</h2>
-                    <p class="section-subtitle">Consultez la qualification, les coordonnées et le lieu principal de chaque agent. Le bouton Modifier ouvre la fiche complète.</p>
+                    <p class="section-subtitle">Consultez la qualification, les coordonnées et le lieu principal de chaque agent. Le bouton Modifier ouvre la fiche complète ; le second bouton coupe ou rétablit l’accès de l’agent à l’application, sans toucher à son jeton.</p>
                 </div>
             </div>
             <div id="assignment-message" class="message" role="status" aria-live="polite"></div>
@@ -188,7 +193,15 @@
                                 <td class="agent-row-phone"><?= htmlspecialchars((string) (($agent['telephone'] ?? '') ?: 'Non renseigné')) ?></td>
                                 <td class="agent-row-contract-start"><?= htmlspecialchars((string) (($agent['date_debut_contrat'] ?? '') ?: 'Non renseignée')) ?></td>
                                 <td class="agent-row-structure"><?= htmlspecialchars((string) (($agent['structure_nom'] ?? '') ?: 'Sans lieu principal')) ?></td>
-                                <td><button type="button" class="button button-secondary edit-agent-profile">Modifier</button></td>
+                                <td class="agent-row-actions">
+                                    <button type="button" class="button button-secondary edit-agent-profile">Modifier</button>
+                                    <!--
+                                        État du compte d'accès rempli par le module `agentAccess`
+                                        après appel de l'API : le HTML servi ne porte aucune
+                                        information sur les comptes, comme sur l'écran DSI.
+                                    -->
+                                    <button type="button" class="button button-secondary agent-access-toggle" disabled>Compte d’accès…</button>
+                                </td>
                             </tr>
                         <?php endforeach; ?>
                     </tbody>
diff --git a/assets/js/access-tokens.js b/assets/js/access-tokens.js
new file mode 100644
index 0000000..7c44cf3
--- /dev/null
+++ b/assets/js/access-tokens.js
@@ -0,0 +1,345 @@
+/**
+ * Jetons d'accès de terrain (`PTA.modules.accessTokens`), écran administration.php
+ * — V7.27.
+ *
+ * Le Service Enfance équipe ses agents et ses responsables de lieu : création
+ * d'un compte, régénération d'un jeton perdu, désactivation, suppression, et
+ * génération en lot pour les identités qui n'en ont pas encore.
+ *
+ * PÉRIMÈTRE : agents et responsables de lieu, RIEN D'AUTRE. Les comptes Service
+ * Enfance et DSI ne sont ni listés ni créables. Ce module ne les propose pas, et
+ * le serveur les refuse en 403 (AccessAccountController) : l'écran ne fait que
+ * refléter une frontière qu'il ne décide pas.
+ *
+ * RÈGLE CENTRALE, héritée de l'espace DSI : un jeton n'existe en clair que dans
+ * la réponse qui vient de le produire. Il est affiché dans un panneau dédié, qui
+ * reste ouvert tant qu'il n'a pas été refermé, et n'est jamais rechargé depuis
+ * le serveur — la base n'en garde qu'une empreinte.
+ */
+(() => {
+    'use strict';
+    const PTA = window.PTA;
+    // core.js absent : la page reste lisible, simplement non interactive.
+    if (!PTA) return;
+
+    const { readJsonResponse, apiErrorMessage, escapeHtml } = PTA.utils;
+    const el = (id) => document.getElementById(id);
+
+    const LIBELLES_ROLE = {
+        RESPONSABLE_STRUCTURE: 'Responsable de structure',
+        AGENT: 'Agent',
+    };
+
+    /**
+     * Ce qu'il faut renseigner change selon le type de compte : l'écran
+     * l'explique plutôt que de laisser deviner pourquoi un champ change.
+     */
+    const AIDES_ROLE = {
+        AGENT: 'Compte en lecture seule sur son propre planning. Seuls les agents actifs qui n’ont pas encore de compte sont proposés.',
+        RESPONSABLE_STRUCTURE: 'Compte d’édition des brouillons d’un seul lieu. Seuls les lieux actifs qui n’ont pas encore de compte sont proposés.',
+    };
+
+    /** Message dans un des bandeaux de la section. */
+    function message(id, texte, type = 'info') {
+        const boite = el(id);
+        if (!boite) return;
+        boite.className = `message message-${type}`;
+        boite.textContent = texte;
+    }
+
+    /** Appel d'API mutualisé : toute réponse non-OK devient une exception. */
+    async function api(url, options = {}) {
+        const reponse = await fetch(url, options);
+        const donnees = await readJsonResponse(reponse);
+        if (!reponse.ok) throw new Error(apiErrorMessage(donnees, 'Opération impossible.'));
+        return donnees;
+    }
+
+    /** Raccourci des appels mutants : POST JSON avec le jeton CSRF dans le corps. */
+    function poster(url, charge) {
+        return api(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ csrf_token: window.PTA_CONFIG.csrfToken, ...charge }),
+        });
+    }
+
+    /** « 2026-08-20 09:41:07 » → « 20/08/2026 09:41 ». */
+    function formatDateHeure(valeur) {
+        if (!valeur) return '—';
+        const [date, heure = ''] = String(valeur).split(' ');
+        const [annee, mois, jour] = date.split('-');
+        return `${jour}/${mois}/${annee} ${heure.slice(0, 5)}`;
+    }
+
+    // ------------------------------------------------------------------ jetons
+
+    /**
+     * Affiche les jetons produits par la dernière action.
+     *
+     * @param {Array<{libelle: string, role: string, jeton: string}>} jetons
+     */
+    function afficherJetons(jetons) {
+        const panneau = el('access-token-panel');
+        const liste = el('access-token-list');
+        if (!panneau || !liste || !jetons.length) return;
+
+        liste.innerHTML = jetons.map((entree) => `
+            <div class="dsi-token-row">
+                <div class="dsi-token-identity">
+                    <strong>${escapeHtml(entree.libelle)}</strong>
+                    <small>${escapeHtml(LIBELLES_ROLE[entree.role] || entree.role)}</small>
+                </div>
+                <code class="dsi-token-value">${escapeHtml(entree.jeton)}</code>
+            </div>
+        `).join('');
+
+        panneau.hidden = false;
+        message('access-token-message', `${jetons.length} jeton(s) à transmettre. Ils ne seront plus affichés après fermeture.`, 'warning');
+        panneau.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+
+    /**
+     * Copie les jetons affichés dans le presse-papiers.
+     *
+     * L'API Clipboard n'existe QUE dans un contexte sécurisé : sur une
+     * installation en http:// sur le réseau de la collectivité, elle est
+     * absente. D'où le repli par zone de texte masquée, puis, en dernier
+     * ressort, l'invitation à sélectionner à la main.
+     */
+    async function copierJetons() {
+        const lignes = Array.from(document.querySelectorAll('#access-token-list .dsi-token-row')).map((ligne) => {
+            const identite = ligne.querySelector('strong')?.textContent || '';
+            const jeton = ligne.querySelector('.dsi-token-value')?.textContent || '';
+            return `${identite}\t${jeton}`;
+        });
+        if (!lignes.length) return;
+
+        const texte = lignes.join('\n');
+        try {
+            if (navigator.clipboard?.writeText) {
+                await navigator.clipboard.writeText(texte);
+            } else {
+                const zone = document.createElement('textarea');
+                zone.value = texte;
+                zone.setAttribute('readonly', 'readonly');
+                zone.className = 'dsi-clipboard-relay';
+                document.body.appendChild(zone);
+                zone.select();
+                document.execCommand('copy');
+                zone.remove();
+            }
+            message('access-token-message', `${lignes.length} jeton(s) copié(s) dans le presse-papiers.`, 'success');
+        } catch (erreur) {
+            message('access-token-message', 'Copie impossible sur ce navigateur : sélectionnez les jetons à la main.', 'error');
+        }
+    }
+
+    /** Referme le panneau des jetons ; leur contenu est perdu pour de bon. */
+    function fermerJetons() {
+        const panneau = el('access-token-panel');
+        if (!panneau) return;
+        panneau.hidden = true;
+        el('access-token-list').innerHTML = '';
+        message('access-token-message', '');
+    }
+
+    // ----------------------------------------------------------------- comptes
+
+    /** Une ligne du tableau des comptes. */
+    function ligneCompte(compte) {
+        const identite = [
+            `<strong>${escapeHtml(compte.identite_libelle)}</strong>`,
+            compte.matricule ? `<br><small>Matricule ${escapeHtml(compte.matricule)}</small>` : '',
+            compte.commentaire ? `<br><small>${escapeHtml(compte.commentaire)}</small>` : '',
+        ].join('');
+
+        const etats = [];
+        if (!compte.actif) etats.push('<span class="dsi-state dsi-state-off">Désactivé</span>');
+        else if (!compte.identite_active) etats.push('<span class="dsi-state dsi-state-off">Identité inactive</span>');
+        else etats.push('<span class="dsi-state dsi-state-on">Actif</span>');
+
+        const connexions = compte.nombre_connexions > 0
+            ? `<br><small>${compte.nombre_connexions} connexion(s)</small>`
+            : '';
+
+        return `
+            <tr data-compte-id="${Number(compte.id_compte)}">
+                <td>${identite}</td>
+                <td>${escapeHtml(LIBELLES_ROLE[compte.role] || compte.role)}</td>
+                <td><code>${escapeHtml(compte.jeton_prefixe)}…</code></td>
+                <td>${formatDateHeure(compte.date_derniere_connexion)}${connexions}</td>
+                <td>${etats.join(' ')}</td>
+                <td class="dsi-actions-cell">
+                    <button type="button" class="button button-secondary access-regenerate">Régénérer</button>
+                    <button type="button" class="button button-secondary access-toggle">${compte.actif ? 'Désactiver' : 'Réactiver'}</button>
+                    <button type="button" class="button button-danger access-delete">Supprimer</button>
+                </td>
+            </tr>`;
+    }
+
+    /**
+     * Remplit les listes de création à partir des identités SANS compte :
+     * proposer un agent qui en a déjà un ne mènerait qu'à un refus du serveur
+     * (un seul compte par identité).
+     */
+    function remplirIdentites(manquants) {
+        const agents = manquants.filter((identite) => identite.role === 'AGENT');
+        const lieux = manquants.filter((identite) => identite.role === 'RESPONSABLE_STRUCTURE');
+
+        const selectAgent = el('access-account-agent');
+        const selectLieu = el('access-account-structure');
+        if (selectAgent) {
+            selectAgent.innerHTML = '<option value="">Choisir un agent sans compte</option>'
+                + agents.map((agent) => `<option value="${Number(agent.id_agent)}">${escapeHtml(agent.libelle)}</option>`).join('');
+        }
+        if (selectLieu) {
+            selectLieu.innerHTML = '<option value="">Choisir un lieu sans compte</option>'
+                + lieux.map((lieu) => `<option value="${Number(lieu.id_structure)}">${escapeHtml(lieu.libelle)}</option>`).join('');
+        }
+
+        const compteur = el('access-missing-count');
+        if (compteur) {
+            compteur.textContent = String(manquants.length);
+            compteur.hidden = manquants.length === 0;
+        }
+        const bouton = el('access-generate-missing');
+        if (bouton) bouton.disabled = manquants.length === 0;
+    }
+
+    /** Recharge la liste des comptes selon les filtres courants. */
+    async function chargerComptes() {
+        const parametres = new URLSearchParams();
+        const role = el('access-filter-role')?.value || '';
+        const etat = el('access-filter-state')?.value || '';
+        const recherche = el('access-filter-search')?.value.trim() || '';
+        if (role) parametres.set('role', role);
+        if (etat !== '') parametres.set('actif', etat);
+        if (recherche) parametres.set('q', recherche);
+
+        message('access-accounts-message', 'Chargement des comptes…');
+        try {
+            const donnees = await api(`api/acces_comptes.php?${parametres.toString()}`);
+            const comptes = donnees.comptes || [];
+            el('access-accounts-body').innerHTML = comptes.length
+                ? comptes.map(ligneCompte).join('')
+                : '<tr><td colspan="6">Aucun compte ne correspond à ces filtres.</td></tr>';
+            remplirIdentites(donnees.manquants || []);
+            message('access-accounts-message', `${comptes.length} compte(s) affiché(s).`, 'success');
+        } catch (erreur) {
+            message('access-accounts-message', erreur.message, 'error');
+        }
+    }
+
+    /** Affiche les seuls champs d'identité utiles au type de compte choisi. */
+    function ajusterFormulaireCompte() {
+        const role = el('access-account-role')?.value || '';
+        const champAgent = el('access-account-agent-field');
+        const champLieu = el('access-account-structure-field');
+        if (!champAgent || !champLieu) return;
+
+        champAgent.hidden = role !== 'AGENT';
+        champLieu.hidden = role !== 'RESPONSABLE_STRUCTURE';
+        el('access-account-agent').required = role === 'AGENT';
+        el('access-account-structure').required = role === 'RESPONSABLE_STRUCTURE';
+
+        const aide = el('access-account-hint');
+        if (aide) aide.textContent = AIDES_ROLE[role] || '';
+    }
+
+    /** Crée un compte, puis affiche son jeton — unique occasion de le lire. */
+    async function creerCompte(evenement) {
+        evenement.preventDefault();
+        const role = el('access-account-role').value;
+
+        try {
+            const donnees = await poster('api/acces_compte_creer.php', {
+                role,
+                agent_id: role === 'AGENT' ? Number(el('access-account-agent').value) : null,
+                structure_id: role === 'RESPONSABLE_STRUCTURE' ? Number(el('access-account-structure').value) : null,
+                commentaire: el('access-account-comment').value,
+            });
+            message('access-account-message', donnees.message, 'success');
+            el('access-account-comment').value = '';
+            afficherJetons([{
+                libelle: donnees.compte?.identite_libelle || '',
+                role: donnees.compte?.role || role,
+                jeton: donnees.jeton,
+            }]);
+            await chargerComptes();
+        } catch (erreur) {
+            message('access-account-message', erreur.message, 'error');
+        }
+    }
+
+    /** Régénération, activation, suppression : délégation sur le tableau. */
+    async function agirSurCompte(evenement) {
+        const ligne = evenement.target.closest('tr[data-compte-id]');
+        if (!ligne) return;
+        const compteId = Number(ligne.dataset.compteId);
+        const titulaire = ligne.querySelector('strong')?.textContent || 'ce compte';
+
+        try {
+            if (evenement.target.closest('.access-regenerate')) {
+                if (!window.confirm(`Régénérer le jeton de ${titulaire} ? L’ancien cessera immédiatement de fonctionner.`)) return;
+                const donnees = await poster('api/acces_compte_jeton.php', { compte_id: compteId });
+                afficherJetons([{
+                    libelle: donnees.compte?.identite_libelle || titulaire,
+                    role: donnees.compte?.role || '',
+                    jeton: donnees.jeton,
+                }]);
+                message('access-accounts-message', donnees.message, 'success');
+            } else if (evenement.target.closest('.access-toggle')) {
+                const desactiver = evenement.target.textContent.trim().startsWith('Dés');
+                const donnees = await poster('api/acces_compte_statut.php', {
+                    compte_id: compteId,
+                    action: desactiver ? 'DESACTIVER' : 'ACTIVER',
+                });
+                message('access-accounts-message', donnees.message, 'success');
+            } else if (evenement.target.closest('.access-delete')) {
+                if (!window.confirm(`Supprimer définitivement le compte de ${titulaire} ? Son jeton cessera de fonctionner ; ses traces dans le journal sont conservées.`)) return;
+                const donnees = await poster('api/acces_compte_statut.php', { compte_id: compteId, action: 'SUPPRIMER' });
+                message('access-accounts-message', donnees.message, 'success');
+            } else {
+                return;
+            }
+            await chargerComptes();
+        } catch (erreur) {
+            message('access-accounts-message', erreur.message, 'error');
+        }
+    }
+
+    /** Équipe d'un coup toutes les identités actives sans compte. */
+    async function genererManquants() {
+        if (!window.confirm('Générer un jeton pour chaque agent et chaque lieu actif qui n’en a pas ? Ils seront affichés une seule fois.')) return;
+        try {
+            const donnees = await poster('api/acces_comptes_manquants.php', {});
+            message('access-accounts-message', donnees.message, 'success');
+            afficherJetons(donnees.jetons || []);
+            await chargerComptes();
+        } catch (erreur) {
+            message('access-accounts-message', erreur.message, 'error');
+        }
+    }
+
+    function init() {
+        // La section n'existe que sur l'écran Administration : ailleurs, le
+        // module se retire sans rien tenter.
+        if (!el('access-accounts-body')) return;
+
+        el('access-account-role')?.addEventListener('change', ajusterFormulaireCompte);
+        el('access-account-form')?.addEventListener('submit', creerCompte);
+        el('access-accounts-body')?.addEventListener('click', agirSurCompte);
+        el('access-accounts-refresh')?.addEventListener('click', chargerComptes);
+        el('access-filter-role')?.addEventListener('change', chargerComptes);
+        el('access-filter-state')?.addEventListener('change', chargerComptes);
+        el('access-generate-missing')?.addEventListener('click', genererManquants);
+        el('access-token-copy')?.addEventListener('click', copierJetons);
+        el('access-token-close')?.addEventListener('click', fermerJetons);
+
+        ajusterFormulaireCompte();
+        chargerComptes();
+    }
+
+    PTA.modules.accessTokens = { init, refresh: chargerComptes };
+})();
diff --git a/assets/js/administration.js b/assets/js/administration.js
index 72807e3..806876e 100644
--- a/assets/js/administration.js
+++ b/assets/js/administration.js
@@ -252,7 +252,10 @@
             <td class="agent-row-phone">${escapeHtml(agent.telephone || 'Non renseigné')}</td>
             <td class="agent-row-contract-start">${escapeHtml(formatContractDate(agent.date_debut_contrat))}</td>
             <td class="agent-row-structure">${escapeHtml(structureLabel)}</td>
-            <td><button type="button" class="button button-secondary edit-agent-profile">Modifier</button></td>
+            <td class="agent-row-actions">
+                <button type="button" class="button button-secondary edit-agent-profile">Modifier</button>
+                <button type="button" class="button button-secondary agent-access-toggle" disabled>Compte d’accès…</button>
+            </td>
         `;
     }
 
@@ -301,6 +304,10 @@
             setAgentRowData(row, agent);
             row.innerHTML = agentRowHtml(agent);
             body.appendChild(row);
+            // L'agent vient de naître : il n'a pas encore de compte d'accès. Le
+            // module le dira sur la ligne, plutôt que d'y laisser un bouton
+            // inerte au libellé provisoire.
+            PTA.modules.agentAccess?.refresh?.();
         }
     }
 
diff --git a/assets/js/agent-access.js b/assets/js/agent-access.js
new file mode 100644
index 0000000..6ce7bd2
--- /dev/null
+++ b/assets/js/agent-access.js
@@ -0,0 +1,158 @@
+/**
+ * Compte d'accès depuis la fiche des agents (`PTA.modules.agentAccess`),
+ * écran manage_agents.php — V7.28.
+ *
+ * Pose sur chaque ligne du tableau des agents un bouton qui COUPE ou RÉTABLIT
+ * l'accès de l'agent à l'application. C'est le geste courant — un départ, un
+ * arrêt long, un retour — là où l'écran Administration porte la distribution des
+ * jetons elle-même.
+ *
+ * CE QUE LE BOUTON NE FAIT PAS : il ne touche ni au jeton (désactiver puis
+ * réactiver rend le MÊME jeton valable), ni à la fiche de l'agent, qui reste
+ * planifiable. Il ne crée pas non plus de compte : un agent qui n'en a pas
+ * encore l'obtient depuis Administration, seul écran qui sache afficher un jeton
+ * fraîchement produit.
+ *
+ * Il réutilise les endpoints de la délégation V7.27 (api/acces_comptes.php et
+ * api/acces_compte_statut.php) : mêmes gardes serveur, même liste blanche de
+ * rôles, même journalisation. Rien de neuf côté droits.
+ *
+ * L'état des comptes N'EST PAS rendu par PHP mais chargé par ce module : le HTML
+ * servi ne porte ainsi aucune information sur les comptes, comme sur l'écran
+ * DSI.
+ */
+(() => {
+    'use strict';
+    const PTA = window.PTA;
+    if (!PTA) return;
+
+    const { readJsonResponse, apiErrorMessage } = PTA.utils;
+
+    const corps = () => document.querySelector('#agent-assignment-body');
+
+    /** Comptes d'accès des agents, indexés par identifiant d'agent. */
+    let comptesParAgent = new Map();
+    let chargement = false;
+
+    function message(texte, type = 'info') {
+        const boite = document.querySelector('#assignment-message');
+        if (!boite) return;
+        boite.className = texte ? `message message-${type}` : 'message';
+        boite.textContent = texte;
+    }
+
+    /** Appel d'API mutualisé : toute réponse non-OK devient une exception. */
+    async function api(url, options = {}) {
+        const reponse = await fetch(url, options);
+        const donnees = await readJsonResponse(reponse);
+        if (!reponse.ok) throw new Error(apiErrorMessage(donnees, 'Opération impossible.'));
+        return donnees;
+    }
+
+    /**
+     * Met un bouton de ligne à l'état du compte correspondant.
+     *
+     * Trois états, et un seul est actionnable :
+     *  - compte actif    → « Couper l'accès » ;
+     *  - compte coupé    → « Rétablir l'accès » ;
+     *  - aucun compte    → bouton inerte, qui dit où en créer un.
+     */
+    function decorerLigne(ligne) {
+        const bouton = ligne.querySelector('.agent-access-toggle');
+        if (!bouton) return;
+
+        const agentId = Number(ligne.dataset.agentId);
+        const compte = comptesParAgent.get(agentId);
+
+        if (!compte) {
+            bouton.disabled = true;
+            bouton.textContent = 'Sans compte d’accès';
+            bouton.title = 'Cet agent n’a pas encore de jeton. Créez son compte depuis l’onglet Administration, section « Jetons d’accès ».';
+            delete bouton.dataset.compteId;
+            delete bouton.dataset.actif;
+            return;
+        }
+
+        bouton.disabled = false;
+        bouton.dataset.compteId = String(compte.id_compte);
+        bouton.dataset.actif = compte.actif ? '1' : '0';
+        bouton.textContent = compte.actif ? 'Couper l’accès' : 'Rétablir l’accès';
+        bouton.title = compte.actif
+            ? 'Désactive le compte : l’agent ne pourra plus se connecter. Son jeton reste valable et resservira au rétablissement.'
+            : 'Réactive le compte : l’agent pourra de nouveau se connecter avec le jeton qu’il détient déjà.';
+        bouton.classList.toggle('button-danger', compte.actif);
+        bouton.classList.toggle('button-secondary', !compte.actif);
+    }
+
+    /** Applique l'état chargé à toutes les lignes présentes. */
+    function decorerToutesLesLignes() {
+        corps()?.querySelectorAll('tr[data-agent-id]').forEach(decorerLigne);
+    }
+
+    /**
+     * Recharge l'état des comptes agents.
+     *
+     * L'échec est SILENCIEUX sur le tableau : les boutons restent inertes avec
+     * leur libellé d'attente, et la page des agents continue de fonctionner. Une
+     * commodité ne doit pas empêcher de consulter ou de modifier une fiche.
+     */
+    async function refresh() {
+        if (!corps() || chargement) return;
+        chargement = true;
+        try {
+            const donnees = await api('api/acces_comptes.php?role=AGENT');
+            comptesParAgent = new Map(
+                (donnees.comptes || [])
+                    .filter((compte) => compte.id_agent !== null)
+                    .map((compte) => [Number(compte.id_agent), compte])
+            );
+            decorerToutesLesLignes();
+        } catch (erreur) {
+            message(`État des comptes d’accès indisponible : ${erreur.message}`, 'warning');
+        } finally {
+            chargement = false;
+        }
+    }
+
+    /** Coupe ou rétablit l'accès de l'agent d'une ligne. */
+    async function basculer(evenement) {
+        const bouton = evenement.target.closest('.agent-access-toggle');
+        if (!bouton || bouton.disabled) return;
+
+        const ligne = bouton.closest('tr[data-agent-id]');
+        const compteId = Number(bouton.dataset.compteId);
+        const actif = bouton.dataset.actif === '1';
+        const titulaire = ligne?.querySelector('.agent-row-name')?.textContent?.trim() || 'cet agent';
+
+        if (actif && !window.confirm(`Couper l’accès de ${titulaire} ? Il ne pourra plus se connecter, et sa session en cours se refermera à sa prochaine action. Son jeton reste valable pour un rétablissement.`)) {
+            return;
+        }
+
+        bouton.disabled = true;
+        try {
+            const donnees = await api('api/acces_compte_statut.php', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    csrf_token: window.PTA_CONFIG.csrfToken,
+                    compte_id: compteId,
+                    action: actif ? 'DESACTIVER' : 'ACTIVER',
+                }),
+            });
+            message(donnees.message, 'success');
+            await refresh();
+        } catch (erreur) {
+            message(erreur.message, 'error');
+            bouton.disabled = false;
+        }
+    }
+
+    function init() {
+        // Le module ne sert que sur l'écran des agents : ailleurs, il se retire.
+        if (!corps()) return;
+        corps().addEventListener('click', basculer);
+        refresh();
+    }
+
+    PTA.modules.agentAccess = { init, refresh };
+})();
diff --git a/assets/js/page-bootstrap.js b/assets/js/page-bootstrap.js
index d717410..2dd836c 100644
--- a/assets/js/page-bootstrap.js
+++ b/assets/js/page-bootstrap.js
@@ -54,7 +54,18 @@
         }
         if (params.agentId && agentSelect) {
             agentSelect.value = String(params.agentId);
-            if (weekInput) weekInput.disabled = false;
+            // Depuis la V7.29, un agent dont le compte d'accès est coupé sort des
+            // listes d'affectation. Un lien profond qui le désigne (file de
+            // validation, tableau de bord, vue annuelle) ne trouve alors aucune
+            // option : sans ce message, l'écran resterait vide sans rien dire.
+            if (agentSelect.value !== String(params.agentId)) {
+                PTA.utils.showMessage(
+                    'Cet agent n’est plus proposé à la saisie : son accès a été coupé. Rétablissez-le depuis l’onglet Agents pour reprendre son planning.',
+                    'warning'
+                );
+            } else if (weekInput) {
+                weekInput.disabled = false;
+            }
         }
         if (params.week && weekInput) {
             weekInput.disabled = !agentSelect?.value;
diff --git a/assets/style.css b/assets/style.css
index 5235d55..2e89aae 100644
--- a/assets/style.css
+++ b/assets/style.css
@@ -3394,3 +3394,17 @@ input.field-invalid {
 input.field-valid {
     border-color: #1b7f3b;
 }
+
+/* ============================================================
+   V7.28 - Actions de ligne sur la fiche des agents
+   ============================================================ */
+.agent-row-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+    align-items: center;
+}
+
+.agent-row-actions .button {
+    white-space: nowrap;
+}
diff --git a/database/migration_v7_9h_jetons_service_enfance.sql b/database/migration_v7_9h_jetons_service_enfance.sql
new file mode 100644
index 0000000..d00db40
--- /dev/null
+++ b/database/migration_v7_9h_jetons_service_enfance.sql
@@ -0,0 +1,56 @@
+-- ============================================================================
+-- PTA V7.27 — Le Service Enfance gère les jetons des agents et des responsables
+-- ============================================================================
+-- La distribution des accès était entièrement portée par la DSI (V7.11). Dans
+-- les faits, c'est le Service Enfance qui sait qu'un agent est arrivé, qu'un
+-- responsable a perdu son jeton ou qu'un remplaçant part : passer par la DSI
+-- pour chaque mouvement de terrain ajoutait un délai sans ajouter de contrôle.
+--
+-- CETTE DÉLÉGATION EST STRICTEMENT BORNÉE À DEUX RÔLES : AGENT et
+-- RESPONSABLE_STRUCTURE. Les comptes SERVICE_ENFANCE et DSI restent à la seule
+-- main de la DSI, et ce n'est pas une commodité d'affichage :
+--   * un compte SERVICE_ENFANCE créé par le Service Enfance serait une
+--     auto-promotion — le rôle se distribuerait lui-même sans contrôle externe ;
+--   * un compte DSI créé par le Service Enfance lui ouvrirait le journal
+--     d'activité, c'est-à-dire la trace de ses propres actions.
+-- La borne est doublée en PHP (AccessAccountController::ROLES_DELEGUES), parce
+-- qu'une frontière de privilège ne doit pas dépendre d'une seule ligne de
+-- données : une ligne mal saisie ici ne doit pas pouvoir ouvrir la création de
+-- comptes privilégiés.
+--
+-- POURQUOI « v7_9h » : les migrations sont jouées dans l'ORDRE ALPHABÉTIQUE
+-- (docker/db/apply-migrations.sh). Le préfixe suit la dernière migration en date
+-- (v7_9g), pas le numéro de version fonctionnelle. Voir CLAUDE.md.
+--
+-- Prérequis : migration_v7_8_securite_acces.sql (tables acces_role_*) et
+--             migration_v7_9e_dsi_comptes_journal.sql (compte_acces, rôle DSI).
+-- Idempotente : rejouable sans effet de bord.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- AUCUNE PAGE NOUVELLE
+-- ----------------------------------------------------------------------------
+-- La gestion des jetons prend place dans l'onglet « Administration », déjà
+-- ouvert au Service Enfance depuis la V7.8 : c'est là que vivent les réglages
+-- qu'on pose une fois, à côté des horaires de couverture. Il n'y a donc rien à
+-- insérer dans acces_role_page — et rien qui puisse ouvrir cet écran à un autre
+-- rôle par mégarde.
+--
+-- ----------------------------------------------------------------------------
+-- LA PERMISSION
+-- ----------------------------------------------------------------------------
+-- `can_manage_field_access` : distribuer les jetons DE TERRAIN (agents et
+-- responsables de lieu). À ne pas confondre avec `can_manage_access`, qui reste
+-- la permission de la DSI et couvre TOUS les comptes, y compris privilégiés.
+--
+-- Les refus sont écrits explicitement plutôt que laissés absents : une ligne à
+-- FALSE documente une décision, une ligne absente laisse croire à un oubli (une
+-- permission inconnue vaut de toute façon « refusé »).
+INSERT INTO acces_role_permission (role, permission, autorise) VALUES
+    ('SERVICE_ENFANCE', 'can_manage_field_access', TRUE),
+    -- La DSI n'en a pas besoin : can_manage_access lui ouvre déjà tous les
+    -- comptes. Lui donner celle-ci n'ajouterait rien et brouillerait la lecture.
+    ('DSI', 'can_manage_field_access', FALSE),
+    ('AGENT', 'can_manage_field_access', FALSE),
+    ('RESPONSABLE_STRUCTURE', 'can_manage_field_access', FALSE)
+ON DUPLICATE KEY UPDATE autorise = VALUES(autorise);
diff --git a/docs/README.md b/docs/README.md
index 04ec58b..6f96208 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,114 +1,1251 @@
-# PTA V6 — application PHP MVC multipage
+# PTA — Planning de Travail Annualisé
 
-PTA n’est plus une SPA. Chaque fonction principale correspond à une page PHP distincte :
+Documentation technique de l'application. Elle s'adresse aux développeurs qui reprennent le projet :
+elle explique ce que fait l'application, comment elle est construite, et documente l'intégralité des
+points d'entrée HTTP.
 
-- `planning.php` : saisie, brouillon, validation et semaines types ;
-- `pending.php` : plannings en attente de validation ;
-- `coverage.php` : contrôle des créneaux sans agent ;
-- `structures.php` : planning hebdomadaire par lieu ;
-- `agents.php` : planning mensuel et bilan par agent ;
-- `vacations.php` : aperçu et enregistrement des vacances scolaires ;
-- `administration.php` : lieux, agents et règles de couverture.
+> Les fichiers `README_V7_*.md` de ce dossier documentent chacun **une version successive** et
+> servent d'historique des décisions. Ce document-ci décrit l'**état courant** du code. En cas de
+> divergence, seul le code fait foi.
 
-`index.php` redirige vers le choix de rôle lors de la première visite, puis vers la page d’accueil autorisée pour le profil sélectionné.
+---
 
-## Architecture
+## Sommaire
 
-```text
-page PHP
-  → PageController
-    → Models / Services
-      → View dédiée
+1. [Ce que fait l'application](#1-ce-que-fait-lapplication)
+2. [Contraintes techniques structurantes](#2-contraintes-techniques-structurantes)
+3. [Démarrage](#3-démarrage)
+4. [Architecture](#4-architecture)
+5. [Rôles, authentification et droits](#5-rôles-authentification-et-droits)
+6. [Journalisation](#6-journalisation)
+7. [Sécurité — contraintes à respecter](#7-sécurité--contraintes-à-respecter)
+8. [JavaScript](#8-javascript)
+9. [Modèle métier](#9-modèle-métier)
+10. [Piège : logique de validation dupliquée](#10-️-piège--logique-de-validation-dupliquée)
+11. [Les pages](#11-les-pages)
+12. [**Référence des endpoints API**](#12-référence-des-endpoints-api)
+    · [Planning](#121-planning--saisie-et-validation)
+    · [Semaines types](#122-semaines-types)
+    · [Agents](#123-agents)
+    · [PDF](#124-pdf)
+    · [Lieux & couverture](#125-lieux-daffectation-et-couverture)
+    · [Annuel & PTA](#126-vue-annuelle-et-pta)
+    · [Équipes](#127-équipes)
+    · [Vacances](#128-vacances-scolaires)
+    · [Tableau de bord](#129-tableau-de-bord-et-recherche-dadresse)
+    · [Comptes délégués](#1210-comptes-daccès-délégués--service-enfance-v727)
+    · [Espace DSI](#1211-espace-dsi--comptes-privilégiés-et-journal-v711)
+13. [Base de données](#13-base-de-données)
+14. [Où chercher quoi](#14-où-chercher-quoi)
+15. [Checklist avant commit](#15-checklist-avant-commit)
+16. [Historique des versions](#16-historique-des-versions)
 
-View
-  → API JSON uniquement pour les actions asynchrones utiles
+---
+
+## 1. Ce que fait l'application
+
+PTA gère la **planification annualisée** des agents d'accueils de loisirs périscolaires et
+extrascolaires d'une collectivité.
+
+Le principe métier : un agent ne travaille pas un nombre d'heures fixe chaque semaine, mais un
+**volume annuel** (1 607 h de référence, proratisé par sa quotité de travail). Les semaines sont
+donc inégales — beaucoup d'heures pendant les vacances scolaires, moins pendant le temps scolaire —
+et l'application sert à composer ces semaines, à vérifier en continu que le cumul reste cohérent
+avec le volume dû, et à valider le résultat.
+
+L'application permet de :
+
+- saisir semaine par semaine les créneaux d'un agent sur un lieu (`planning.php`) ;
+- composer des **semaines types** réutilisables et les appliquer sur toute une période ;
+- suivre le **quota annuel** consommé, mois par mois et sur l'année (`annual.php`, `pta.php`) ;
+- contrôler la **couverture** : les plages horaires d'un lieu où il manque des agents ;
+- faire **valider** les plannings par le Service Enfance, avec des contrôles bloquants ;
+- composer les **équipes** des mercredis et des vacances, avec taux d'encadrement ;
+- importer le calendrier des **vacances scolaires** depuis l'API officielle ;
+- éditer des **PDF** (planning d'agent, planning de lieu, bilan d'heures, contrat horaire) ;
+- administrer les **comptes d'accès** (jetons) et consulter le **journal d'activité**.
+
+---
+
+## 2. Contraintes techniques structurantes
+
+**Aucune dépendance externe.** Pas de Composer, pas de npm, pas de framework, pas de bundler, pas de
+suite de tests. Uniquement **PHP 8.3 + PDO/MariaDB + JavaScript vanilla**. Le générateur PDF
+(`app/Services/SimplePdf.php`) et l'autoloader (`app/autoload.php`) sont volontairement réécrits à
+la main. N'introduisez pas de dépendance sans raison forte.
+
+**Tout est en français** : identifiants SQL (`creneau_horaire`, `id_agent`, `statut`), messages
+utilisateur, commentaires, noms de méthodes métier. Conservez cette langue pour tout nouveau code.
+
+**Pas de routeur.** Chaque URL correspond à un fichier PHP réel de 5 à 10 lignes, à la racine ou
+dans `api/`.
+
+---
+
+## 3. Démarrage
+
+```bash
+cp .env.example .env      # puis renseigner DB_PASSWORD / DB_ROOT_PASSWORD
+docker compose up -d --build
 ```
 
-Les contrôleurs métier, modèles, services PDF et endpoints API de la V5.20 sont conservés. La différence principale porte sur l’interface : plus de routeur JavaScript, plus de vues cachées et plus de chargement de tous les modules sur une seule page.
+L'application est alors sur `http://localhost:8080`, phpMyAdmin sur `http://127.0.0.1:8081`.
 
-## JavaScript chargé par page
+### Services docker-compose
 
-- Saisie : `planning-editor.js` et `week-templates.js` ;
-- À valider : `pending-validation.js` ;
-- Couverture : `coverage.js` ;
-- Par lieu : `structure-overview.js` ;
-- Par agent : `agent-overview.js` ;
-- Vacances : `vacation-calendar.js` ;
-- Administration : `administration.js` et la partie configuration de `coverage.js`.
+| Service      | Rôle |
+|--------------|------|
+| `db`         | MariaDB 11.4. Le schéma `database/pta_prod_schema_mariadb.sql` n'est joué qu'à la **création initiale du volume**. |
+| `db-migrate` | Conteneur jetable qui applique les `database/migration_*.sql` à chaque démarrage. |
+| `php`        | php-fpm 8.3. **Attend la sortie en succès de `db-migrate`** : une migration en échec empêche l'application de tourner sur une base incomplète. |
+| `nginx`      | Sert les pages PHP et les assets statiques. Publié sur `APP_PORT`. |
+| `phpmyadmin` | N'écoute que sur `127.0.0.1` et exige un identifiant MariaDB. |
 
-`assets/js/page-bootstrap.js` initialise uniquement les modules déclarés par la page et applique les filtres transmis dans l’URL.
+### ⚠️ Le code est COPIÉ dans l'image, pas monté
 
-## Liens directs
+Toute modification PHP/JS/CSS exige un rebuild des **deux** services — nginx sert lui-même les
+assets statiques depuis sa propre copie de `/var/www/html` :
+
+```bash
+docker compose up -d --build php nginx
+```
+
+### Commandes utiles
+
+```bash
+docker compose logs -f php nginx db
+docker compose logs db-migrate       # compte rendu de l'application des migrations
+docker compose exec db mariadb -upta -p pta
+docker compose down                  # arrêt en conservant les données
+docker compose down -v               # DÉTRUIT le volume MariaDB
+
+# Vérification syntaxique (il n'existe ni linter ni tests automatisés)
+find . -name '*.php' -not -path './.git/*' -exec php -l {} \;
+```
+
+### Après une installation neuve
+
+1. Se connecter avec le **jeton DSI d'installation** `PTA-INSTALLATION-DSI`, écrit en clair dans
+   `database/migration_v7_9e_dsi_comptes_journal.sql` — il est donc **public**.
+2. Le régénérer immédiatement depuis la page « Accès & journaux ». L'écran alerte tant que ce n'est
+   pas fait.
+3. Générer les jetons manquants pour équiper les agents et les responsables de lieu.
+4. Changer le mot de passe MariaDB du `.env`, encore à sa valeur d'exemple.
+
+### Migrations
+
+Les fichiers `database/migration_*.sql` sont appliqués automatiquement par `db-migrate`
+(`docker/db/apply-migrations.sh`), sur base neuve comme sur base existante. Le script tient un
+registre `schema_migration` (fichier + empreinte MD5) : un fichier déjà appliqué et inchangé est
+ignoré, un fichier modifié est **rejoué**.
+
+Deux règles :
+
+- **Toute migration doit être idempotente** : `CREATE TABLE IF NOT EXISTS`,
+  `CREATE OR REPLACE VIEW`, `INSERT … ON DUPLICATE KEY UPDATE`.
+- **Les fichiers sont pris dans l'ordre alphabétique.** Nommer une migration `migration_v7_10_…` la
+  ferait passer *avant* `migration_v7_9_…`. C'est pourquoi les migrations récentes suivent le
+  préfixe de la précédente (`…_v7_9e_`, `…_v7_9f_`, `…_v7_9g_`, `…_v7_9h_`) et non le numéro de
+  version fonctionnelle.
+
+> `PTA_DB_PORT`, `DB_PORT` et `PMA_PORT` du compose sont les ports joints **à l'intérieur** du
+> réseau Docker, où MariaDB écoute sur 3306. Ce ne sont pas les ports publiés sur l'hôte
+> (`APP_PORT`, `PMA_PORT` de `.env`) : les modifier coupe l'accès à la base.
+
+---
+
+## 4. Architecture
+
+### 4.1 Arborescence
+
+```
+/                          points d'entrée « pages » (planning.php, agents.php, …)
+├── api/                   points d'entrée JSON et PDF
+├── app/
+│   ├── autoload.php       autoloader PSR-4 maison
+│   ├── bootstrap.php      session + PDO + contrôle de schéma + journal
+│   ├── Controllers/       logique applicative, gardes, validation
+│   ├── Core/              Access, Csrf, Journal, JsonResponse, Request, Security, Session…
+│   ├── Models/            SQL PDO uniquement, aucune règle d'accès
+│   ├── Services/          appels d'API externes et génération PDF
+│   └── Views/
+│       ├── layouts/       header.php (nav) et footer.php (injection JS)
+│       ├── pages/         une vue par page
+│       └── partials/      markup réutilisable
+├── assets/                style.css et js/ (une IIFE par module)
+├── database/              schéma initial + migrations
+├── docker/                Dockerfiles, conf nginx, script de migration
+└── docs/                  cette documentation
+```
+
+### 4.2 Deux types de points d'entrée
+
+**Pages HTML** — fichiers à la racine :
+
+```php
+require __DIR__ . '/page_bootstrap.php';
+runPage('planning');   // -> PageController::planning()
+```
+
+`page_bootstrap.php` attrape tout `Throwable` et rend une page d'erreur HTML autonome ; le détail
+technique reste journalisé côté serveur par `Security::reportThrowable()`.
+
+**Endpoints JSON/PDF** — `api/*.php`, plus `save_planning.php`, `validate_planning.php` et
+`reopen_planning.php` restés à la racine pour raisons historiques :
+
+```php
+JsonResponse::bootstrap();                       // handlers d'erreur -> JSON, jamais du HTML
+$pdo = require dirname(__DIR__) . '/app/bootstrap.php';
+(new PlanningController($pdo))->show();
+```
+
+`JsonResponse::bootstrap()` convertit warnings et exceptions en réponses JSON 500 — indispensable,
+car le JS refuse toute réponse non-JSON. **Les endpoints PDF ne l'appellent pas** : ils émettent des
+octets binaires via `PdfResponse::inline()` et sortent leurs erreurs en texte brut.
+
+### 4.3 Chaîne d'un appel
+
+```
+api/x.php  → Controller (Access + Csrf + Request) → Model (SQL PDO) → JsonResponse::send()
+page.php   → PageController → Models → Views/pages/x.php
+                                        ├── layouts/header.php   (nav filtrée par rôle)
+                                        ├── partials/x.php       (markup)
+                                        └── layouts/footer.php   (window.PTA_CONFIG + scripts)
+```
+
+`app/bootstrap.php` démarre la session, ouvre le PDO (`db.php` ← `config.php` ← variables
+d'environnement `PTA_DB_*`), appelle `SchemaModel::assertCurrent()` **à chaque requête** et pose la
+connexion du journal.
+
+> **Ajouter une table ou une colonne obligatoire impose de mettre à jour les listes de
+> `SchemaModel`**, sinon l'application entière refuse de démarrer — ou, pire, démarre sans le
+> contrôle.
+
+### 4.4 Ajouter un endpoint
+
+1. Créer le fichier mince dans `api/` (voir modèle ci-dessus).
+2. Ajouter la méthode au contrôleur, avec **dans cet ordre** :
+   garde `Access` → `Request::requireMethod('POST')` → `Request::json()` →
+   `Csrf::assertPayload($payload)` → validation → modèle → `Journal::ecriture()` →
+   `JsonResponse::send()`.
+
+### 4.5 Ajouter une page
+
+1. Fichier PHP à la racine (`require page_bootstrap.php` + `runPage('cle')`).
+2. Méthode dans `PageController` — **son nom EST la clé de page** utilisée par `acces_role_page`
+   (d'où `manage_agents()` en snake_case, à rebours du reste du projet).
+3. Vue `app/Views/pages/cle.php` + partiel `app/Views/partials/cle.php`.
+4. Module JS, déclaré dans les tableaux `scripts` / `modules` de la méthode.
+5. Inscription de la clé dans `$navigation` **et** dans un groupe de `$navigationGroups`
+   (`app/Views/layouts/header.php`).
+6. **Migration SQL** insérant la ligne dans `acces_role_page` : les pages autorisées sont lues en
+   base, pas écrites en PHP.
+
+Une page absente des groupes reste affichée dans un groupe « Autres » : ce filet évite qu'un oubli
+la rende inatteignable.
+
+**Seule exception assumée : `faq`** (guide d'utilisation) est volontairement absente de
+`$navigation` et rendue par le bloc `.view-tab-help` ancré à droite de la barre. L'omettre de
+`$navigation` est ce qui l'empêche d'être aussi repêchée par « Autres » et d'apparaître deux fois.
+Elle reste soumise à `acces_role_page` (`migration_v7_9d_faq.sql`).
+
+---
+
+## 5. Rôles, authentification et droits
+
+### 5.1 Les quatre rôles
+
+| Rôle | Périmètre |
+|------|-----------|
+| `AGENT` | Lecture seule sur son propre planning. |
+| `RESPONSABLE_STRUCTURE` | Édition des brouillons de **son seul lieu**. |
+| `SERVICE_ENFANCE` | Tout le métier ; **seul habilité à valider**. Distribue les jetons de terrain. |
+| `DSI` | Administration technique : comptes d'accès et journal. **Aucun droit métier.** |
+
+### 5.2 Authentification par jeton (V7.11)
+
+`role.php` n'est **pas** un sélecteur de rôle. Une session ne peut naître que de
+`Access::openSession()`, appelée après vérification d'un jeton par `CompteModel::authentifier()`.
+Le rôle, l'agent et le lieu sont **lus sur le compte**, jamais déclarés par l'utilisateur. La base ne
+conserve qu'une empreinte SHA-256 du jeton.
+
+`Access::select()` a disparu — **ne pas le réintroduire.**
+
+### 5.3 Second facteur pour les comptes privilégiés (V7.12)
+
+Les comptes `SERVICE_ENFANCE` et `DSI` exigent, après le jeton, un **mot de passe** choisi par le
+titulaire à sa première connexion et haché par `password_hash()`. Entre les deux étapes, la session
+ne porte qu'une attente horodatée de cinq minutes : **un jeton validé sans mot de passe n'ouvre
+rien.**
+
+La règle « qui doit avoir un mot de passe » est portée par la vue
+(`v_acces_compte.mot_de_passe_requis`), pas par du PHP. La DSI peut **effacer** un mot de passe,
+jamais en **poser** un — sans quoi elle connaîtrait celui de tout le monde.
+
+Un frein anti-force-brute compte les échecs récents via `JournalModel::echecsRecents()` :
+10 échecs sur 15 minutes bloquent. **Renommer les actions `JETON_REFUSE` ou `MOT_DE_PASSE_REFUSE`
+désarmerait ce frein silencieusement.**
+
+### 5.4 Délégation des jetons de terrain (V7.27)
+
+Le Service Enfance distribue lui-même les jetons des rôles `AGENT` et `RESPONSABLE_STRUCTURE`,
+depuis l'onglet « Administration » (`AccessAccountController`, `api/acces_*.php`).
+
+**La délégation s'arrête à ces deux rôles** : un compte `SERVICE_ENFANCE` créé par le Service
+Enfance serait une auto-promotion, un compte `DSI` lui ouvrirait le journal de ses propres actions.
+La borne est posée **des deux côtés** — `AccessAccountController::ROLES_DELEGUES` en PHP,
+`can_manage_field_access` en base — et ne doit être élargie ni d'un côté ni de l'autre. La DSI reste
+seule sur les comptes privilégiés, les mots de passe et le journal.
+
+### 5.5 Relecture du compte à chaque requête
+
+`Access` relit le compte à **chaque requête** (`v_acces_compte`, filtrée sur `actif` et
+`identite_active`) : c'est ce qui fait qu'un jeton révoqué, un agent désactivé ou un lieu fermé
+referment la session en cours. **Ne pas mettre ce résultat en cache entre deux requêtes.**
+
+### 5.6 Les droits vivent en SQL, pas en PHP
+
+**`Access.php` ne contient aucune règle de droit.** Tout est lu dans les vues créées par
+`database/migration_v7_8_securite_acces.sql` :
+
+`v_acces_role_page`, `v_acces_role_permission`, `v_acces_identite_agent`,
+`v_acces_identite_structure`, `v_acces_agent_par_structure`, `v_acces_perimetre_creneau`,
+`v_acces_perimetre_planning` — plus `v_acces_compte`, `v_acces_compte_manquant` et
+`v_journal_activite` (V7.11).
+
+Modifier un droit se fait **en SQL** dans `acces_role_page` / `acces_role_permission`, sans
+redéploiement. **Une permission absente de la base vaut « refusé ».**
+
+`SchemaModel` vérifie au démarrage la présence des dix vues et fait échouer l'application si une
+migration manque — c'est volontairement **fail-closed**, et `docker/db/apply-migrations.sh` refait le
+même contrôle au déploiement.
+
+Permissions actuelles :
+
+| Permission | Ce qu'elle ouvre |
+|------------|------------------|
+| `read_only` | Marque un rôle en lecture seule (AGENT). |
+| `can_edit_draft` | Éditer les brouillons — garde `requireDraftEditor()`. |
+| `can_edit_cross_structure` | Sortir du périmètre d'un seul lieu. |
+| `can_validate` | Valider un planning. |
+| `can_reopen` | Repasser un planning validé en brouillon. |
+| `can_view_pending` | Voir la file d'attente de validation. |
+| `can_use_templates` | Semaines types (conditionne aussi le chargement des scripts). |
+| `can_copy_full_week` | Recopier une semaine entière d'un agent. |
+| `can_forecast_next_year` | Projeter sur l'année suivante. |
+| `can_manage_agents` | Référentiel des agents. |
+| `can_manage_structures` | Référentiel des lieux. |
+| `can_manage_coverage` | Règles de couverture. |
+| `can_manage_teams` | Équipes des mercredis et vacances. |
+| `can_manage_vacations` | Calendrier des vacances scolaires. |
+| `can_manage_pta` | Contraintes et souhaits du PTA. |
+| `can_manage_access` | Comptes d'accès, tous rôles (DSI). |
+| `can_manage_field_access` | Comptes d'accès **de terrain uniquement** (Service Enfance, V7.27). |
+| `can_read_journal` | Journal d'activité (DSI). |
+
+### 5.7 Les gardes de contrôleur
+
+Les contrôles sont **doublés** : l'UI masque, mais le serveur tranche. Toute méthode de contrôleur
+commence par un garde. Ces gardes émettent directement un 401/403 JSON et **coupent l'exécution** —
+l'appelant n'a donc pas à tester leur retour.
+
+| Garde | Ce qu'il vérifie |
+|-------|------------------|
+| `requirePage($cle)` | Page autorisée pour le rôle (`acces_role_page`). Pages HTML uniquement. |
+| `requireRoles([…])` | Appartenance à une liste de rôles. |
+| `requireService()` | Rôle `SERVICE_ENFANCE`. |
+| `requireDsi()` | Rôle `DSI`. |
+| `requireDraftEditor()` | Permission `can_edit_draft`. |
+| `requireStructureView($id)` | Droit de **consulter** ce lieu. |
+| `requireStructureEdit($id)` | Droit d'**éditer** ce lieu (un responsable est borné au sien). |
+| `requireAgentView($id)` | Droit de consulter cet agent (un AGENT est borné à lui-même). |
+| `requireEntryEdit($id)` | Droit d'éditer ce créneau (`v_acces_perimetre_creneau`). |
+| `requirePlanningEdit($id)` | Droit d'éditer ce planning (`v_acces_perimetre_planning`). |
+
+**Ne jamais ajouter un endpoint mutant sans garde ni sans `Csrf::assertPayload($payload)`.**
+
+### 5.8 CSRF
+
+Le jeton voyage **dans le corps JSON** (`csrf_token`), pas dans un en-tête — ce choix évite la
+requête préliminaire CORS et garde les appels `fetch()` identiques d'un module à l'autre.
+
+```js
+csrf_token: window.PTA_CONFIG.csrfToken
+```
+
+Il vit aussi longtemps que la session : il n'est pas renouvelé à chaque requête, sans quoi deux
+onglets ouverts s'invalideraient l'un l'autre. La comparaison passe par `hash_equals()`.
+
+`role.php` fait exception et vérifie son CSRF à la main : les données y arrivent en formulaire
+classique et un échec doit produire une page HTML, pas du JSON.
+
+---
+
+## 6. Journalisation
+
+`App\Core\Journal` écrit dans `journal_activite`. Sa connexion PDO est posée une fois par
+`app/bootstrap.php` — les appelants n'ont rien à transporter :
+
+```php
+Journal::ecriture('PLANNING_VALIDE', 'planning', $planningId, 'Planning validé pour…', [contexte]);
+```
+
+Cinq catégories : `CONNEXION`, `ECRITURE`, `ACCES_REFUSE`, `ADMINISTRATION`, `SYSTEME`.
+
+**Trois règles :**
+
+1. **Tout endpoint mutant doit journaliser son succès**, après l'écriture en base et avant le
+   `JsonResponse::send()` — au même titre qu'il porte un garde et un `Csrf::assertPayload()`.
+2. **Les lectures ne sont jamais journalisées** (choix de volume). Les refus le sont, et `Access`
+   comme `Csrf` s'en chargent déjà — inutile de les doubler dans les contrôleurs.
+3. **Le journal ne doit jamais faire échouer l'action** : `Journal` avale ses propres erreurs. Ne pas
+   entourer un appel de logique qui pourrait lever.
+
+Actions existantes (extrait) : `CONNEXION_REUSSIE`, `JETON_REFUSE`, `MOT_DE_PASSE_REFUSE`,
+`CONNEXION_BLOQUEE`, `DECONNEXION`, `COMPTE_CREE`, `JETON_REGENERE`, `JETONS_GENERES_EN_LOT`,
+`MOT_DE_PASSE_REINITIALISE`, `JOURNAL_PURGE`, `PLANNING_ENREGISTRE`, `PLANNING_VALIDE`,
+`PLANNING_ROUVERT`, `CRENEAU_MODIFIE`, `CRENEAU_SUPPRIME`, `SEMAINE_COPIEE`,
+`SEMAINE_TYPE_APPLIQUEE_PERIODE`, `AGENT_CREE`, `AGENT_MODIFIE`, `STRUCTURE_CREEE`,
+`COUVERTURE_ENREGISTREE`, `VACANCES_ENREGISTREES`, `EQUIPE_CREEE`, `CSRF_INVALIDE`,
+`ROLE_HORS_PERIMETRE`, `COMPTE_HORS_PERIMETRE`.
+
+---
+
+## 7. Sécurité — contraintes à respecter
+
+- **CSP à nonce** (`app/Core/Security.php`) : `script-src 'self' 'nonce-…'`, sans `unsafe-inline`.
+  Tout `<script>` inline ajouté à une vue **doit** porter `nonce="<?= $cspNonce ?>"`. Aucun
+  `onclick=` ni `style=` inline ne fonctionnera.
+- **`PTA.utils.escapeHtml` échappe aussi les guillemets** et vaut donc en contexte texte comme en
+  contexte attribut. **Ne pas la réimplémenter localement** : une variante incomplète avait
+  introduit un XSS stocké.
+- **Ordre des blocs nginx** : nginx retient la première regex correspondante. Tout nouveau refus doit
+  être placé **avant** `location ~ \.php$`, sinon il est sans effet. Sont déjà refusés : `/app/`,
+  `/database/`, `/docker/`, les fichiers d'amorçage (`config.php`, `db.php`, `page_bootstrap.php`),
+  les `README*` et les extensions `.env .sql .ini .log .bak .dump .yml .yaml .md`. Ces règles doivent
+  suivre toute réorganisation de l'arborescence.
+- **`PTA_DEBUG` reste à `0`.** Les détails d'exception passent par `Security::reportThrowable()`, qui
+  journalise côté serveur et ne renvoie rien au client.
+- **`session_start()` ne doit jamais être appelé directement** : passer par `App\Core\Session::start()`.
+- **Ne jamais redéfinir `PMA_USER` / `PMA_PASSWORD`** dans le compose : cela rouvre phpMyAdmin sans
+  mot de passe.
+
+---
+
+## 8. JavaScript
+
+Pas de bundler, pas de module ES. Chaque fichier est une **IIFE** qui lit le global `window.PTA`
+publié par `core.js` (`config`, `elements`, `state`, `shared`, `utils`, `modules`) et s'enregistre :
+
+```js
+PTA.modules.agentOverview = { init, load };
+```
+
+**Ordre de chargement imposé** : `core.js` d'abord (il publie `window.PTA`), puis les modules de la
+page, puis `page-bootstrap.js` en dernier (il appelle leurs `init()`).
+
+`PageController` décide quels scripts et quels modules charger (tableaux `scripts` / `modules`),
+`footer.php` les injecte avec deux globales :
+
+- `window.PTA_CONFIG` — jeton CSRF, profil d'accès, permissions, référentiel des motifs (valable
+  pour toute l'application) ;
+- `window.PTA_PAGE_CONFIG` — modules à initialiser et paramètres d'URL déjà assainis.
+
+`page-bootstrap.js` applique ensuite les filtres d'URL (`structure_id`, `agent_id`, `week`, `month`,
+`focus`). Les modules se rafraîchissent entre eux via l'appel optionnel
+`PTA.modules.autre?.refresh?.({ silent: true })`.
+
+### ⚠️ Versionnage manuel des assets
+
+Les assets sont versionnés à la main : `assets/style.css?v=7.29` et `assets/js/*.js?v=7.29`.
+**Bumper ce numéro aux trois endroits après toute modification de JS/CSS :**
+
+1. `app/Views/layouts/header.php`
+2. `app/Views/layouts/footer.php`
+3. `app/Views/pages/role.php` — qui porte sa propre balise `<head>`
+
+Sinon les navigateurs et le `expires 7d` de nginx servent l'ancienne version.
+
+### Modules disponibles
+
+| Fichier | Module | Pages |
+|---------|--------|-------|
+| `core.js` | *(socle)* | toutes |
+| `page-bootstrap.js` | *(amorçage)* | toutes |
+| `dashboard.js` | `dashboard` | `dashboard` |
+| `planning-editor.js` | `planning` | `planning` |
+| `week-templates.js`, `week-template-editor.js` | `weekTemplates`, `weekTemplateEditor` | `planning`, si `can_use_templates` |
+| `pending-validation.js` | `pendingValidation` | `pending` |
+| `coverage.js` | `coverage` | `coverage`, `administration` |
+| `structure-overview.js` | `structureOverview` | `structures` |
+| `agent-overview.js` | `agentOverview` | `agents` |
+| `annual-overview.js` | `annualOverview` | `annual` |
+| `pta.js` | `pta` | `pta` |
+| `teams.js` | `teams` | `teams` |
+| `vacation-calendar.js` | `vacationCalendar` | `vacations` |
+| `administration.js` | `administration` | `manage_agents`, `manage_structures` |
+| `address-autocomplete.js`, `field-format.js` | `addressAutocomplete`, `fieldFormat` | `manage_agents` |
+| `agent-access.js` | `agentAccess` | `manage_agents` |
+| `access-tokens.js` | `accessTokens` | `administration` |
+| `dsi.js` | `dsi` | `dsi` |
+
+---
+
+## 9. Modèle métier
+
+### 9.1 Le quota annuel
+
+- Il suit l'**année civile** (01/01 → 31/12), **jamais** l'année scolaire ni la date de contrat.
+- 1 607 h de référence, proratisées par la quotité (`QuotaModel::REFERENCE_MINUTES`).
+- Les 1 607 h sont un volume **NET de travail effectif** :
+  `365 − 104 (week-ends) − 25 (congés payés) − 8 (jours fériés) = 228 j × 7 h = 1 596 h`,
+  arrondies à 1 600 h, plus les 7 h de la journée de solidarité.
+
+> **Congés payés et jours fériés sont donc DÉJÀ retranchés.** Leur imputer des heures de quota les
+> décompterait une seconde fois. Une tentative de décompter un forfait de 7 h par jour de CP a été
+> introduite puis annulée pour cette raison — **ne pas la réintroduire.**
+
+### 9.2 Les objets
+
+- Un **planning** = un agent × une semaine ISO × un lieu, statut `BROUILLON` ou `VALIDE`.
+- Il contient des **créneaux** (`creneau_horaire`) porteurs d'un **motif** (`motif_planning`). Le
+  flag `compte_dans_quota` du motif décide de l'imputation : `CONGE`, `AUTRE_ABSENCE` et `JNT` ne
+  comptent pas.
+- Une **semaine type** (`modele_semaine_agent` / `modele_semaine_creneau`) appartient à **un agent**
+  et décrit un lundi→vendredi générique. **Ce n'est pas un planning** : rien n'est planifié tant
+  qu'elle n'est pas appliquée à une semaine ou dupliquée sur une période. Elle se compose soit à
+  partir d'une semaine réellement planifiée (`saveFromWeek()`), soit directement dans l'éditeur
+  (`saveFromEntries()`) — les deux passent par `persistTemplate()`.
+- Un agent peut être planifié sur **plusieurs lieux la même semaine** ; `id_structure` sur l'agent
+  n'est qu'un rattachement par défaut. D'où les contrôles de chevauchement inter-structures.
+- Les **vacances scolaires** (`periode_vacance`) déterminent le contexte périscolaire /
+  extrascolaire ; elles sont importées depuis l'API publique data.education.gouv.fr via
+  `SchoolHolidayApiService` (le conteneur php a donc besoin d'un **accès sortant**).
+
+### 9.3 Dates de contrat (V7.15)
+
+**Un agent n'est planifiable qu'entre ses dates de contrat** (`date_debut_contrat` /
+`date_fin_contrat`). La règle vaut pour **tous les motifs, congés compris** : hors contrat, il n'y a
+rien à décompter. Une borne absente ouvre — pas de date de fin signifie CDI.
+
+Elle est appliquée :
+- à l'écriture — `assertDatesWithinContract()` dans `PlanningController` **et**
+  `WeekTemplateController` ;
+- au contrôle de validation — code `HORS_CONTRAT` ;
+- à l'inverse, sur la fiche agent : raccourcir un contrat sous des affectations existantes est
+  refusé.
+
+> **Toute nouvelle voie d'écriture de créneaux doit poser la même garde.**
+
+### 9.4 Comptes d'accès et listes d'affectation (V7.29)
+
+Un **compte d'accès coupé retire l'agent des listes d'AFFECTATION** : sélecteur de la saisie
+(`AgentModel::listForLocation()`) et composition des équipes (`allSelectable()`).
+
+Un agent **sans compte** reste proposé — c'est l'état normal avant distribution des jetons, le
+filtrer viderait les listes d'une installation neuve. Les écrans de consultation et le référentiel
+« Agents » continuent de le montrer : c'est de là qu'on lui rétablit son accès.
+`allActive()` reste la liste non filtrée ; **ne pas confondre les deux.**
+
+### 9.5 Les deux modes de `planning.php`
+
+Deux modes **exclusifs** : l'éditeur de semaine type (ouvert par défaut) et la saisie semaine par
+semaine. Le second reste la cible de tous les liens profonds — dès que l'URL porte `week` ou `focus`,
+`page-bootstrap.js` bascule dessus, sinon un utilisateur venant corriger un planning identifié
+atterrirait dans l'éditeur de modèles.
+
+---
+
+## 10. ⚠️ Piège : logique de validation dupliquée
+
+`database/pta_prod_schema_mariadb.sql` définit des vues (`v_suivi_quota_annuel`,
+`v_plannings_en_attente_validation`, `v_pta_annuel_synthese`, `v_equipe_pta_controle`,
+`v_planning_agent_semaine`) et des procédures (`sp_controler_planning`, `sp_valider_planning`) —
+**aucune n'est appelée par le code PHP.**
+
+Les contrôles réellement appliqués vivent dans `PlanningController::validate()`,
+`AnnualOverviewController::validateYear()` et `PtaModel`. Modifier une règle métier impose de traiter
+**le PHP** ; le SQL correspondant est du patrimoine à ne pas prendre pour la source de vérité.
+
+### Forme des contrôles renvoyés au client
+
+```json
+{ "niveau": "ERREUR|ALERTE|INFO", "code": "…", "message": "…" }
+```
+
+| Niveau | Effet | Code HTTP |
+|--------|-------|-----------|
+| `ERREUR` | Bloque, rien n'est validé | 422 |
+| `ALERTE` | Demande une confirmation explicite | 409, à rappeler avec `force_quota: true` |
+| `INFO` | Informatif | 200 |
+
+Codes de validation d'un planning :
+
+- `AUCUN_CRENEAU` (ERREUR) — planning vide ;
+- `CRENEAU_HORS_SEMAINE` (ERREUR) — créneau hors des bornes de la semaine ;
+- `CHEVAUCHEMENT_INTERNE` (ERREUR) — deux créneaux du planning se recouvrent ;
+- `HORS_CONTRAT` (ERREUR) — affectation hors des dates de contrat ;
+- `CHEVAUCHEMENT_AUTRE_STRUCTURE` (ERREUR) — recouvrement avec un créneau **déjà validé** sur un
+  autre lieu. *Seuls les plannings validés sont opposables : un brouillon concurrent peut encore
+  être corrigé, le bloquer empêcherait toute validation dans un ordre donné.*
+- `QUOTA_DEPASSE` (ALERTE) — le dépassement est une décision de gestion, pas une anomalie technique.
+
+Tous les contrôles sont **collectés avant de trancher**, afin que l'utilisateur voie l'ensemble des
+problèmes d'un coup plutôt qu'un par requête.
+
+---
+
+## 11. Les pages
+
+| Clé | Fichier | Titre | Rôles typiques |
+|-----|---------|-------|----------------|
+| `dashboard` | `dashboard.php` | Tableau de bord | Service Enfance (accueil de ce rôle) |
+| `planning` | `planning.php` | Saisie | Responsable, Service Enfance |
+| `pending` | `pending.php` | À valider | Service Enfance |
+| `coverage` | `coverage.php` | Couverture | Responsable, Service Enfance |
+| `structures` | `structures.php` | Par lieu | tous sauf DSI |
+| `agents` | `agents.php` | Par agent / **Mon planning** | tous sauf DSI |
+| `annual` | `annual.php` | Vue annuelle | Service Enfance |
+| `pta` | `pta.php` | PTA détaillé | Service Enfance |
+| `teams` | `teams.php` | Équipes | Service Enfance |
+| `vacations` | `vacations.php` | Vacances | Service Enfance |
+| `manage_agents` | `manage_agents.php` | Agents | Service Enfance |
+| `manage_structures` | `manage_structures.php` | Lieux d'affectation | Service Enfance |
+| `administration` | `administration.php` | Administration (couverture + jetons de terrain) | Service Enfance |
+| `dsi` | `dsi.php` | Accès & journaux | DSI |
+| `faq` | `faq.php` | Guide d'utilisation | les trois rôles métier, pas la DSI (hors `$navigation`) |
+| — | `role.php` | Connexion par jeton | anonyme |
+| — | `index.php` | Aiguillage vers `Access::homeUrl()` ou `role.php` | — |
+
+Groupes de navigation : **Piloter** (`dashboard`, `pending`, `coverage`) · **Planifier**
+(`planning`, `teams`) · **Consulter** (`agents`, `structures`, `annual`, `pta`) · **Management**
+(`manage_agents`, `manage_structures`) · **Paramétrer** (`vacations`, `administration`, `dsi`).
+
+> `Access::homeUrl()` se replie sur `planning.php` si `dashboard` n'est pas autorisé (migration non
+> jouée). **Ce repli est indispensable** : sans lui, `requirePage()` renverrait indéfiniment vers une
+> page interdite.
+
+### Liens profonds
 
 Une page de contrôle peut ouvrir directement le planning concerné :
 
-```text
+```
 planning.php?structure_id=2&agent_id=7&week=2026-W31&focus=validation
 ```
 
-## Installation
+Paramètres reconnus par `page-bootstrap.js` : `structure_id`, `agent_id`, `week`, `month`, `year`,
+`date`, `date_debut`, `date_fin`, `compte_id`, `focus`, `notice`.
 
-1. Configurer `config.php`.
-2. Utiliser le schéma SQL correspondant à la V5.20.
-3. Placer le dossier sur le serveur PHP.
-4. Ouvrir `index.php` ou `planning.php`.
+---
 
-Aucune migration SQL supplémentaire n’est nécessaire pour passer de la V5.20 à la V6.
+## 12. Référence des endpoints API
 
-## Version 7
+### Conventions communes
 
-Voir `README_V7.md` pour le nouveau socle PTA annuel, les équipes des mercredis/vacances et les contrôles métier associés.
+- **Verbe** : les lectures sont en `GET` (paramètres en query string), les écritures en `POST`
+  (corps JSON). Deux endpoints acceptent les deux verbes, signalés ci-dessous.
+- **Corps** : `Content-Type: application/json`. Toute charge utile mutante porte `csrf_token`.
+- **Réponse** : JSON `UTF-8`, avec `X-Content-Type-Options: nosniff` et `Cache-Control: no-store`
+  (les réponses dépendent du rôle en session : jamais de cache partagé).
+- **Endpoints PDF** : sortent des octets binaires via `PdfResponse::inline()`, et leurs erreurs en
+  **texte brut** avec un code HTTP — jamais en JSON.
 
-## V7.2 — Vue annuelle
+#### Codes de retour
 
-La page `annual.php` reproduit l’esprit du tableau annuel historique : douze mois côte à côte, codes AP/PP/AE/PE, couleurs métier, vacances scolaires et accès direct à la semaine à corriger. Voir `README_V7_2.md`.
+| Code | Signification |
+|------|---------------|
+| 200 | Succès |
+| 201 | Ressource créée |
+| 400 | Paramètres de requête absents ou mal formés |
+| 401 / 403 | Session absente, rôle insuffisant, hors périmètre, ou CSRF invalide |
+| 404 | Ressource introuvable — ou hors périmètre, quand le révéler renseignerait |
+| 405 | Verbe HTTP non autorisé |
+| 409 | Conflit : doublon, chevauchement, ou **ALERTE** demandant confirmation |
+| 422 | Charge utile invalide, ou **ERREUR** de validation métier |
+| 500 | Erreur serveur (détail journalisé, jamais renvoyé sauf `PTA_DEBUG=1`) |
+| 502 | Un service externe (BAN, data.education.gouv.fr) n'a pas répondu |
 
+Exemple d'appel mutant :
 
-## V7.8 — Sécurité et droits en base
+```js
+const reponse = await fetch('save_planning.php', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        structure_id: 2,
+        agent_id: 7,
+        week: '2026-W31',
+        entries: [{ date: '2026-07-27', start: '08:00', end: '12:00', motif_id: 1 }],
+        csrf_token: window.PTA_CONFIG.csrfToken,
+    }),
+});
+```
 
-Les correctifs de sécurité et le déplacement de la matrice des droits dans des
-vues SQL sont décrits dans `README_V7_8.md`. La migration
-`database/migration_v7_8_securite_acces.sql` est obligatoire ; elle est appliquée
-automatiquement au déploiement par le service `db-migrate` du docker-compose.
+---
 
-## V7.4 — Rôles et droits d’accès
+### 12.1 Planning — saisie et validation
 
-La première arrivée ouvre `role.php`. Les droits Agent, Responsable de structure et Service Enfance sont vérifiés dans les pages et les contrôleurs API. Voir `README_V7_4.md`.
+| Endpoint | Verbe | Contrôleur | Garde |
+|----------|-------|-----------|-------|
+| `api/planning.php` | GET | `PlanningController::show` | `requireDraftEditor` + `requireStructureEdit` |
+| `save_planning.php` | POST | `PlanningController::save` | `requireDraftEditor` + `requireStructureEdit` |
+| `api/update_agent_entry.php` | POST | `PlanningController::updateAgentEntry` | `requireDraftEditor` + `requireEntryEdit` + `requireStructureEdit` |
+| `api/delete_agent_entry.php` | POST | `PlanningController::deleteAgentEntry` | `requireDraftEditor` + `requireEntryEdit` |
+| `api/move_or_duplicate_entry.php` | POST | `PlanningController::moveOrDuplicateEntry` | `requireDraftEditor` + `requireEntryEdit` |
+| `api/copy_agent_week.php` | POST | `PlanningController::copyAgentWeek` | `requireService` |
+| `api/pending_plannings.php` | GET | `PlanningController::pendingValidation` | `requireService` |
+| `validate_planning.php` | POST | `PlanningController::validate` | `requireService` |
+| `reopen_planning.php` | POST | `PlanningController::reopen` | `requireDraftEditor` + `requirePlanningEdit` |
 
-## V7.11 — Connexion par jeton, espace DSI et journal d’activité
+**`GET api/planning.php`** — état complet d'une semaine de saisie.
+Paramètres : `structure_id`, `agent_id`, `week` (`2026-W08`).
+Renvoie le planning et ses créneaux, mais aussi les créneaux de l'agent sur les **autres lieux** la
+même semaine (`other_entries`) : l'éditeur doit les afficher en lecture seule pour rendre les
+chevauchements visibles avant l'échec.
 
-`role.php` n’est plus un sélecteur de rôle : chaque utilisateur se connecte avec un jeton personnel
-distribué par la DSI, dont la base ne conserve qu’une empreinte SHA-256. Un quatrième rôle `DSI`
-ouvre `dsi.php` : gestion des comptes d’accès (dont les administrateurs Service Enfance) et lecture
-du journal d’activité, qui trace les connexions, les écritures en base et les refus d’accès. La
-migration `database/migration_v7_9e_dsi_comptes_journal.sql` est obligatoire ; elle crée aussi le
-compte DSI d’installation dont le jeton, public, est à régénérer immédiatement. Voir
-`README_V7_11.md`.
+**`POST save_planning.php`** — enregistre le brouillon d'une semaine.
+Charge utile : `structure_id`, `agent_id`, `week`, `entries[]`, `csrf_token`.
+La charge utile **remplace intégralement** les créneaux de la semaine : une liste `entries` vide est
+un cas nominal (« tout supprimer »), pas une erreur.
+Ordre des contrôles, du moins coûteux au plus coûteux et du plus explicite au plus générique :
+① droits et périmètre → ② motifs fermés à l'agent → ③ normalisation ligne à ligne →
+④ chevauchements internes → ⑤ chevauchements avec les autres lieux.
 
-## V7.12 — Mot de passe des comptes privilégiés
+**`POST api/update_agent_entry.php`** — modifie un créneau depuis la fiche agent.
+Charge utile : `entry_id`, `structure_id`, `motif_id`, `date`, `start`, `end`, `csrf_token`.
+Un créneau peut appartenir à un planning déjà `VALIDE` : le modèle le repasse alors automatiquement
+en `BROUILLON`, d'où le drapeau **`requires_revalidation`** dans la réponse.
 
-Les comptes Service Enfance et DSI ajoutent un second facteur à leur jeton : un mot de passe choisi
-par leur titulaire à sa première connexion, que la DSI ne peut qu’effacer, jamais lire. Les agents et
-les responsables de lieu restent à un seul facteur. Migration
-`database/migration_v7_9f_mot_de_passe_admin.sql`. Voir `README_V7_12.md`.
+**`POST api/delete_agent_entry.php`** — supprime un créneau depuis la fiche agent.
+Charge utile : `entry_id`, `csrf_token`.
+Peut également rouvrir un planning validé. Le planning **n'est jamais supprimé** même s'il devient
+vide : `planning_empty` permet à l'interface de le signaler, mais l'enregistrement conserve son
+historique.
 
-## V7.13 — Nom et prénom modifiables
+**`POST api/move_or_duplicate_entry.php`** — glisser-déposer d'un créneau.
+Charge utile : `entry_id`, `target_date`, `action` (`move` | `duplicate`), `csrf_token`.
+`duplicate` correspond au glisser avec Ctrl. Déposer un créneau sur son jour d'origine n'est pas une
+erreur : le modèle renvoie l'action `none`.
 
-La fiche agent laisse désormais corriger le nom et le prénom, à côté des autres champs déjà
-modifiables. Le matricule et la quotité de travail restent immuables. Un renommage est journalisé
-avec l’identité précédente. Aucune migration. Voir `README_V7_13.md`.
+**`POST api/copy_agent_week.php`** — recopie une semaine entière d'un agent.
+Charge utile : `agent_id`, `source_week`, `target_week`, `mode` (`merge` | `replace`), `csrf_token`.
+Réservé au Service Enfance et **non aux responsables** : la copie porte sur tous les lieux de l'agent
+sur la semaine source, elle déborde donc par nature du périmètre d'un responsable.
 
-## V7.14 — Groupe de navigation « Management »
+**`GET api/pending_plannings.php`** — file d'attente de validation (alimente `pending.php`).
+Les totaux distinguent les minutes saisies (`total_minutes`) des minutes réellement décomptées du
+quota (`counted_minutes`).
 
-Les agents et les lieux d’affectation quittent l’onglet « Administration » pour deux onglets
-distincts, réunis dans un groupe « Management » de la barre de navigation, au même titre que
-« Piloter » ou « Planifier ». « Administration » ne conserve que les horaires de couverture.
-Migration `database/migration_v7_9g_management.sql` (droits d’accès aux deux pages). Voir
-`README_V7_14.md`.
+**`POST validate_planning.php`** — contrôle puis valide un planning.
+Charge utile : `planning_id`, `force_quota` (bool), `csrf_token`.
+**C'est ici que vivent les règles de validation réellement appliquées** — voir §10 pour la liste des
+codes et les trois issues (422 / 409 / 200).
 
-## V7.15 — Affectations bornées par le contrat
+**`POST reopen_planning.php`** — repasse un planning `VALIDE` en `BROUILLON`.
+Charge utile : `planning_id`, `csrf_token`.
+Réouverture volontaire, à distinguer de la réouverture automatique déclenchée par la modification
+d'un créneau. Le modèle applique un `UPDATE` conditionné au statut : un retour à zéro ligne signifie
+qu'un autre utilisateur est passé entre-temps → **409**, plutôt qu'un succès trompeur.
 
-Un agent ne peut plus être planifié avant sa date de début de contrat ni après sa date de fin, quel
-que soit le chemin d’écriture (saisie, déplacement, copie de semaine, semaine type). La validation
-signale les affectations devenues hors contrat, et raccourcir un contrat sous des affectations
-existantes est refusé. Aucune migration. Voir `README_V7_15.md`.
+---
+
+### 12.2 Semaines types
+
+Tous ces endpoints exigent `requireService`.
+
+| Endpoint | Verbe | Méthode |
+|----------|-------|---------|
+| `api/week_templates.php` | GET | `WeekTemplateController::index` |
+| `api/week_template.php` | GET | `WeekTemplateController::show` |
+| `api/save_week_template_entries.php` | POST | `WeekTemplateController::storeEntries` |
+| `api/save_week_template.php` | POST | `WeekTemplateController::store` |
+| `api/apply_week_template.php` | POST | `WeekTemplateController::apply` |
+| `api/preview_week_template_period.php` | POST | `WeekTemplateController::previewPeriod` |
+| `api/apply_week_template_period.php` | POST | `WeekTemplateController::applyPeriod` |
+| `api/delete_week_template.php` | POST | `WeekTemplateController::destroy` |
+
+**`GET api/week_templates.php`** — liste des semaines types d'un agent. Paramètre : `agent_id`.
+Ne renvoie que des **compteurs**, pas le contenu : la liste sert à choisir, `show()` sert à ouvrir.
+
+**`GET api/week_template.php`** — contenu détaillé. Paramètres : `template_id`, `agent_id`.
+Le modèle est retrouvé par **le couple** (`template_id`, `agent_id`) et non par le seul
+identifiant : c'est ce qui empêche de lire le modèle d'un autre agent en changeant l'URL.
+Les drapeaux `structure_active` et `motif_actif` sont conservés bien que toujours vrais à la
+création : un lieu ou un motif peut être désactivé **après** l'enregistrement, et l'éditeur doit le
+signaler plutôt que d'échouer à l'application.
+
+**`POST api/save_week_template_entries.php`** — enregistre un modèle composé directement dans
+l'éditeur. Charge utile : `agent_id`, `name`, `entries[]`, `replace` (bool), `csrf_token`.
+Les listes de motifs et de lieux autorisés sont calculées **dans le contrôleur** puis transmises au
+modèle : celui-ci ne connaît pas les règles d'accès et se contente de rejeter ce qui n'est pas dans
+les listes reçues.
+
+**`POST api/save_week_template.php`** — capture une semaine planifiée en modèle.
+Charge utile : `agent_id`, `week`, `name`, `replace` (bool), `csrf_token`.
+
+**`POST api/apply_week_template.php`** — applique un modèle à **une** semaine.
+Charge utile : `template_id`, `agent_id`, `week`, `mode` (`merge` | `replace`), `csrf_token`.
+Appliquer sur une semaine validée la repasse en brouillon (`requires_revalidation`).
+
+**`POST api/preview_week_template_period.php`** — simulation **sans écriture**.
+Charge utile : `template_id`, `agent_id`, `start_date`, `end_date`, `mode`, `period_filter`,
+`csrf_token`.
+**Étape obligatoire dans l'interface avant `applyPeriod()`** : une application sur période touche des
+dizaines de semaines et peut rouvrir des plannings validés. L'utilisateur doit voir le volume avant
+de confirmer.
+`period_filter` restreint le périmètre au calendrier scolaire :
+`all` → toutes les semaines · `school` → semaines scolaires (périscolaire) ·
+`extra` → vacances scolaires (extrascolaire).
+
+**`POST api/apply_week_template_period.php`** — même charge utile, avec écriture.
+Le message de retour est volontairement détaillé (créés / ignorés / remplacés / rouverts) :
+l'opération est massive et difficile à annuler à la main. Les quotas sont renvoyés **indexés par date
+de début de période** — une application à cheval sur deux années civiles touche **deux** quotas
+annuels distincts, et l'interface doit rafraîchir les deux.
+
+**`POST api/delete_week_template.php`** — supprime une semaine type.
+Charge utile : `template_id`, `agent_id`, `csrf_token`.
+La suppression est filtrée par `agent_id` ; un modèle appartenant à un autre agent ressort en **404
+plutôt qu'en 403**, pour ne pas révéler son existence. Les créneaux **déjà appliqués ne sont pas
+touchés** : le modèle est un patron, pas un lien vivant vers les plannings produits.
+
+---
+
+### 12.3 Agents
+
+| Endpoint | Verbe | Méthode | Garde |
+|----------|-------|---------|-------|
+| `api/agents.php` | GET | `AgentController::listForPlanning` | `requireDraftEditor` + `requireStructureEdit` |
+| `api/agent_overview.php` | GET | `AgentController::overview` | `requireAgentView` |
+| `api/agent_month_overview.php` | GET | `AgentController::monthOverview` | `requireAgentView` |
+| `api/agent_assignments.php` | GET / POST | `AgentController::assignments` | `requireService` |
+| `api/create_agent.php` | POST | `AgentController::create` | `requireService` |
+| `api/update_agent.php` | POST | `AgentController::updateProfile` | `requireService` |
+
+**`GET api/agents.php`** — agents sélectionnables dans l'éditeur. Paramètre : `structure_id`.
+`structure_id` à 0 (ou absent) signifie « tous les lieux » : ce n'est licite que pour le Service
+Enfance, un responsable étant renvoyé en 403 par `requireStructureEdit()` dès qu'il vise un autre
+lieu que le sien.
+
+**`GET api/agent_overview.php`** — semaine d'un agent, **tous lieux confondus**.
+Paramètres : `agent_id`, `week`.
+Vue transverse par agent (et non par lieu comme `api/planning.php`) : c'est la seule qui donne la
+charge réelle d'un agent planifié à plusieurs endroits. En lecture seule pour le rôle `AGENT`.
+
+**`GET api/agent_month_overview.php`** — grille mensuelle. Paramètres : `agent_id`, `month`
+(`2026-02`).
+La grille est **alignée sur les semaines ISO** : elle commence au lundi de la semaine du 1er du mois
+et finit au vendredi de la semaine du dernier jour. Elle déborde donc du mois, et le drapeau
+`in_month` de chaque jour permet de griser les débordements. *Sans cet alignement, une semaine serait
+coupée en deux et les cumuls hebdomadaires affichés seraient faux.* Les créneaux sont chargés sur
+toute l'étendue de la grille, débordements compris.
+
+**`api/agent_assignments.php`** — rattachement principal d'un agent. **Endpoint à double verbe** :
+GET liste les agents (`allActive()`), POST modifie un rattachement.
+Charge utile (POST) : `agent_id`, `structure_id` (nullable), `csrf_token`.
+Un `structure_id` nul est **valide** : il détache l'agent de tout lieu par défaut, sans l'empêcher
+d'être planifié ponctuellement ailleurs.
+
+**`POST api/create_agent.php`** — création d'un agent.
+Charge utile : `matricule`, `nom`, `prenom`, `id_poste`, `type_contrat`, `structure_id`,
+`quotite_travail`, `date_debut_contrat`, `date_fin_contrat`, `email`, `telephone`, `adresse`,
+`est_diplome`, `diplome_libelle`, `droit_enveloppe_formation`, `commentaire_pta`, `csrf_token`.
+Les contrôles vont au-delà du « non vide » : poste existant en base, type de contrat dans
+l'énumération, dates cohérentes entre elles, quotité dans ]0 ; 100], longueurs alignées sur les
+colonnes SQL (une chaîne trop longue serait sinon **tronquée silencieusement** par MariaDB), et
+unicité du matricule (**409**, pas 422 : c'est un conflit avec l'existant, pas une saisie malformée).
+La réponse renvoie l'agent complet reconstitué, pour insertion dans la liste sans rechargement.
+
+**`POST api/update_agent.php`** — modification de la fiche.
+Mêmes contrôles que `create()`, **deux champs exceptés, jamais modifiables** :
+
+- le **matricule** : c'est la clé de rapprochement avec les outils RH ;
+- la **quotité de travail** : elle détermine le quota annuel déjà consommé, la changer en cours
+  d'année fausserait rétroactivement tous les suivis.
+
+Le nom et le prénom, **eux**, sont modifiables (V7.13) : mariage, divorce, ou faute de frappe. Un
+renommage est journalisé avec l'identité précédente. Raccourcir un contrat sous des affectations
+existantes est **refusé** (422).
+
+---
+
+### 12.4 PDF
+
+| Endpoint | Méthode | Garde | Paramètres |
+|----------|---------|-------|-----------|
+| `api/agent_planning_pdf.php` | `AgentController::pdf` | `requireAgentView` | `agent_id`, `week`, `weeks` |
+| `api/agent_time_summary_pdf.php` | `AgentController::timeSummaryPdf` | `requireAgentView` | `agent_id`, `date` **ou** `year` |
+| `api/agent_hours_contract_pdf.php` | `AgentController::hoursContractPdf` | `requireAgentView` | `agent_id`, `date` **ou** `year` |
+| `api/structure_planning_pdf.php` | `StructureController::pdf` | `requireStructureView` | `structure_id`, `week` |
+
+Tous en `GET`. Ils **n'appellent pas `JsonResponse::bootstrap()`** et sortent leurs erreurs en texte
+brut.
+
+**`api/agent_planning_pdf.php`** — planning d'un agent sur plusieurs semaines.
+`weeks` n'accepte que **6 ou 7** (7 par défaut) : au-delà, la grille ne tient plus sur une page A4
+paysage et `SimplePdf` ne gère pas le report de tableau sur page suivante.
+
+**`api/agent_time_summary_pdf.php`** — bilan annuel d'heures, ventilé par motif.
+La période couverte **n'est pas choisie par l'appelant** : c'est celle calculée par `QuotaModel`
+(année civile 01/01 → 31/12). Le paramètre `year` n'est qu'un raccourci vers le 1er janvier
+correspondant.
+
+**`api/agent_hours_contract_pdf.php`** — contrat horaire annuel. Document contractuel : il n'affiche
+que le volume annualisé dû, **sans le détail des créneaux planifiés**.
+
+**`api/structure_planning_pdf.php`** — planning d'un lieu.
+Reprend **volontairement** le calcul de `StructureController::overview()` plutôt que de le
+factoriser : les deux méthodes doivent rester alignées, toute évolution de l'une appelle la même dans
+l'autre.
+
+---
+
+### 12.5 Lieux d'affectation et couverture
+
+| Endpoint | Verbe | Méthode | Garde |
+|----------|-------|---------|-------|
+| `api/structure_overview.php` | GET | `StructureController::overview` | `requireStructureView` |
+| `api/create_structure.php` | POST | `StructureController::create` | `requireService` |
+| `api/update_structure.php` | POST | `StructureController::updateType` | `requireService` |
+| `api/coverage_alerts.php` | GET | `CoverageController::alerts` | `requireRoles([RESPONSABLE, SERVICE])` |
+| `api/structure_coverage_rules.php` | GET | `CoverageController::rules` | `requireService` |
+| `api/save_structure_coverage_rules.php` | POST | `CoverageController::saveRules` | `requireService` |
+
+**`GET api/structure_overview.php`** — semaine d'un lieu, agent par agent.
+Paramètres : `structure_id`, `week`.
+La liste d'agents **ne se limite pas** aux agents rattachés au lieu : elle inclut ceux qui y sont
+ponctuellement planifiés, distingués par le drapeau `lieu_principal`. *Un agent peut travailler sur
+plusieurs lieux la même semaine, et l'omettre donnerait une vue fausse de l'effectif présent.* Les
+créneaux sont indexés par agent en PHP (une seule lecture, puis regroupement en mémoire) plutôt que
+par une requête par agent.
+
+**`POST api/create_structure.php`** — création d'un lieu.
+Charge utile : `code`, `nom`, `adresse`, `type_affectation`, `csrf_token`.
+Le code est normalisé avant contrôle (espaces → underscores, puis majuscules). Il sert d'identifiant
+lisible (nom de fichier PDF, exports), d'où le format restreint à `[A-Z0-9_-]{2,50}`. Un doublon
+ressort en **409**. `type_affectation` (`PERISCOLAIRE` | `EXTRASCOLAIRE`) détermine le contexte par
+défaut du lieu ; il reste croisé avec le calendrier des vacances.
+
+**`POST api/update_structure.php`** — change le type d'un lieu.
+Charge utile : `structure_id`, `type_affectation`, `csrf_token`.
+**Seul le type est modifiable** : le code sert de référence stable, et le nom n'est pas exposé à
+l'édition dans cette version.
+
+**`GET api/coverage_alerts.php`** — trous de couverture d'une semaine.
+Paramètres : `week`, `structure_id` (facultatif — sans lui, balaie **tous** les lieux actifs).
+Pour un responsable, le `structure_id` demandé est **ignoré et écrasé** par son propre lieu : un
+simple 403 l'empêcherait de consulter son écran depuis une URL partagée.
+Trois familles de retours, **à ne pas confondre** :
+
+- `alerts` — plages réellement sous-couvertes ;
+- `validation_warnings` — couverture assurée par des plannings **encore en brouillon**, donc pas
+  encore fiable ;
+- `unconfigured_structures` — lieux sans aucune règle. Ils ne peuvent pas produire d'alerte, et les
+  taire les ferait passer pour conformes.
+
+**`GET api/structure_coverage_rules.php`** — règles d'un lieu. Paramètre : `structure_id`.
+
+**`POST api/save_structure_coverage_rules.php`** — **remplace intégralement** les règles d'un lieu.
+Charge utile : `structure_id`, `rules[]`, `csrf_token`.
+La liste reçue devient l'unique jeu de règles ; une liste **vide supprime toute règle** (le lieu
+redevient « non configuré »). Il n'y a pas d'ajout ni de suppression unitaire.
+Les règles sont validées **dans le contrôleur** — jour ouvré, horaires au quart d'heure, fin après
+début, minimum dans [1, 50], puis absence de chevauchement — avant d'être confiées au modèle, qui
+n'effectue aucun contrôle métier.
+
+---
+
+### 12.6 Vue annuelle et PTA
+
+Tous ces endpoints exigent `requireService`.
+
+| Endpoint | Verbe | Méthode |
+|----------|-------|---------|
+| `api/annual_overview.php` | GET | `AnnualOverviewController::overview` |
+| `api/annual_validate.php` | POST | `AnnualOverviewController::validateYear` |
+| `api/pta_summary.php` | GET | `PtaController::summary` |
+| `api/pta_constraint.php` | POST | `PtaController::constraint` |
+| `api/pta_wish.php` | POST | `PtaController::wish` |
+
+**`GET api/annual_overview.php`** — répartition de l'année d'un agent.
+Paramètres : `agent_id`, `year` (facultatif, borné à [2000, 2100], retombe sur l'année en cours).
+
+**`POST api/annual_validate.php`** — contrôle puis validation de **toute l'année** en une opération.
+Charge utile : `agent_id`, `year`, `force_quota` (bool), `csrf_token`.
+**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 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é, rappeler 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.
+
+**`GET api/pta_summary.php`** — synthèse du PTA d'un agent à une date donnée.
+Paramètres : `agent_id`, `date` (facultative, `AAAA-MM-JJ`, défaut aujourd'hui).
+La date sert de **point d'observation** : elle détermine la période de quota retenue et les
+contraintes en vigueur ce jour-là.
+
+**`POST api/pta_constraint.php`** — enregistre ou supprime une contrainte prioritaire.
+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` /
+`interdit_midi` / `interdit_soir`.
+Deux types seulement, volontairement fermés : `MEDICALE` et `TEMPS_PARTIEL_THERAPEUTIQUE`. Une date
+de fin vide signifie « sans terme connu ». 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.
+
+**`POST api/pta_wish.php`** — enregistre ou supprime un souhait de lieu.
+Charge utile : `action` (`SAVE` | `DELETE`), `agent_id`, `csrf_token`, puis `wish_id`, ou
+`structure_id` / `type_souhait` / `priorite` / `distance_km` / `commentaire`.
+Deux types : `PREFERENCE` et `INTERDICTION`. La priorité (1 à 5) ordonne plusieurs préférences entre
+elles ; la distance en kilomètres sert à arbitrer les affectations éloignées.
+
+---
+
+### 12.7 Équipes
+
+Tous ces endpoints exigent `requireService`.
+
+**`api/teams.php`** — **endpoint à double verbe**.
+GET : liste, avec `date_debut` / `date_fin` facultatifs pour ne montrer que les équipes actives sur
+une période.
+POST (`TeamController::index`) : création. Charge utile : `structure_id`, `type_equipe`, `libelle`,
+`date_debut`, `date_fin`, `nombre_enfants_moins_6`, `nombre_enfants_6_plus`, `ratio_moins_6`,
+`ratio_6_plus`, `minimum_agents`, `pourcentage_diplomes_min`, `csrf_token`.
+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, et un ratio à zéro provoquerait une division par zéro
+au calcul du taux d'encadrement.
+
+**`POST api/team_members.php`** (`TeamController::member`) — ajoute ou retire un agent.
+Charge utile : `action` (`ADD` par défaut | `REMOVE`), `team_id`, `agent_id`, `fonction_equipe`,
+`commentaire`, `csrf_token`.
+Trois fonctions : `RESPONSABLE`, `ANIMATION`, `RESTAURATION_ENTRETIEN` — elles conditionnent le
+calcul du taux d'encadrement. L'exception d'ajout ressort en **422 avec son propre message** : le
+modèle y place les refus métier lisibles (agent déjà membre, par exemple), destinés à l'utilisateur.
+
+**`POST api/team_status.php`** (`TeamController::status`) — fait avancer une équipe dans son cycle de
+vie. Charge utile : `team_id`, `statut` (`BROUILLON` | `A_CONTROLER` | `VALIDEE`), `csrf_token`.
+**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.
+
+---
+
+### 12.8 Vacances scolaires
+
+Tous ces endpoints exigent `requireService`.
+
+**`GET api/vacation_periods.php`** (`VacationController::index`) — périodes enregistrées.
+Paramètre : `school_year` (facultatif, `2026-2027`).
+
+**`GET api/preview_school_holidays.php`** (`VacationController::preview`) — propositions de l'API
+officielle, **sans aucune écriture en base**. Paramètres : `academy`, `year` (année civile).
+Le **502** (et non 500) en cas d'échec dit ce qui s'est passé : c'est le service distant qui n'a pas
+répondu, pas PTA qui a échoué. *Le conteneur php a besoin d'un accès réseau sortant.*
+Les `warnings` signalent les périodes que le service n'a pas su interpréter ; elles sont montrées à
+l'utilisateur plutôt que tues.
+
+**`POST api/save_vacation_periods.php`** (`VacationController::save`) — enregistre les périodes
+retenues. Charge utile : `periods[]`, `csrf_token`.
+Plafond de **50 périodes** par envoi : large excédent d'une année scolaire complète, il borne le coût
+d'un envoi malformé ou répété. Les libellés, académies et zones sont tronqués avec les fonctions
+`mb_*` aux longueurs des colonnes — *une troncature en octets couperait un caractère accentué en deux
+et produirait de l'UTF-8 invalide en base*. `source` distingue `MANUEL` de `DATA_GOUV` ; une valeur
+inconnue retombe sur `MANUEL` au lieu de faire échouer l'enregistrement.
+
+**`POST api/delete_vacation_period.php`** (`VacationController::delete`) — supprime une période.
+Charge utile : `period_id`, `csrf_token`.
+Aucun contrôle d'usage : supprimer une période change le contexte scolaire/extrascolaire des journées
+concernées, **mais ne touche aucun créneau déjà planifié**.
+
+---
+
+### 12.9 Tableau de bord et recherche d'adresse
+
+**`GET api/dashboard_summary.php`** (`DashboardController::summary`, `requireService`).
+Paramètres : `scope`, `week`, `year` (tous facultatifs).
+Deux portées, **à ne pas confondre** :
+
+- `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 (paramètre absent) — les quatre blocs de l'écran, soit plusieurs dizaines de
+  requêtes, acceptable **uniquement** sur le tableau de bord lui-même.
+
+**`GET api/search_address.php`** (`AddressController::search`, `requireService`) — propositions
+d'adresses via la Base Adresse Nationale. Paramètres : `q` (saisie en cours), `limit` (facultatif,
+1 à 8). Le garde est celui de l'écriture des fiches agent : c'est le seul rôle qui saisit une
+adresse.
+
+---
+
+### 12.10 Comptes d'accès délégués — Service Enfance (V7.27)
+
+Tous ces endpoints exigent `requireService` **et** vérifient que le compte visé relève des
+`ROLES_DELEGUES` (`AGENT`, `RESPONSABLE_STRUCTURE`). Un compte hors périmètre ressort en **403** et
+le refus est journalisé (`COMPTE_HORS_PERIMETRE` / `ROLE_HORS_PERIMETRE`).
+
+**`GET api/acces_comptes.php`** (`comptes`) — comptes de terrain et identités sans compte.
+Paramètres : `role` (dans la liste déléguée), `actif`, `q`.
+
+**`POST api/acces_compte_creer.php`** (`creerCompte`) — crée un compte de terrain et **renvoie son
+jeton en clair**. Charge utile : `role`, `agent_id`, `structure_id`, `commentaire`, `csrf_token`.
+Le libellé **n'est pas saisi** : pour ces deux rôles il est toujours déduit de l'identité (nom de
+l'agent, nom du lieu) par `CompteModel`. *Un titulaire ne peut donc pas être maquillé sous un autre
+nom dans la liste.*
+
+**`POST api/acces_compte_jeton.php`** (`regenererJeton`) — régénère le jeton d'un compte de terrain.
+Charge utile : `compte_id`, `csrf_token`.
+C'est la procédure du jeton perdu comme du jeton compromis : **l'ancien cesse immédiatement de
+fonctionner.**
+
+**`POST api/acces_compte_statut.php`** (`changerStatutCompte`) — active, désactive ou supprime.
+Charge utile : `compte_id`, `action` (`ACTIVER` | `DESACTIVER` | `SUPPRIMER`), `csrf_token`.
+La suppression efface le compte **mais pas ses traces** : le journal conserve le libellé figé de
+l'acteur.
+
+**`POST api/acces_comptes_manquants.php`** (`genererJetonsManquants`) — équipe d'un coup toutes les
+identités actives sans compte. Charge utile : `csrf_token`.
+Sans danger d'élargissement : `v_acces_compte_manquant` ne connaît que des agents et des lieux,
+jamais un compte privilégié. **La réponse porte tous les jetons produits, en clair — seule occasion
+de les lire.**
+
+---
+
+### 12.11 Espace DSI — comptes privilégiés et journal (V7.11)
+
+Tous ces endpoints exigent `requireDsi`.
+
+**`GET api/dsi_comptes.php`** (`comptes`) — comptes d'accès et identités sans compte.
+Paramètres : `role`, `actif`, `q`.
+
+**`POST api/dsi_compte_creer.php`** (`creerCompte`) — crée un compte, **tous rôles**, et renvoie son
+jeton. Charge utile : `role`, `agent_id`, `structure_id`, `libelle`, `commentaire`, `csrf_token`.
+
+**`POST api/dsi_compte_jeton.php`** (`regenererJeton`) — régénère un jeton.
+Charge utile : `compte_id`, `csrf_token`.
+
+**`POST api/dsi_compte_mot_de_passe.php`** (`reinitialiserMotDePasse`) — **efface** le mot de passe
+d'un compte privilégié. Charge utile : `compte_id`, `csrf_token`.
+La DSI ne **remplace** pas le mot de passe, elle le **retire** : le titulaire en choisira un nouveau
+à sa prochaine connexion, avec son jeton. *C'est ce qui garantit que personne d'autre que lui ne l'a
+jamais connu — y compris la personne qui vient de le réinitialiser.*
+
+**`POST api/dsi_compte_statut.php`** (`changerStatutCompte`) — active, désactive ou supprime.
+Charge utile : `compte_id`, `action`, `csrf_token`.
+Refuse (422) de désactiver ou supprimer **le compte avec lequel on est connecté**. La suppression
+conserve les traces du journal (clé étrangère en `ON DELETE SET NULL`).
+
+**`POST api/dsi_comptes_manquants.php`** (`genererJetonsManquants`) — **outil de mise en service** :
+à l'installation, aucun agent ni responsable n'a de jeton, donc personne ne peut entrer.
+Charge utile : `csrf_token`. La réponse porte tous les jetons produits **en clair** — seule occasion
+de les lire, faite pour être imprimée ou copiée avant de refermer l'écran.
+
+**`GET api/dsi_journal.php`** (`journal`) — recherche paginée dans le journal.
+Paramètres : `categorie`, `resultat`, `role`, `id_compte`, `q`, `du`, `au`, `page`, `taille`.
+
+**`POST api/dsi_journal_purge.php`** (`purgerJournal`) — supprime les entrées les plus anciennes.
+Charge utile : `jours` (**minimum 30**), `csrf_token`.
+La purge est elle-même journalisée, et l'est **après** coup : sa propre trace ne peut donc pas être
+emportée par la purge qu'elle décrit.
+
+---
+
+## 13. Base de données
+
+### Tables du socle métier
+
+`structure` · `poste_agent` · `agent` · `agent_structure` · `tranche_age` · `structure_capacite` ·
+`structure_couverture_horaire` · `structure_creneau_reference` · `motif_planning` ·
+`quota_agent_annuel` · `pta_annuel` · `semaine` · `planning` · `creneau_horaire` ·
+`modele_semaine_agent` · `modele_semaine_creneau` · `periode_vacance` · `agent_structure_souhait` ·
+`agent_contrainte` · `equipe_pta` · `equipe_pta_membre`
+
+### Tables ajoutées par migration
+
+`compte_acces` (V7.11) · `journal_activite` (V7.11) · `acces_role_page` (V7.8) ·
+`acces_role_permission` (V7.8) · `schema_migration` (registre du script de migration)
+
+### Migrations, dans l'ordre d'application
+
+| Fichier | Apport |
+|---------|--------|
+| `migration_v7_8_securite_acces.sql` | Matrice des droits en vues SQL (V7.8) |
+| `migration_v7_9_tableau_de_bord.sql` | Page `dashboard` (V7.9) |
+| `migration_v7_9b_droit_enveloppe_formation.sql` | Colonne `droit_enveloppe_formation` |
+| `migration_v7_9c_retrait_formation_repartition.sql` | Retrait de la formation de la répartition |
+| `migration_v7_9d_faq.sql` | Page `faq` pour les trois rôles |
+| `migration_v7_9e_dsi_comptes_journal.sql` | Rôle DSI, `compte_acces`, `journal_activite` (V7.11) |
+| `migration_v7_9f_mot_de_passe_admin.sql` | Second facteur des comptes privilégiés (V7.12) |
+| `migration_v7_9g_management.sql` | Pages `manage_agents` / `manage_structures` (V7.14) |
+| `migration_v7_9h_jetons_service_enfance.sql` | `can_manage_field_access` (V7.27) |
+
+> Rappel : **ordre alphabétique**, pas ordre de version. Nommer une nouvelle migration en suivant le
+> préfixe de la dernière en date (`migration_v7_9i_…`), jamais le numéro de version fonctionnelle.
+
+---
+
+## 14. Où chercher quoi
+
+| Besoin | Fichier |
+|--------|---------|
+| Règles de validation d'un planning | `app/Controllers/PlanningController::validate()` |
+| Validation annuelle | `app/Controllers/AnnualOverviewController::validateYear()` |
+| Calcul du quota | `app/Models/QuotaModel.php` |
+| Contrôle des rôles et périmètres | `app/Core/Access.php` (+ vues SQL de la V7.8) |
+| Authentification, jetons, mots de passe | `app/Controllers/RoleController.php`, `app/Models/CompteModel.php` |
+| Traces d'activité | `app/Core/Journal.php`, `app/Models/JournalModel.php` |
+| En-têtes de sécurité et CSP | `app/Core/Security.php` |
+| Génération PDF | `app/Services/SimplePdf.php` + les trois services `*PdfService.php` |
+| Import des vacances | `app/Services/SchoolHolidayApiService.php` |
+| Recherche d'adresse | `app/Services/AddressApiService.php` |
+| Contrôle de schéma au démarrage | `app/Models/SchemaModel.php` |
+| Navigation et groupes d'onglets | `app/Views/layouts/header.php` |
+| Injection des globales JS | `app/Views/layouts/footer.php` |
+| Amorçage des modules JS | `assets/js/page-bootstrap.js` |
+| Refus d'accès nginx | `docker/nginx/default.conf` |
+| Application des migrations | `docker/db/apply-migrations.sh` |
+
+---
+
+## 15. Checklist avant commit
+
+- [ ] `find . -name '*.php' -not -path './.git/*' -exec php -l {} \;` passe.
+- [ ] Tout endpoint mutant a : un garde `Access`, `Request::requireMethod('POST')`,
+      `Csrf::assertPayload()`, un `Journal::ecriture()` de succès.
+- [ ] Toute nouvelle voie d'écriture de créneaux appelle `assertDatesWithinContract()`.
+- [ ] Nouvelle table ou colonne obligatoire → listes de `SchemaModel` mises à jour.
+- [ ] Nouvelle migration → idempotente, et nommée selon l'**ordre alphabétique** voulu.
+- [ ] Nouvelle page → `$navigation`, `$navigationGroups`, `acces_role_page` (migration SQL).
+- [ ] JS/CSS modifié → `?v=` bumpé dans `header.php`, `footer.php` **et** `pages/role.php`.
+- [ ] Aucun `onclick=` ni `style=` inline ; tout `<script>` inline porte le `nonce`.
+- [ ] Échappement côté JS via `PTA.utils.escapeHtml`, jamais une variante locale.
+- [ ] `docker compose up -d --build php nginx` pour voir l'effet du changement.
+
+---
+
+## 16. Historique des versions
+
+Chaque fichier documente **une version successive** et explique *pourquoi* une décision a été prise.
+Ils restent utiles pour comprendre un choix, mais **seul le code fait foi**.
+
+| Fichier | Sujet |
+|---------|-------|
+| `README_V6.md` | Passage de la SPA à l'architecture multipage |
+| `README_V7.md` | Socle PTA annuel, équipes mercredis/vacances, contrôles métier |
+| `README_V7_1.md` → `README_V7_7.md` | Vue annuelle, rôles et droits, ajustements successifs |
+| `README_V7_8.md` | Sécurité et matrice des droits déplacée en vues SQL |
+| `README_V7_9.md` | Tableau de bord du Service Enfance |
+| `README_V7_10.md` | Éditeur de semaine type, application sur période |
+| `README_V7_11.md` | Connexion par jeton, espace DSI, journal d'activité |
+| `README_V7_12.md` | Mot de passe des comptes privilégiés |
+| `README_V7_13.md` | Nom et prénom modifiables sur la fiche agent |
+| `README_V7_14.md` | Groupe de navigation « Management » |
+| `README_V7_15.md` | Affectations bornées par les dates de contrat |
+| `README_V7_27.md` | Distribution des jetons de terrain par le Service Enfance |
diff --git a/docs/README_DOCKER.md b/docs/README_DOCKER.md
deleted file mode 100644
index 94ef749..0000000
--- a/docs/README_DOCKER.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# PTA - Docker / Nginx / PHP / MariaDB / phpMyAdmin
-
-## Installation
-
-Copier les fichiers de ce kit à la racine du projet PTA :
-
-- `Dockerfile`
-- `docker-compose.yml`
-- `.env.example`
-- `docker/nginx/default.conf`
-- `docker/php/php.ini`
-- `docker/db/apply-migrations.sh`
-- `database/pta_prod_schema_mariadb.sql`
-- `database/migration_*.sql`
-
-Puis :
-
-```bash
-cp .env.example .env
-nano .env
-```
-
-Changer impérativement `DB_PASSWORD` et `DB_ROOT_PASSWORD`.
-
-Démarrer :
-
-```bash
-docker compose up -d --build
-```
-
-Application :
-
-```text
-http://IP_DU_SERVEUR:8080
-```
-
-phpMyAdmin est volontairement publié sur `127.0.0.1:8081` par défaut et **exige
-un identifiant MariaDB** à chaque connexion. Ne pas définir `PMA_USER` /
-`PMA_PASSWORD` dans le compose : ces variables font basculer phpMyAdmin en
-`auth_type=config`, c'est-à-dire une session déjà ouverte pour quiconque
-atteint le port.
-
-Sur le serveur lui-même :
-
-```text
-http://127.0.0.1:8081
-```
-
-Pour y accéder depuis un poste distant, le plus sûr est un tunnel SSH :
-
-```bash
-ssh -L 8081:127.0.0.1:8081 utilisateur@serveur
-```
-
-Puis ouvrir localement :
-
-```text
-http://127.0.0.1:8081
-```
-
-## Base de données
-
-Le schéma `database/pta_prod_schema_mariadb.sql` est exécuté automatiquement uniquement
-lorsque le volume MariaDB est créé pour la première fois.
-
-Il ne sera PAS rejoué à chaque démarrage du conteneur.
-
-### Migrations
-
-Les fichiers `database/migration_*.sql` sont appliqués **automatiquement à chaque
-`docker compose up`**, par le service jetable `db-migrate` :
-
-- il attend que MariaDB soit sain, puis joue les migrations dans l'ordre alphabétique ;
-- la table `schema_migration` mémorise les fichiers déjà appliqués — rien n'est rejoué
-  inutilement ;
-- le service `php` ne démarre qu'après sa sortie en succès : une migration en échec arrête
-  le déploiement au lieu de faire tourner l'application sur une base incomplète ;
-- il vérifie pour finir la présence des sept vues de contrôle d'accès de la V7.8.
-
-Il n'est donc plus nécessaire de supprimer le volume ni d'exécuter les migrations à la main.
-
-```bash
-# Compte rendu de la dernière application
-docker compose logs db-migrate
-
-# Rejouer les migrations sans toucher au reste de la pile
-docker compose up -d --force-recreate db-migrate
-```
-
-Toute nouvelle migration doit être écrite idempotente (`CREATE TABLE IF NOT EXISTS`,
-`INSERT ... ON DUPLICATE KEY UPDATE`, `CREATE OR REPLACE VIEW`) : un fichier dont le contenu
-change après coup est rejoué.
-
-## Commandes utiles
-
-```bash
-# Etat
-docker compose ps
-
-# Logs
-docker compose logs -f nginx php db
-
-# Rebuild après modification du PHP / JS / CSS
-docker compose up -d --build php nginx
-
-# Journal de l'application des migrations
-docker compose logs db-migrate
-
-# Arrêt
-docker compose down
-
-# Arrêt SANS supprimer les données
-docker compose down
-
-# ATTENTION : supprime la base MariaDB persistée
-docker compose down -v
-```
-
-## Connexion de l'application
-
-Le `config.php` PTA utilise déjà les variables :
-
-- `PTA_DB_HOST`
-- `PTA_DB_PORT`
-- `PTA_DB_NAME`
-- `PTA_DB_USER`
-- `PTA_DB_PASS`
-
-Le compose les fournit automatiquement au conteneur PHP.
diff --git a/docs/README_V7_27.md b/docs/README_V7_27.md
new file mode 100644
index 0000000..03011a6
--- /dev/null
+++ b/docs/README_V7_27.md
@@ -0,0 +1,121 @@
+# PTA V7.27 — Le Service Enfance distribue les jetons des agents et des responsables
+
+## Le problème traité
+
+Depuis la V7.11, tout compte d’accès passait par la DSI : création, jeton perdu, départ d’un
+remplaçant. Or c’est le **Service Enfance** qui sait qu’un agent est arrivé, qu’un responsable a
+laissé son jeton chez lui ou qu’un contrat s’arrête. Le détour par la DSI ajoutait un délai — parfois
+plusieurs jours — sans ajouter le moindre contrôle : la DSI ne pouvait rien vérifier de ce qu’on lui
+demandait, elle exécutait.
+
+## Ce qui change
+
+L’onglet **Administration** du Service Enfance gagne une section « Jetons d’accès des agents et des
+responsables », sous les horaires de couverture. On y fait, pour ces deux rôles, ce que la page DSI
+permet :
+
+- **créer** un compte pour un agent ou un lieu qui n’en a pas encore ;
+- **régénérer** un jeton perdu ou compromis — l’ancien cesse aussitôt de fonctionner ;
+- **désactiver** puis réactiver un compte (départ temporaire) ;
+- **supprimer** un compte définitivement ;
+- **générer en lot** les jetons de toutes les identités actives qui n’en ont pas.
+
+Comme sur la page DSI, un jeton produit n’est lisible **qu’une fois**, dans le panneau « Jetons à
+transmettre » : la base n’en garde qu’une empreinte SHA-256. Perdu, il ne se retrouve pas — il se
+régénère.
+
+## Ce qui ne change pas : la frontière de privilège
+
+La délégation s’arrête à **deux rôles : AGENT et RESPONSABLE_STRUCTURE**. Les comptes
+**SERVICE_ENFANCE** et **DSI** n’apparaissent pas dans cette section, ne sont pas créables, et toute
+action qui en désigne un est refusée en **403**. Ce n’est pas une commodité d’affichage :
+
+- un compte Service Enfance créé par le Service Enfance serait une **auto-promotion** — le rôle se
+  distribuerait lui-même, sans contrôle extérieur ;
+- un compte DSI créé par le Service Enfance lui ouvrirait le **journal d’activité**, c’est-à-dire la
+  trace de ses propres actions.
+
+Le **second facteur** de la V7.12 reste hors de portée : ces deux rôles n’ont pas de mot de passe, et
+le Service Enfance n’a aucun moyen d’en effacer un. La réinitialisation de mot de passe reste une
+action DSI, sur la page DSI.
+
+La borne est posée **des deux côtés** :
+
+| Où | Quoi |
+| --- | --- |
+| `AccessAccountController::ROLES_DELEGUES` | La liste blanche PHP, contrôlée avant toute écriture et à la relecture de tout compte désigné |
+| `CompteModel::lister(['roles' => …])` | La liste SQL est bornée ; le filtre d’interface ne peut que **restreindre** à l’intérieur de cette borne |
+| `migration_v7_9h_jetons_service_enfance.sql` | La permission `can_manage_field_access`, accordée au seul Service Enfance |
+
+Une frontière de privilège ne doit pas dépendre d’un seul des deux côtés : une ligne mal saisie en
+base ne doit pas pouvoir ouvrir la création de comptes privilégiés, et inversement.
+
+## Traçabilité
+
+Toutes les actions sont journalisées en catégorie `ADMINISTRATION`, avec le rôle de l’acteur et un
+contexte `canal = DELEGATION_SERVICE_ENFANCE` qui les distingue des mêmes actions faites par la DSI.
+Les **refus** le sont aussi, en `ACCES_REFUSE` : `ROLE_HORS_PERIMETRE` (création tentée sur un rôle
+privilégié) et `COMPTE_HORS_PERIMETRE` (action tentée sur un compte privilégié). La DSI garde donc la
+lecture complète de ce que le Service Enfance fait des accès.
+
+## Fichiers
+
+| Fichier | Rôle |
+| --- | --- |
+| `database/migration_v7_9h_jetons_service_enfance.sql` | Permission `can_manage_field_access`. Aucune page nouvelle : « Administration » est déjà ouverte au Service Enfance |
+| `app/Controllers/AccessAccountController.php` | Les cinq endpoints, la liste blanche et les refus |
+| `api/acces_comptes.php`, `acces_compte_creer.php`, `acces_compte_jeton.php`, `acces_compte_statut.php`, `acces_comptes_manquants.php` | Points d’entrée minces |
+| `app/Models/CompteModel.php` | Filtre `roles` sur `lister()` |
+| `app/Views/partials/administration.php` | La section et le panneau des jetons |
+| `assets/js/access-tokens.js` | Module `accessTokens` |
+
+## V7.28 — Couper l’accès depuis la fiche des agents
+
+La page **Agents** gagne, à côté de « Modifier », un bouton qui **coupe ou rétablit l’accès** de
+l’agent : « Couper l’accès » / « Rétablir l’accès ». C’est le geste courant — un départ, un arrêt
+long, un retour — là où la section « Jetons d’accès » de l’onglet Administration porte la
+distribution des jetons elle-même.
+
+Ce bouton **ne touche pas au jeton** : désactiver puis réactiver rend le *même* jeton valable, et
+l’agent n’a rien à recevoir. Il ne touche pas non plus à la fiche de l’agent, qui reste planifiable —
+c’est l’accès à l’application qui est coupé, pas la personne au planning. Un agent qui n’a pas encore
+de compte affiche un bouton inerte « Sans compte d’accès », qui renvoie vers Administration : seul
+cet écran sait afficher un jeton fraîchement produit.
+
+Aucun droit nouveau : le module `agentAccess` réutilise `api/acces_comptes.php` et
+`api/acces_compte_statut.php`, donc les mêmes gardes, la même liste blanche de rôles et la même
+journalisation. L’état des comptes n’est **pas** rendu par PHP mais chargé par le module — le HTML
+servi ne porte aucune information sur les comptes, comme sur l’écran DSI.
+
+## V7.29 — Un accès coupé retire l’agent des listes d’affectation
+
+Couper l’accès d’un agent le retire désormais des listes **où l’on affecte** :
+
+| Écran | Effet |
+| --- | --- |
+| Saisie (`api/agents.php` → `AgentModel::listForLocation()`) | L’agent n’est plus proposé dans le sélecteur |
+| Équipes (`PageController::teams()` → `allSelectable()`) | L’agent n’est plus proposé à la composition |
+
+Trois bornes, toutes portées par le même `NOT EXISTS` de `AgentModel::SANS_COMPTE_COUPE` :
+
+- **un agent SANS compte reste proposé.** Il n’a pas encore reçu son jeton, ce qui est l’état normal
+  avant distribution : le filtrer viderait les listes d’une installation neuve ;
+- le filtre porte sur `compte_acces.actif`, **pas** sur `agent.actif` : fermer une fiche d’agent et
+  couper un accès restent deux décisions distinctes ;
+- les écrans de **consultation** (planning par agent, vue annuelle, PTA détaillé) et le
+  **référentiel Agents** continuent de montrer l’agent. Sans quoi on ne pourrait plus ni relire son
+  année passée, ni lui rétablir son accès — le bouton vit précisément sur cette page.
+
+**Ce qui n’est pas défait :** les créneaux déjà saisis et les équipes déjà composées restent en
+place. Couper un accès n’efface rien du passé. En revanche, un lien profond qui désigne un agent
+coupé (file de validation, tableau de bord) ne peut plus le sélectionner : l’écran de saisie le dit
+alors explicitement, plutôt que de rester vide — rétablir l’accès rend la saisie de nouveau possible.
+
+## Correctif embarqué
+
+`CompteModel::lister()` répétait le paramètre nommé `:q` quatre fois dans sa clause de recherche. PDO
+tourne ici **sans émulation de requêtes préparées** (`ATTR_EMULATE_PREPARES = 0`) : MariaDB refuse
+alors un même paramètre employé plusieurs fois. **Toute recherche par nom, matricule ou début de
+jeton échouait en 500 sur la page DSI**, depuis la V7.11. Les marqueurs sont désormais numérotés
+(`:q_0` … `:q_3`). Le même champ de recherche existant dans la nouvelle section, le défaut aurait été
+reconduit tel quel.