feat(core) : RBAC #345 - AdminHeadcountGuard domain service

feat(core) : RBAC #345 - add core.roles.view permission
docs(core) : RBAC #345 - spec voter + usePermissions
2026-04-15 15:45:55 +02:00 · 2026-04-15 15:42:42 +02:00 · 2026-04-15 15:28:51 +02:00 · 2026-04-15 14:53:49 +02:00 · 2026-04-15 14:28:02 +02:00 · 2026-04-15 14:17:18 +02:00
23 changed files with 3106 additions and 194 deletions
--- a/composer.json
+++ b/composer.json
@@ -23,7 +23,6 @@
        "symfony/expression-language": "8.0.*",
        "symfony/flex": "^2",
        "symfony/framework-bundle": "8.0.*",
-        "symfony/http-client": "8.0.*",
        "symfony/mime": "8.0.*",
        "symfony/monolog-bundle": "^4.0",
        "symfony/property-access": "8.0.*",
@@ -90,6 +89,8 @@
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^4.3",
        "friendsofphp/php-cs-fixer": "^3.94",
-        "phpunit/phpunit": "^13.0"
+        "phpunit/phpunit": "^13.0",
+        "symfony/browser-kit": "8.0.*",
+        "symfony/http-client": "8.0.*"
    }
 }
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
        "This file is @generated automatically"
    ],
-    "content-hash": "bfd26e903d79f710cfe95452c05f2a25",
+    "content-hash": "75f8e672f2a401290886fbcf01befd3f",
    "packages": [
        {
            "name": "api-platform/doctrine-common",
@@ -4988,180 +4988,6 @@
            ],
            "time": "2026-03-30T15:14:47+00:00"
        },
-        {
-            "name": "symfony/http-client",
-            "version": "v8.0.8",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/symfony/http-client.git",
-                "reference": "356e43d6994ae9d7761fd404d40f78691deabe0e"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/symfony/http-client/zipball/356e43d6994ae9d7761fd404d40f78691deabe0e",
-                "reference": "356e43d6994ae9d7761fd404d40f78691deabe0e",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=8.4",
-                "psr/log": "^1|^2|^3",
-                "symfony/http-client-contracts": "~3.4.4|^3.5.2",
-                "symfony/service-contracts": "^2.5|^3"
-            },
-            "conflict": {
-                "amphp/amp": "<3",
-                "php-http/discovery": "<1.15"
-            },
-            "provide": {
-                "php-http/async-client-implementation": "*",
-                "php-http/client-implementation": "*",
-                "psr/http-client-implementation": "1.0",
-                "symfony/http-client-implementation": "3.0"
-            },
-            "require-dev": {
-                "amphp/http-client": "^5.3.2",
-                "amphp/http-tunnel": "^2.0",
-                "guzzlehttp/promises": "^1.4|^2.0",
-                "nyholm/psr7": "^1.0",
-                "php-http/httplug": "^1.0|^2.0",
-                "psr/http-client": "^1.0",
-                "symfony/cache": "^7.4|^8.0",
-                "symfony/dependency-injection": "^7.4|^8.0",
-                "symfony/http-kernel": "^7.4|^8.0",
-                "symfony/messenger": "^7.4|^8.0",
-                "symfony/process": "^7.4|^8.0",
-                "symfony/rate-limiter": "^7.4|^8.0",
-                "symfony/stopwatch": "^7.4|^8.0"
-            },
-            "type": "library",
-            "autoload": {
-                "psr-4": {
-                    "Symfony\\Component\\HttpClient\\": ""
-                },
-                "exclude-from-classmap": [
-                    "/Tests/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Nicolas Grekas",
-                    "email": "p@tchwork.com"
-                },
-                {
-                    "name": "Symfony Community",
-                    "homepage": "https://symfony.com/contributors"
-                }
-            ],
-            "description": "Provides powerful methods to fetch HTTP resources synchronously or asynchronously",
-            "homepage": "https://symfony.com",
-            "keywords": [
-                "http"
-            ],
-            "support": {
-                "source": "https://github.com/symfony/http-client/tree/v8.0.8"
-            },
-            "funding": [
-                {
-                    "url": "https://symfony.com/sponsor",
-                    "type": "custom"
-                },
-                {
-                    "url": "https://github.com/fabpot",
-                    "type": "github"
-                },
-                {
-                    "url": "https://github.com/nicolas-grekas",
-                    "type": "github"
-                },
-                {
-                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
-                    "type": "tidelift"
-                }
-            ],
-            "time": "2026-03-30T15:14:47+00:00"
-        },
-        {
-            "name": "symfony/http-client-contracts",
-            "version": "v3.6.0",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/symfony/http-client-contracts.git",
-                "reference": "75d7043853a42837e68111812f4d964b01e5101c"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/symfony/http-client-contracts/zipball/75d7043853a42837e68111812f4d964b01e5101c",
-                "reference": "75d7043853a42837e68111812f4d964b01e5101c",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=8.1"
-            },
-            "type": "library",
-            "extra": {
-                "thanks": {
-                    "url": "https://github.com/symfony/contracts",
-                    "name": "symfony/contracts"
-                },
-                "branch-alias": {
-                    "dev-main": "3.6-dev"
-                }
-            },
-            "autoload": {
-                "psr-4": {
-                    "Symfony\\Contracts\\HttpClient\\": ""
-                },
-                "exclude-from-classmap": [
-                    "/Test/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Nicolas Grekas",
-                    "email": "p@tchwork.com"
-                },
-                {
-                    "name": "Symfony Community",
-                    "homepage": "https://symfony.com/contributors"
-                }
-            ],
-            "description": "Generic abstractions related to HTTP clients",
-            "homepage": "https://symfony.com",
-            "keywords": [
-                "abstractions",
-                "contracts",
-                "decoupling",
-                "interfaces",
-                "interoperability",
-                "standards"
-            ],
-            "support": {
-                "source": "https://github.com/symfony/http-client-contracts/tree/v3.6.0"
-            },
-            "funding": [
-                {
-                    "url": "https://symfony.com/sponsor",
-                    "type": "custom"
-                },
-                {
-                    "url": "https://github.com/fabpot",
-                    "type": "github"
-                },
-                {
-                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
-                    "type": "tidelift"
-                }
-            ],
-            "time": "2025-04-29T11:18:49+00:00"
-        },
        {
            "name": "symfony/http-foundation",
            "version": "v8.0.8",
@@ -11018,6 +10844,322 @@
            ],
            "time": "2024-10-20T05:08:20+00:00"
        },
+        {
+            "name": "symfony/browser-kit",
+            "version": "v8.0.8",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/browser-kit.git",
+                "reference": "f5a28fca785416cf489dd579011e74c831100cc3"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/browser-kit/zipball/f5a28fca785416cf489dd579011e74c831100cc3",
+                "reference": "f5a28fca785416cf489dd579011e74c831100cc3",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.4",
+                "symfony/dom-crawler": "^7.4|^8.0"
+            },
+            "require-dev": {
+                "symfony/css-selector": "^7.4|^8.0",
+                "symfony/http-client": "^7.4|^8.0",
+                "symfony/mime": "^7.4|^8.0",
+                "symfony/process": "^7.4|^8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Component\\BrowserKit\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Tests/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Fabien Potencier",
+                    "email": "fabien@symfony.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Simulates the behavior of a web browser, allowing you to make requests, click on links and submit forms programmatically",
+            "homepage": "https://symfony.com",
+            "support": {
+                "source": "https://github.com/symfony/browser-kit/tree/v8.0.8"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2026-03-30T15:14:47+00:00"
+        },
+        {
+            "name": "symfony/dom-crawler",
+            "version": "v8.0.8",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/dom-crawler.git",
+                "reference": "284ace90732b445b027728b5e0eec6418a17a364"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/dom-crawler/zipball/284ace90732b445b027728b5e0eec6418a17a364",
+                "reference": "284ace90732b445b027728b5e0eec6418a17a364",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.4",
+                "symfony/polyfill-ctype": "^1.8",
+                "symfony/polyfill-mbstring": "^1.0"
+            },
+            "require-dev": {
+                "symfony/css-selector": "^7.4|^8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Component\\DomCrawler\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Tests/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Fabien Potencier",
+                    "email": "fabien@symfony.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Eases DOM navigation for HTML and XML documents",
+            "homepage": "https://symfony.com",
+            "support": {
+                "source": "https://github.com/symfony/dom-crawler/tree/v8.0.8"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2026-03-30T15:14:47+00:00"
+        },
+        {
+            "name": "symfony/http-client",
+            "version": "v8.0.8",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/http-client.git",
+                "reference": "356e43d6994ae9d7761fd404d40f78691deabe0e"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/http-client/zipball/356e43d6994ae9d7761fd404d40f78691deabe0e",
+                "reference": "356e43d6994ae9d7761fd404d40f78691deabe0e",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.4",
+                "psr/log": "^1|^2|^3",
+                "symfony/http-client-contracts": "~3.4.4|^3.5.2",
+                "symfony/service-contracts": "^2.5|^3"
+            },
+            "conflict": {
+                "amphp/amp": "<3",
+                "php-http/discovery": "<1.15"
+            },
+            "provide": {
+                "php-http/async-client-implementation": "*",
+                "php-http/client-implementation": "*",
+                "psr/http-client-implementation": "1.0",
+                "symfony/http-client-implementation": "3.0"
+            },
+            "require-dev": {
+                "amphp/http-client": "^5.3.2",
+                "amphp/http-tunnel": "^2.0",
+                "guzzlehttp/promises": "^1.4|^2.0",
+                "nyholm/psr7": "^1.0",
+                "php-http/httplug": "^1.0|^2.0",
+                "psr/http-client": "^1.0",
+                "symfony/cache": "^7.4|^8.0",
+                "symfony/dependency-injection": "^7.4|^8.0",
+                "symfony/http-kernel": "^7.4|^8.0",
+                "symfony/messenger": "^7.4|^8.0",
+                "symfony/process": "^7.4|^8.0",
+                "symfony/rate-limiter": "^7.4|^8.0",
+                "symfony/stopwatch": "^7.4|^8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Component\\HttpClient\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Tests/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Nicolas Grekas",
+                    "email": "p@tchwork.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Provides powerful methods to fetch HTTP resources synchronously or asynchronously",
+            "homepage": "https://symfony.com",
+            "keywords": [
+                "http"
+            ],
+            "support": {
+                "source": "https://github.com/symfony/http-client/tree/v8.0.8"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2026-03-30T15:14:47+00:00"
+        },
+        {
+            "name": "symfony/http-client-contracts",
+            "version": "v3.6.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/http-client-contracts.git",
+                "reference": "75d7043853a42837e68111812f4d964b01e5101c"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/http-client-contracts/zipball/75d7043853a42837e68111812f4d964b01e5101c",
+                "reference": "75d7043853a42837e68111812f4d964b01e5101c",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.1"
+            },
+            "type": "library",
+            "extra": {
+                "thanks": {
+                    "url": "https://github.com/symfony/contracts",
+                    "name": "symfony/contracts"
+                },
+                "branch-alias": {
+                    "dev-main": "3.6-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Contracts\\HttpClient\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Test/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Nicolas Grekas",
+                    "email": "p@tchwork.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Generic abstractions related to HTTP clients",
+            "homepage": "https://symfony.com",
+            "keywords": [
+                "abstractions",
+                "contracts",
+                "decoupling",
+                "interfaces",
+                "interoperability",
+                "standards"
+            ],
+            "support": {
+                "source": "https://github.com/symfony/http-client-contracts/tree/v3.6.0"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2025-04-29T11:18:49+00:00"
+        },
        {
            "name": "symfony/process",
            "version": "v8.0.8",
--- a/config/packages/api_platform.yaml
+++ b/config/packages/api_platform.yaml
@@ -1,6 +1,14 @@
 api_platform:
    title: Coltura API
    version: 1.0.0
+    # Scan du module Core pour decouvrir les classes ApiResource et ApiFilter.
+    # Ajouter un chemin par module lors de l'ajout d'entites ApiResource dans d'autres modules.
+    # Sans ces paths, le compile pass d'API Platform ne declare pas les
+    # services de filtres annotes (les filtres etaient silencieusement
+    # ignores sur Permission — cf. ticket #344).
+    mapping:
+        paths:
+            - '%kernel.project_dir%/src/Module/Core/Domain/Entity'
    formats:
        jsonld: ['application/ld+json']
        json: ['application/json']
--- a/docs/rbac/ticket-344-spec.md
+++ b/docs/rbac/ticket-344-spec.md
@@ -0,0 +1,275 @@
+# Ticket #344 - 2/5 - API CRUD Roles & Permissions (Backend)
+
+## 1. Objectif
+
+Exposer via API Platform le socle RBAC livre par le ticket #343 (entites `Role`, `Permission`, relations `User->roles`/`directPermissions`, flag `isAdmin`). Ce ticket livre la surface HTTP minimale permettant :
+
+- de lister et consulter les permissions synchronisees par `app:sync-permissions`,
+- de gerer le cycle de vie des roles (CRUD) tout en protegeant les roles systeme,
+- d'attribuer `isAdmin`, les roles RBAC et les permissions directes a un utilisateur sans polluer le groupe `user:write` (commit `0fc4e16`).
+
+Le ticket n'introduit **aucune logique d'autorisation metier** : toute la verification `is_granted('module.resource.action')` est traitee par le voter du ticket #345. A ce stade, les operations sont gardees par un simple `is_granted('ROLE_ADMIN')`, remplace au #345.
+
+## 2. Perimetre
+
+### IN
+
+- Exposer l'entite `Permission` en API Platform en lecture seule (`GetCollection`, `Get`), groupe `permission:read`, filtres `module` et `orphan`.
+- Exposer l'entite `Role` en API Platform avec CRUD complet (`GetCollection`, `Get`, `Post`, `Patch`, `Delete`), groupes `role:read` et `role:write`, filtre `isSystem`.
+- Ajouter un processor `RoleProcessor` decorant `PersistProcessor` et `RemoveProcessor` pour :
+  - refuser la suppression d'un role systeme en traduisant `SystemRoleDeletionException` en `403`,
+  - empecher la mutation de `code` et `isSystem` sur un role systeme existant.
+- Ajouter une operation nommee `user_rbac_patch` (`PATCH /api/users/{id}/rbac`) sur l'entite `User` avec son propre groupe `user:rbac:write` exposant `isAdmin`, `roles` et `directPermissions`. Laisser `user:write` propre pour les champs profil (compatible avec la decision de `0fc4e16`). Le nom explicite est indispensable : API Platform 4 identifie les operations par nom, un `new Patch` sans `name:` entrerait en collision avec l'operation profil existante.
+- Ajouter un processor `UserRbacProcessor` qui persiste les mutations RBAC de l'utilisateur sans toucher au password hashing (decorator de `PersistProcessor`, pas du `UserPasswordHasherProcessor`).
+- Ajouter sur `Role` les contraintes Symfony Validator : `UniqueEntity(fields: ['code'])`, `Assert\NotBlank` et `Assert\Regex` sur `code`, `Assert\NotBlank` sur `label` (cf. section 6).
+- Garder toutes les operations sous `is_granted('ROLE_ADMIN')` avec un commentaire `// TODO ticket #345 : remplacer par is_granted('core.roles.manage')`.
+- Tests PHPUnit unitaires (processors) et fonctionnels (`ApiTestCase`) couvrant les chemins nominaux et les cas 403/422.
+
+### OUT
+
+- Ticket `#345` : voter `PermissionVoter`, remplacement du `is_granted('ROLE_ADMIN')` par les codes de permission, composable front `usePermissions`.
+- Ticket `#346` : ecrans d'administration front (liste/edition des roles et permissions).
+- Ticket `#347` : UX des erreurs 403 et integration front de l'ecran de gestion des permissions utilisateur.
+- Endpoint d'ecriture sur `Permission` : la table reste la propriete exclusive de `app:sync-permissions` (source de verite = code).
+- Lecture des permissions effectives d'un `User` via `/api/me` : traitee au #345 en meme temps que le voter.
+- Exposition d'un endpoint de bulk-assign permissions sur plusieurs utilisateurs : hors scope.
+
+## 3. Fichiers a creer
+
+### Infrastructure - Processors
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessor.php`
+  Decorator de `ApiPlatform\Doctrine\Common\State\PersistProcessor` et `RemoveProcessor`. Charge de la garde `ensureDeletable()` et de la protection des champs immuables sur un role systeme.
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php`
+  Decorator de `PersistProcessor` specifique a l'operation `PATCH /api/users/{id}/rbac`. Persiste les mutations `isAdmin`, `roles`, `directPermissions` sans passer par `UserPasswordHasherProcessor`.
+
+### Tests unitaires
+
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessorTest.php`
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessorTest.php`
+
+### Tests fonctionnels
+
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Api/PermissionApiTest.php`
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Api/RoleApiTest.php`
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Api/UserRbacApiTest.php`
+
+## 4. Fichiers a modifier
+
+### Entite `Permission`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/Permission.php`
+
+- Ajouter l'attribut `#[ApiResource]` avec operations `GetCollection` + `Get` uniquement.
+- Normalization context : groupe `permission:read` uniquement.
+- Pas de `denormalizationContext` (lecture seule).
+- Security `is_granted('ROLE_ADMIN')` sur les deux operations (TODO #345).
+- Ajouter `#[Groups(['permission:read'])]` sur `$id`, `$code`, `$label`, `$module`, `$orphan`. Pas d'ajout du groupe `role:read` : on laisse API Platform serialiser la relation `Role::$permissions` en IRIs par defaut, le front resoudra les details en 2 appels si necessaire (decision explicite pour garder les payloads petits et les permissions paginable independamment).
+- Ajouter les filtres API Platform `SearchFilter` sur `module` (exact) et `BooleanFilter` sur `orphan`.
+
+Extrait attendu :
+
+```php
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            security: "is_granted('ROLE_ADMIN')",
+            normalizationContext: ['groups' => ['permission:read']],
+        ),
+        new Get(
+            security: "is_granted('ROLE_ADMIN')",
+            normalizationContext: ['groups' => ['permission:read']],
+        ),
+    ],
+)]
+#[ApiFilter(SearchFilter::class, properties: ['module' => 'exact'])]
+#[ApiFilter(BooleanFilter::class, properties: ['orphan'])]
+```
+
+### Entite `Role`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/Role.php`
+
+- Ajouter l'attribut `#[ApiResource]` avec operations `GetCollection`, `Get`, `Post`, `Patch`, `Delete`.
+- Normalization context : `role:read`. Denormalization context : `role:write`.
+- Processor `RoleProcessor::class` sur `Post`, `Patch` et `Delete`.
+- Security `is_granted('ROLE_ADMIN')` sur les 5 operations (TODO #345).
+- Groupes :
+  - `$id` : `role:read`.
+  - `$code` : `role:read`, `role:write`. L'immuabilite apres creation est portee par `RoleProcessor` (variante A, cf. section 5), pas par un decoupage de groupes.
+  - `$label` : `role:read`, `role:write`.
+  - `$description` : `role:read`, `role:write`.
+  - `$isSystem` : `role:read` (jamais writable via API).
+  - `$permissions` : `role:read`, `role:write`. Serialise en IRIs (comportement API Platform par defaut sur une relation ManyToMany).
+- Filtre `BooleanFilter` sur `isSystem`.
+- **Important** : le constructeur actuel `public function __construct(string $code, string $label, bool $isSystem = false, ?string $description = null)` doit etre compatible avec la denormalisation API Platform sur `POST`. API Platform 4 resout les arguments du constructeur par nom de propriete denormalise. Verifier (ou adapter) que `isSystem` ne peut pas etre injecte par le POST car il n'est pas dans `role:write`.
+
+### Entite `User`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/User.php`
+
+- Ajouter dans la liste des operations `ApiResource` existantes une operation dediee :
+
+```php
+new Patch(
+    name: 'user_rbac_patch',
+    uriTemplate: '/users/{id}/rbac',
+    security: "is_granted('ROLE_ADMIN')",
+    denormalizationContext: ['groups' => ['user:rbac:write']],
+    processor: UserRbacProcessor::class,
+),
+```
+
+Le `name:` est OBLIGATOIRE : sans lui, API Platform 4 deduit un nom par defaut qui peut collisionner avec la `Patch` profil existante (meme classe, meme methode HTTP) et provoquer un ecrasement silencieux de la route `/api/users/{id}`.
+
+- Ajouter le groupe `user:rbac:write` sur les proprietes :
+  - `$isAdmin`
+  - `$roles`
+  - `$directPermissions`
+- Ne PAS toucher `user:write` : la decision de `0fc4e16` est confirmee par ce ticket.
+
+Raison de l'endpoint dedie (option B) :
+- Separation des preoccupations : un `PATCH /api/users/{id}` reste un endpoint "profil" ; la promotion admin et la gestion des permissions est un acte administratif explicite et tracable.
+- Facilite future l'ajout d'un audit log dedie (`#355` audit log project) sur l'endpoint RBAC sans polluer l'audit profil.
+- Contrat front simple : une seule route, un seul groupe, une seule validation.
+
+## 5. Regles metier et cas limites
+
+### Role
+
+- **Creation (`POST /api/roles`)** :
+  - `code`, `label` obligatoires. `description` optionnel. `permissions` optionnel (tableau d'IRIs).
+  - `isSystem` est toujours `false` pour les roles crees via API (n'est pas dans `role:write`).
+  - Unicite du `code` geree par la contrainte DB `uniq_role_code` → 422 via `UniqueEntity` validator a ajouter sur l'entite (voir section 6).
+
+- **Modification (`PATCH /api/roles/{id}`)** :
+  - `label`, `description`, `permissions` modifiables librement, y compris sur un role systeme (utile pour customiser l'apparence dans l'UI sans casser la relation).
+  - `code` **immuable apres creation** — strategie retenue (variante A) : un seul groupe `role:write` contenant `code`, et une garde centralisee dans `RoleProcessor`. Le processor compare la valeur entrante a l'etat d'origine via `UnitOfWork::getOriginalEntityData($role)['code']` ; si elle differe, leve `BadRequestHttpException` avec un message francais explicite. Regle unique et uniforme : roles systeme ET roles customs sont concernes. Justification : garder la regle metier dans le domaine applicatif plutot que dupliquer les groupes de serialisation.
+
+- **Suppression (`DELETE /api/roles/{id}`)** :
+  - `RoleProcessor` appelle `$role->ensureDeletable()` avant de deleguer au `RemoveProcessor`.
+  - `SystemRoleDeletionException` est catchee et re-levee en `Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException` (403).
+  - Les relations `user_role` et `role_permission` sur ce role sont nettoyees automatiquement par le `ON DELETE CASCADE` des contraintes `FK_2DE8C6A3D60322AC` (`user_role.role_id`) et `FK_6F7DF886D60322AC` (`role_permission.role_id`) posees dans `migrations/Version20260414150034.php`. Aucun nettoyage manuel necessaire dans `RoleProcessor`. Verifier en test fonctionnel par un DELETE d'un role custom attache a un user, puis assert que le user existe toujours et que `user_role` est vide pour ce couple.
+
+### Permission
+
+- Lecture seule via API. Aucun endpoint de mutation.
+- Si un admin veut forcer une permission sur un utilisateur, il passe par `directPermissions` de `User`.
+
+### User (operation RBAC)
+
+- `PATCH /api/users/{id}/rbac` n'accepte que `isAdmin`, `roles`, `directPermissions`. Tout autre champ dans le payload est ignore (comportement par defaut d'API Platform avec un `denormalizationContext` restreint).
+- **Garde minimale auto-suicide** : `UserRbacProcessor` refuse (`BadRequestHttpException` 400) toute requete ou l'user cible est egal a l'user courant du `Security::getUser()` ET `isAdmin` passe de `true` a `false`. Sans cette garde, un admin peut se degrader seul et perdre acces a l'endpoint, creant une situation de recovery penible. C'est une garde locale et pragmatique, volontairement plus stricte que "le dernier admin" : on interdit l'auto-degradation, point. La garde "plus d'un admin restant" reste reportee au #345 ou un inventaire global fera sens avec le voter. TODO a placer dans le processor avec reference a #345.
+- Le password n'est jamais touche par cet endpoint (contrairement a `UserPasswordHasherProcessor` sur `PATCH /api/users/{id}`).
+
+## 6. Validation
+
+- Ajouter sur `Role` une contrainte `#[UniqueEntity(fields: ['code'])]` pour un 422 propre au lieu d'un 500 SQL en cas de conflit.
+- Ajouter sur `Role::$code` un `#[Assert\NotBlank]` et un `#[Assert\Regex('/^[a-z][a-z0-9_]*$/')]` (meme convention que les permissions).
+- Ajouter sur `Role::$label` un `#[Assert\NotBlank]`.
+
+## 7. Plan de tests
+
+### Unitaires
+
+**`RoleProcessorTest`**
+
+- `process()` d'un role non-systeme en DELETE delegue au `RemoveProcessor` sans lever.
+- `process()` d'un role systeme en DELETE leve `AccessDeniedHttpException` (403) et n'appelle pas le decorator.
+- `process()` d'un role systeme en PATCH dont le `code` a change leve `BadRequestHttpException`.
+- `process()` d'un role systeme en PATCH dont seuls `label`/`permissions` changent delegue au `PersistProcessor`.
+- `process()` d'un role non-systeme en POST delegue au `PersistProcessor`.
+
+**`UserRbacProcessorTest`**
+
+- `process()` persiste un user avec `isAdmin = true` via le decorator.
+- `process()` persiste une collection de `roles` mise a jour.
+- `process()` ne declenche jamais le hashing de password (verifier que `UserPasswordHasherProcessor` n'est pas dans la chaine).
+
+### Fonctionnels (`ApiTestCase`)
+
+**`PermissionApiTest`**
+
+- `GET /api/permissions` en tant qu'admin retourne la liste des permissions synchronisees.
+- `GET /api/permissions?module=core` filtre par module.
+- `GET /api/permissions?orphan=true` retourne uniquement les orphelines.
+- `GET /api/permissions/{id}` retourne les champs attendus (groupe `permission:read`).
+- `POST /api/permissions` en tant qu'admin retourne `405 Method Not Allowed`.
+- `GET /api/permissions` non authentifie retourne `401`.
+- `GET /api/permissions` en tant que user standard retourne `403`.
+
+**`RoleApiTest`**
+
+- `POST /api/roles` avec `{code, label, description}` retourne `201` et persiste `isSystem = false`.
+- `POST /api/roles` avec un `code` deja utilise retourne `422`.
+- `POST /api/roles` avec un `code` invalide (`MAJ`, `space`) retourne `422`.
+- `PATCH /api/roles/{id}` sur un role custom modifie `label` et ajoute des permissions via IRIs → `200`.
+- `PATCH /api/roles/{id}` sur le role `admin` (systeme) modifiant seulement `label` → `200`.
+- `PATCH /api/roles/{id}` sur le role `admin` tentant de modifier `code` → `400`.
+- `DELETE /api/roles/{id}` sur un role custom → `204`.
+- `DELETE /api/roles/{id}` sur le role `admin` → `403` avec `SystemRoleDeletionException` traduite.
+- `DELETE /api/roles/{id}` d'un role custom attache a un user : le user reste, la relation `user_role` est nettoyee par le CASCADE.
+- Toute operation sans auth retourne `401`.
+- Toute operation en tant que user standard retourne `403`.
+
+**`UserRbacApiTest`**
+
+- `PATCH /api/users/{id}/rbac` en tant qu'admin avec `{isAdmin: true}` promeut le user.
+- `PATCH /api/users/{id}/rbac` avec `{roles: [IRI...]}` remplace la collection de roles RBAC.
+- `PATCH /api/users/{id}/rbac` avec `{directPermissions: [IRI...]}` remplace les permissions directes.
+- `PATCH /api/users/{id}/rbac` en tant que user standard retourne `403`.
+- `PATCH /api/users/{id}/rbac` non authentifie retourne `401`.
+- `PATCH /api/users/{id}/rbac` avec un champ `username` dans le payload n'est pas persiste (denormalization context restreint).
+- `PATCH /api/users/{id}` sans `/rbac` avec `{isAdmin: true}` ne modifie PAS `isAdmin` (confirme la decision `0fc4e16`).
+
+## 8. Securite et traduction d'exceptions
+
+- `SystemRoleDeletionException` → `AccessDeniedHttpException` (403) dans `RoleProcessor` (pas via un listener global : on garde la traduction locale au perimetre RBAC).
+- `BadRequestHttpException` pour la mutation de `code` sur un role systeme : message explicite en francais, dans le payload Hydra `hydra:description`.
+- Toutes les routes ont pour l'instant `security: "is_granted('ROLE_ADMIN')"`. Un commentaire `// TODO ticket #345` doit etre present sur chaque attribut pour faciliter le remplacement.
+
+## 9. Conventions et architecture
+
+- Respect strict du modular monolith : tous les fichiers crees vivent dans `src/Module/Core/` ou `tests/Module/Core/`. Aucun import depuis un autre module.
+- `declare(strict_types=1)` en tete des nouveaux fichiers.
+- Commentaires PHP en francais, identifiants anglais (`CLAUDE.md`).
+- Processors branches via l'autoconfiguration Symfony ; aucun wiring manuel dans `services.yaml` attendu si le constructeur est injecte proprement.
+- Pattern de decorator : utiliser `#[AsDecorator]` ou `#[Autoconfigure]` pour brancher le processor en tant que decorator du `PersistProcessor` API Platform, selon le pattern deja utilise par `UserPasswordHasherProcessor`.
+- Aucune nouvelle entree necessaire dans `config/modules.php` ni `config/sidebar.php`.
+
+## 10. Ordre d'execution recommande
+
+1. Ajouter l'attribut `#[ApiResource]` et les `#[Groups]` sur `Permission`. Ecrire `PermissionApiTest`.
+2. Ajouter les contraintes Validator sur `Role`. Ajouter `#[ApiResource]` et les `#[Groups]` sur `Role` **sans** processor dans un premier temps pour valider le CRUD nominal.
+3. Creer `RoleProcessor` et le brancher en decorator. Ajouter les gardes systeme. Ecrire `RoleProcessorTest` + cas `RoleApiTest`.
+4. Creer `UserRbacProcessor`. Ajouter l'operation `/users/{id}/rbac` et le groupe `user:rbac:write` sur `User`. Ecrire `UserRbacProcessorTest` + `UserRbacApiTest`.
+5. `make test` complet + `make php-cs-fixer-allow-risky`.
+6. Documentation : referencer ce spec dans `docs/rbac/` et mettre a jour le fil conducteur RBAC si un index existe.
+
+## 11. Risques et points d'attention
+
+- **Constructeur de `Role` et denormalisation POST** : API Platform 4 resout les arguments du constructeur par nom ; `isSystem` est dans la signature mais pas dans `role:write`, donc un client ne peut pas l'injecter — a verifier par un test explicite ("POST avec `isSystem: true` est ignore").
+- **`code` immuable** : strategie retenue (garde dans processor) simple mais demande une lecture de l'etat initial du role avant persistance. Utiliser `UnitOfWork::getOriginalEntityData()` pour recuperer la valeur d'origine proprement.
+- **Cascade de delete role → user_role** : depend de `ON DELETE CASCADE` pose par la migration #343. Verifier explicitement en test fonctionnel qu'aucune `ForeignKeyConstraintViolationException` ne remonte.
+- **`UniqueEntity` sur `code`** : ne couvre pas les conflits en race condition, la DB reste la garde ultime. Acceptable.
+- **Pas de filtre sur le `module` de Permission cote front** au #346 sans le filtre API : s'assurer que le filtre est bien pose ici.
+- **Auto-retrait du dernier admin** : garde d'**auto-suicide** posee dans `UserRbacProcessor` (un admin ne peut pas se degrader lui-meme, cf. section 5). La garde "plus d'un admin restant" au niveau global reste reportee au voter #345.
+- **Infra de test fonctionnel (fixtures et isolation)** : les tests `*ApiTest` dependent de la presence en base des roles systeme `admin` et `user`. L'infra actuelle doit fournir soit un reload des fixtures par classe de test, soit `DAMADoctrineTestBundle` pour transactionner chaque test. A verifier au debut de l'etape 1 de l'ordre d'execution ; si absent, ajouter un trait de bootstrap minimal `RbacFixturesTrait` qui insere les deux roles systeme avant chaque classe de test (pas par test, trop couteux). Ne pas bloquer le ticket sur cette question, adapter au vol.
+
+## 12. Criteres d'acceptation (DoD)
+
+- `GET /api/permissions` et `GET /api/permissions/{id}` fonctionnent, filtres `module` et `orphan` operationnels.
+- CRUD complet sur `/api/roles` operationnel, avec `isSystem` en lecture seule cote API.
+- `DELETE /api/roles/{admin_id}` retourne `403` avec un message metier.
+- `PATCH /api/roles/{admin_id}` autorise la modification de `label`/`permissions` mais refuse la modification de `code` avec `400`.
+- `PATCH /api/users/{id}/rbac` permet de modifier `isAdmin`, `roles` et `directPermissions` ; `PATCH /api/users/{id}` (profil) ne les modifie jamais.
+- Les operations API sont gardees par `is_granted('ROLE_ADMIN')` et commentees avec la TODO pointant vers #345.
+- `make test` passe ; `make php-cs-fixer-allow-risky` ne laisse aucun delta.
+- Aucun import croise entre modules ; tous les fichiers crees vivent dans `Module/Core/` ou `tests/Module/Core/`.
+- Le spec est mergee avec le code (meme PR ou PR precedente) pour rester la reference du ticket.
+
+## 13. Remarques de branche
+
+- Le ticket enonce "Branche a creer : `feat/rbac-api` depuis develop apres merge de #2".
+- Branche courante locale : `feat/rbac-core`. A confirmer avec l'utilisateur si PR #2 est mergee : si oui, se rebaser sur `develop` et creer `feat/rbac-api` propre ; sinon, empiler `feat/rbac-api` sur `feat/rbac-core` en attendant le merge.
--- a/docs/rbac/ticket-345-spec.md
+++ b/docs/rbac/ticket-345-spec.md
@@ -0,0 +1,574 @@
+# Ticket #345 - 3/5 - Voter Symfony + composable usePermissions (Full-stack)
+
+## 1. Objectif
+
+Ce ticket remplace les gardes placeholder `is_granted('ROLE_ADMIN')` posees par le #344 sur les 13 operations API Platform du perimetre RBAC par des verifications metier basees sur les codes de permission livres au #343 (`core.users.view`, `core.roles.manage`, etc.). Il introduit le `PermissionVoter` Symfony qui interprete ces codes, avec un bypass total pour les utilisateurs `isAdmin = true` (decision gravee au #343 section 11). Il ferme la garde "dernier admin global" reportee par le #344 via un service domaine mutualise entre les chemins de mutation (`PATCH /users/{id}/rbac` et `DELETE /users/{id}`). Enfin il expose les permissions effectives de l'utilisateur courant via `/api/me` et livre le composable front `usePermissions()` qui les consomme.
+
+A l'issue de ce ticket, l'application dispose d'un systeme d'autorisation applicatif reel, utilisable par les tickets #346 (ecrans d'admin RBAC) et #347 (UX des erreurs 403). Aucune interface d'administration n'est livree ici : le ticket est un socle full-stack sans ecran dedie.
+
+## 2. Perimetre
+
+### IN
+
+- Ajouter la permission `core.roles.view` au catalogue `CoreModule::permissions()` et la synchroniser via `app:sync-permissions`. Documenter la regle par defaut "view + manage par ressource administrable" qui encadre les declarations futures.
+- Creer `PermissionVoter` Symfony qui :
+  - supporte les attributs au format `module.resource[.sub].action` (regex explicite) sans interferer avec `ROLE_*`,
+  - bypasse a `ACCESS_GRANTED` si `User::isAdmin() === true`,
+  - sinon compare l'attribut a `User::getEffectivePermissions()`.
+- Remplacer les 13 `is_granted('ROLE_ADMIN')` places par le #344 (et les operations User heritees du profil pre-#344) par les codes metier adequats sur les entites `Permission`, `Role` et `User`. Supprimer les commentaires `// TODO ticket #345` en meme temps.
+- Creer un service domaine `AdminHeadcountGuard` dans `src/Module/Core/Domain/Security/` qui encapsule la regle "il doit toujours rester au moins un administrateur sur l'instance" et leve `LastAdminProtectionException` quand l'operation ferait tomber le compteur a zero.
+- Brancher le guard dans `UserRbacProcessor` (apres la garde auto-suicide existante) et dans un nouveau `UserProcessor` decorateur de `RemoveProcessor` qui intercepte `DELETE /api/users/{id}`.
+- Ajouter `UserRepositoryInterface::countAdmins(): int` et son implementation Doctrine.
+- Enrichir `/api/me` en exposant `effectivePermissions: list<string>` via un `#[Groups(['me:read'])]` sur la methode existante `User::getEffectivePermissions()`. Aucun changement de `MeProvider`.
+- Livrer `frontend/shared/composables/usePermissions.ts` consommant `useAuthStore().user` (qui porte deja le payload `/api/me`). API publique : `can(code)`, `canAny(codes)`, `canAll(codes)`.
+- Etendre `frontend/shared/types/user-data.ts` avec les champs `isAdmin: boolean` et `effectivePermissions: string[]`.
+- Tests unitaires PHP : `PermissionVoterTest`, `AdminHeadcountGuardTest`, `UserProcessorTest`, extension de `UserRbacProcessorTest`.
+- Tests fonctionnels API : couverture 403 non-admin / 200 admin sur chaque operation des 3 ressources RBAC, cas "dernier admin global" sur PATCH et DELETE, expo `/api/me` avec `effectivePermissions`.
+- Test Vitest du composable `usePermissions`.
+
+### OUT
+
+- Ticket `#346` : ecrans d'administration RBAC front (liste/edition roles, picker permissions, admin user RBAC).
+- Ticket `#347` : UX des erreurs 403 (toasts, redirections, page 403 dediee), integration front complete des ecrans admin RBAC.
+- Decoration des items sidebar par permission : les items portent aujourd'hui un champ `module` owner ; le filtrage par permission individuelle sera ajoute au #346 quand l'UI en aura besoin.
+- Audit log des mutations RBAC : traite par le futur `#355` audit log project, deliberement independant.
+- Decoupe fine de `core.users.manage` en sous-permissions (`create`, `edit`, `delete`) : YAGNI, aucun use-case metier identifie a ce jour.
+- Cache des voter decisions : la verification est O(1) sur un `in_array` avec des collections deja `fetch=EAGER`, aucun cache necessaire.
+
+## 3. Fichiers a creer
+
+### Domaine - Securite
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Security/AdminHeadcountGuard.php`
+  Service domaine encapsulant l'invariant "au moins un admin reste apres l'operation". Depend uniquement de `UserRepositoryInterface::countAdmins()`. Aucune dependance infrastructure, testable en isolation.
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Exception/LastAdminProtectionException.php`
+  Exception metier levee par le guard. Traduite en `BadRequestHttpException` (400) dans les processors.
+
+### Infrastructure - Security
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/Security/PermissionVoter.php`
+  Voter Symfony etendant `Symfony\Component\Security\Core\Authorization\Voter\Voter`. Decouvert automatiquement par `autoconfigure: true`.
+
+### Infrastructure - Processors
+
+- `/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserProcessor.php`
+  Decorateur de `RemoveProcessor` cible sur `DELETE /api/users/{id}`. Appelle `AdminHeadcountGuard` avant de deleguer. Meme pattern qu'`UserRbacProcessor`/`RoleProcessor` : `final class`, `#[Autowire]` sur l'inner, `LogicException` fail-fast si le type entrant n'est pas `User`.
+
+### Frontend - Composable
+
+- `/home/matthieu/dev_malio/Coltura/frontend/shared/composables/usePermissions.ts`
+  Composable stateless qui lit `useAuthStore().user`. Pas de fetch propre, pas de reset (le cycle de vie est porte par l'auth store).
+
+### Tests unitaires PHP
+
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Infrastructure/Security/PermissionVoterTest.php`
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Domain/Security/AdminHeadcountGuardTest.php`
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserProcessorTest.php`
+
+### Tests fonctionnels PHP
+
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Api/MeApiTest.php` (si absent — sinon extension)
+  Couvre l'enrichissement du payload `/api/me`.
+- `/home/matthieu/dev_malio/Coltura/tests/Module/Core/Api/UserApiTest.php` (si absent — sinon extension)
+  Couvre la garde "dernier admin global" sur `DELETE /api/users/{id}`.
+
+### Tests frontend
+
+- `/home/matthieu/dev_malio/Coltura/frontend/shared/composables/__tests__/usePermissions.test.ts`
+  Vitest. Emplacement a adapter si le projet Nuxt a une autre convention (colocalise avec un fichier `.spec.ts`, ou repertoire `tests/`). A verifier au debut de la task frontend.
+
+## 4. Fichiers a modifier
+
+### `CoreModule.php`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/CoreModule.php`
+
+Ajouter une cinquieme entree au catalogue :
+
+```php
+public static function permissions(): array
+{
+    return [
+        ['code' => 'core.users.view',        'label' => 'Voir les utilisateurs'],
+        ['code' => 'core.users.manage',      'label' => 'Gerer les utilisateurs (creer, editer, supprimer)'],
+        ['code' => 'core.roles.view',        'label' => 'Voir les roles RBAC'],
+        ['code' => 'core.roles.manage',      'label' => 'Gerer les roles et permissions'],
+        ['code' => 'core.permissions.view',  'label' => 'Voir le catalogue des permissions'],
+    ];
+}
+```
+
+La commande `app:sync-permissions` creera automatiquement `core.roles.view` a la prochaine execution, sans migration Doctrine necessaire (le catalogue est propriete exclusive de la commande de sync depuis le #343).
+
+### Entite `Permission`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/Permission.php`
+
+Remplacer les 2 gardes placeholder :
+
+```php
+new GetCollection(
+    normalizationContext: ['groups' => ['permission:read']],
+    security: "is_granted('core.permissions.view')",
+),
+new Get(
+    normalizationContext: ['groups' => ['permission:read']],
+    security: "is_granted('core.permissions.view')",
+),
+```
+
+Supprimer les commentaires `// TODO ticket #345`.
+
+### Entite `Role`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/Role.php`
+
+Remplacer les 5 gardes placeholder :
+
+- `GetCollection` → `is_granted('core.roles.view')`
+- `Get` → `is_granted('core.roles.view')`
+- `Post` → `is_granted('core.roles.manage')`
+- `Patch` → `is_granted('core.roles.manage')`
+- `Delete` → `is_granted('core.roles.manage')`
+
+Supprimer les commentaires `// TODO ticket #345`.
+
+### Entite `User`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Entity/User.php`
+
+Remplacer les 6 gardes `ROLE_ADMIN` restantes :
+
+- `Get` (item) → `is_granted('core.users.view')`
+- `GetCollection` → `is_granted('core.users.view')`
+- `Post` → `is_granted('core.users.manage')`
+- `Patch` (profil, sans `name:`) → `is_granted('core.users.manage')`
+- `Patch` (`user_rbac_patch`) → `is_granted('core.users.manage')`
+- `Delete` → `is_granted('core.users.manage')`
+
+Note : l'operation `Get /me` n'a aucune garde (seulement `IS_AUTHENTICATED_FULLY` implicite via `security.yaml`). Ce n'est pas une operation RBAC, elle reste inchangee.
+
+Ajouter le processor `UserProcessor::class` sur l'operation `Delete` :
+
+```php
+new Delete(
+    security: "is_granted('core.users.manage')",
+    processor: UserProcessor::class,
+),
+```
+
+Exposer `getEffectivePermissions()` dans le groupe `me:read` — ajouter l'attribut sur la methode existante :
+
+```php
+#[Groups(['me:read'])]
+public function getEffectivePermissions(): array
+{
+    // implementation existante, inchangee
+}
+```
+
+Supprimer tous les commentaires `// TODO ticket #345` rencontres.
+
+### `UserRepositoryInterface`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Domain/Repository/UserRepositoryInterface.php`
+
+Ajouter la methode :
+
+```php
+/**
+ * Compte le nombre d'utilisateurs avec le flag isAdmin = true.
+ * Utilise par AdminHeadcountGuard pour verifier l'invariant
+ * "au moins un administrateur reste sur l'instance".
+ */
+public function countAdmins(): int;
+```
+
+### `DoctrineUserRepository`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/Doctrine/DoctrineUserRepository.php`
+
+Implementer `countAdmins()` via un `QueryBuilder` simple :
+
+```php
+public function countAdmins(): int
+{
+    return (int) $this->createQueryBuilder('u')
+        ->select('COUNT(u.id)')
+        ->where('u.isAdmin = true')
+        ->getQuery()
+        ->getSingleScalarResult();
+}
+```
+
+### `UserRbacProcessor`
+
+`/home/matthieu/dev_malio/Coltura/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php`
+
+Ajouter la dependance `AdminHeadcountGuard` et l'invoquer **apres** la garde auto-suicide existante, **avant** de deleguer au persist processor. Supprimer le `TODO ticket #345` du docblock.
+
+Logique :
+
+```text
+1. Garde auto-suicide existante (inchangee).
+2. Si l'operation entraine la perte du flag isAdmin (wasAdmin && !data.isAdmin):
+     AdminHeadcountGuard::ensureAtLeastOneAdminRemainsAfterDemotion($data);
+3. Delegation au persist processor.
+```
+
+La detection "wasAdmin && !data.isAdmin" reutilise le meme `UnitOfWork::getOriginalEntityData()` deja utilise par la garde auto-suicide.
+
+### `frontend/shared/types/user-data.ts`
+
+Ajouter les champs :
+
+```ts
+export interface UserData {
+    id: number
+    username: string
+    isAdmin: boolean
+    effectivePermissions: string[]
+    // ... champs existants
+}
+```
+
+### `frontend/shared/services/auth.ts`
+
+A verifier : si `getCurrentUser()` type deja le retour sur `UserData`, rien a changer — les nouveaux champs arrivent automatiquement car l'API les renvoie. Si un mapping manuel est fait dans le service, l'etendre pour ne pas perdre `isAdmin` et `effectivePermissions`. A valider au debut de la task frontend.
+
+## 5. PermissionVoter - details d'implementation
+
+### Regex de support
+
+```php
+private const string PERMISSION_CODE_PATTERN = '/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/';
+```
+
+Garantit :
+- premier caractere alphabetique minuscule,
+- au moins un point de separation (ecarte les `ROLE_*`),
+- segments en snake_case minuscules coherents avec les permissions declarees par les modules.
+
+### `supports(string $attribute, mixed $subject): bool`
+
+Retourne `(bool) preg_match(self::PERMISSION_CODE_PATTERN, $attribute)`. Le `$subject` est ignore : les permissions sont portees par l'utilisateur, pas par une ressource ciblee. Pour l'instant l'autorisation est uniquement basee sur l'identite de l'acteur — les scopes ressource (ex. "edit this specific role") seront traites par un voter dedie si un module metier en a besoin.
+
+### `voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool`
+
+```text
+$user = $token->getUser()
+if (!$user instanceof User) return false                                // ACCESS_DENIED
+if ($user->isAdmin())     return true                                   // bypass total
+return in_array($attribute, $user->getEffectivePermissions(), true)
+```
+
+### Interaction avec les autres voters
+
+Strategie par defaut Symfony `affirmative` : des qu'un voter renvoie GRANTED, l'acces est accorde. `PermissionVoter` ne vote **jamais** sur les attributs `ROLE_*` (filtres par `supports()`), donc :
+
+- l'authentification classique `IS_AUTHENTICATED_FULLY` et `ROLE_USER` continue de fonctionner via `AuthenticatedVoter` et `RoleVoter` de Symfony,
+- un eventuel `is_granted('ROLE_ADMIN')` residuel dans le code continuerait de fonctionner via `RoleVoter` sans interference.
+
+Un test fonctionnel `make test` complet verifiera que l'auth standard marche toujours apres ajout du voter.
+
+### Wiring
+
+`autoconfigure: true` dans `services.yaml` (deja active) detecte la classe via l'interface `VoterInterface`. **Aucun** wiring manuel necessaire dans `services.yaml`.
+
+## 6. AdminHeadcountGuard - regles metier
+
+### Invariant global
+
+> Apres toute operation terminee avec succes, `countAdmins() >= 1`.
+
+### API publique
+
+```php
+final class AdminHeadcountGuard
+{
+    public function __construct(
+        private readonly UserRepositoryInterface $userRepository,
+    ) {}
+
+    /**
+     * Leve si retirer le flag isAdmin a $user ferait tomber le total a zero.
+     * A appeler UNIQUEMENT dans la branche "l'operation retire effectivement isAdmin".
+     */
+    public function ensureAtLeastOneAdminRemainsAfterDemotion(User $user): void;
+
+    /**
+     * Leve si supprimer physiquement $user ferait tomber le total a zero.
+     * A appeler UNIQUEMENT dans la branche DELETE sur un user admin.
+     */
+    public function ensureAtLeastOneAdminRemainsAfterDeletion(User $user): void;
+}
+```
+
+Deux methodes semantiques distinctes plutot qu'une methode generique avec un parametre booleen : ca rend les call-sites lisibles et les tests auto-documentes.
+
+### Logique
+
+Pour les deux methodes, la regle effective est identique :
+
+```text
+if ($this->userRepository->countAdmins() <= 1) {
+    throw new LastAdminProtectionException(
+        'Impossible : au moins un administrateur doit rester sur l\'instance.'
+    );
+}
+```
+
+Les appelants ne passent le guard que si l'operation retire reellement un admin — le guard n'a donc pas a raisonner sur l'etat entrant. Cette separation des responsabilites (le processor decide "est-ce qu'on perd un admin ?", le guard applique "si oui, compte") garde les deux composants minimalistes et testables independamment.
+
+### Cas couverts (tests)
+
+1. `countAdmins() > 1` + demotion → OK (pas d'exception)
+2. `countAdmins() == 1` + demotion → LEVE
+3. `countAdmins() > 1` + deletion → OK
+4. `countAdmins() == 1` + deletion → LEVE
+5. `countAdmins() == 2` + demotion → OK (il en reste 1)
+6. `countAdmins() == 0` + demotion → LEVE (cas theorique, garde defensive)
+
+## 7. Garde "dernier admin" - cohabitation avec l'auto-suicide
+
+Les deux gardes sont distinctes et non fusionnables :
+
+- **Auto-suicide (existante, #344)** : "un admin ne peut pas retirer ses PROPRES droits admin". S'applique meme s'il existe d'autres admins. Protege contre le recovery penible d'un admin qui se cliquerait degrade tout seul.
+- **Dernier admin global (nouveau, #345)** : "l'instance doit toujours avoir au moins un admin". S'applique meme si ce n'est pas l'operation d'un admin sur lui-meme (admin A degrade admin B alors qu'ils sont les deux seuls).
+
+Ordre d'evaluation dans `UserRbacProcessor` :
+
+```text
+1. Garde auto-suicide (cas particulier, message dedie)
+2. Garde dernier admin global (cas general, message dedie)
+3. Persist
+```
+
+Les messages d'erreur distincts aident le front a afficher le bon feedback utilisateur. Le test `UserRbacProcessorTest` doit couvrir les deux branches.
+
+### Cas limite : l'admin se degrade lui-meme ET il est le dernier
+
+Les deux gardes s'appliqueraient. Comme auto-suicide est evalue en premier, c'est son message qui est retourne ("Vous ne pouvez pas retirer vos propres droits administrateur."). Comportement acceptable et coherent : le user voit d'abord la regle la plus specifique.
+
+## 8. /api/me enrichi - contrat
+
+Payload avant :
+```json
+{
+  "@context": "/api/contexts/User",
+  "@id": "/api/users/5",
+  "@type": "User",
+  "id": 5,
+  "username": "admin",
+  "isAdmin": true
+}
+```
+
+Payload apres :
+```json
+{
+  "@context": "/api/contexts/User",
+  "@id": "/api/users/5",
+  "@type": "User",
+  "id": 5,
+  "username": "admin",
+  "isAdmin": true,
+  "effectivePermissions": [
+    "core.permissions.view",
+    "core.roles.manage",
+    "core.roles.view",
+    "core.users.manage",
+    "core.users.view"
+  ]
+}
+```
+
+Contrat :
+- `effectivePermissions` est toujours un tableau de strings (jamais `null`).
+- L'ordre est deterministe (trie alphabetique — implementation existante du #343).
+- Aucun doublon.
+- Pour un admin, le tableau contient les permissions effectives (non vides si le role `admin` a des permissions OU si l'user a des directPermissions, vide sinon). **Le bypass ne se refletera PAS dans ce tableau** : `isAdmin: true` reste la source de verite du bypass. Le front l'utilise en priorite dans le composable.
+
+### Pourquoi le bypass n'est pas materialise dans `effectivePermissions`
+
+Mettre "toutes les permissions connues" dans le tableau pour les admins serait tentant mais faux :
+- il faudrait enumerer dynamiquement toutes les permissions de tous les modules actifs, ce qui recouvre la responsabilite de `app:sync-permissions`,
+- le tableau gonflerait inutilement le payload `/api/me` a chaque requete,
+- et surtout il deviendrait faux si un module declare une nouvelle permission apres une execution de sync : l'admin aurait temporairement un tableau incomplet alors que son bypass reste effectif.
+
+La source de verite du bypass est `isAdmin: boolean`. Le composable front regarde ce flag en premier.
+
+## 9. usePermissions - composable front
+
+### API publique
+
+```ts
+export function usePermissions() {
+  const auth = useAuthStore()
+
+  // Verifie si l'utilisateur courant a la permission demandee.
+  // Bypass automatique si isAdmin = true, coherent avec PermissionVoter cote back.
+  const can = (code: string): boolean => {
+    const user = auth.user
+    if (!user) return false
+    if (user.isAdmin) return true
+    return user.effectivePermissions.includes(code)
+  }
+
+  const canAny = (codes: string[]): boolean => codes.some(can)
+  const canAll = (codes: string[]): boolean => codes.every(can)
+
+  return { can, canAny, canAll }
+}
+```
+
+### Proprietes
+
+- **Stateless** : aucun `ref` module-level, aucune reactivite dediee. Tout passe par `useAuthStore().user` qui est deja reactif via Pinia.
+- **Aucun fetch propre** : les permissions arrivent par `/api/me` au login (via `useAuthStore().ensureSession()` ou `.login()`), aucun appel supplementaire n'est necessaire.
+- **Aucun reset** : le logout efface deja `authStore.user`, donc `can()` retombe naturellement a `false`.
+- **Bypass synchrone avec le back** : la regle `if (user.isAdmin) return true` duplique deliberement le bypass du `PermissionVoter` cote back. Commentaire francais dans le composable pour rappeler que les deux doivent bouger ensemble si la regle change un jour.
+
+### Pas de variante `can` reactive (computed)
+
+Utiliser `computed(() => can('core.users.view'))` dans un composant fonctionne automatiquement puisque `auth.user` est reactif Pinia — Vue re-evalue le computed quand `user` change. Pas besoin d'API supplementaire du composable pour ca.
+
+## 10. Validation
+
+Aucune nouvelle contrainte Symfony Validator introduite par ce ticket. Les gardes metier (`AdminHeadcountGuard`, `SystemRoleDeletionException`, auto-suicide) vivent dans les processors et le domaine, pas dans la couche Validator.
+
+## 11. Plan de tests
+
+### Unitaires PHP
+
+**`PermissionVoterTest`**
+
+- `supports('core.users.view')` retourne `true`.
+- `supports('ROLE_ADMIN')` retourne `false` (n'interfere pas avec les voters core).
+- `supports('IS_AUTHENTICATED_FULLY')` retourne `false`.
+- `supports('invalid attribute')` retourne `false` (espace, majuscule).
+- `voteOnAttribute` avec un `User` admin retourne GRANTED quelle que soit la permission.
+- `voteOnAttribute` avec un user portant la permission retourne GRANTED.
+- `voteOnAttribute` avec un user ne portant pas la permission retourne DENIED.
+- `voteOnAttribute` avec un token non-authentifie (user null) retourne DENIED.
+
+**`AdminHeadcountGuardTest`**
+
+- `ensureAtLeastOneAdminRemainsAfterDemotion` : `countAdmins == 2` → OK.
+- Meme methode : `countAdmins == 1` → `LastAdminProtectionException`.
+- Meme methode : `countAdmins == 0` → leve aussi (garde defensive).
+- `ensureAtLeastOneAdminRemainsAfterDeletion` : memes 3 cas, memes resultats.
+- `UserRepositoryInterface::countAdmins()` est mockee avec une valeur fixe pour chaque cas (test unitaire isole, pas d'acces BDD).
+
+**`UserProcessorTest`**
+
+- `process()` sur un user non-admin en DELETE delegue au `RemoveProcessor`.
+- `process()` sur un user admin en DELETE avec `countAdmins() > 1` delegue.
+- `process()` sur un user admin en DELETE avec `countAdmins() == 1` leve `BadRequestHttpException` (traduction de `LastAdminProtectionException`).
+- `process()` avec `$data` non-`User` leve `LogicException` (fail-fast coherent avec `UserRbacProcessor` / `RoleProcessor`).
+
+**`UserRbacProcessorTest` (extension)**
+
+- Cas existants auto-suicide : gardes en l'etat.
+- Nouveau : PATCH RBAC par admin A sur admin B, `isAdmin: false`, `countAdmins() == 1` (apres perte = 0) → `BadRequestHttpException` "dernier admin".
+- Nouveau : meme operation avec `countAdmins() == 2` → delegue au persist processor.
+- Nouveau : PATCH RBAC qui ne touche pas `isAdmin` (change juste `roles` ou `directPermissions`) ne consulte jamais le guard, meme si `countAdmins() == 1`.
+
+### Fonctionnels API PHP (`AbstractApiTestCase`)
+
+Pour les 3 ressources (`Permission`, `Role`, `User`), pour chaque operation, 3 cas :
+
+1. Admin → succes (confirme que le voter bypass fonctionne).
+2. User standard **avec** la permission requise (attachee via fixture dediee) → succes.
+3. User standard **sans** la permission → `403`.
+
+**Fixtures de test** : ajouter des users "portant une permission specifique" n'est pas souhaitable dans `AppFixtures` (fixtures de dev). Creer a la place un trait ou une helper method `AbstractApiTestCase::createUserWithPermission(string $code): User` qui instancie a la volee un user + un role + l'attache dans le test lui-meme, transactionne si `DAMADoctrineTestBundle` est en place.
+
+**Cas specifiques a ajouter** :
+
+- `UserRbacApiTest` : PATCH `/api/users/{lastAdminId}/rbac` avec `isAdmin: false` par un **autre** admin → `400` avec message "dernier admin" (et pas "auto-suicide").
+- `UserApiTest` (nouveau ou extension) : DELETE `/api/users/{lastAdminId}` par un autre admin → `400` avec message "dernier admin".
+- `UserApiTest` : DELETE `/api/users/{nonAdminId}` fonctionne quel que soit le count (la garde ne doit pas etre appelee).
+- `MeApiTest` : `GET /api/me` en tant qu'admin retourne `effectivePermissions` (tableau, meme vide si pas de role populaire).
+- `MeApiTest` : `GET /api/me` en tant que user standard retourne `effectivePermissions` = list triee des codes issus de ses roles et directPermissions.
+
+### Tests frontend (Vitest)
+
+**`usePermissions.test.ts`**
+
+- Utilisateur null → `can()` retourne `false` pour n'importe quel code.
+- Utilisateur admin → `can('core.users.view')` retourne `true` meme si `effectivePermissions` est vide.
+- Utilisateur non-admin avec `['core.users.view']` → `can('core.users.view')` = `true`, `can('core.users.manage')` = `false`.
+- `canAny(['a', 'b'])` retourne `true` si l'un des deux matche, `false` sinon.
+- `canAll(['a', 'b'])` retourne `true` uniquement si les deux matchent.
+
+Convention de test frontend a valider avant : si le projet Nuxt a deja un setup Vitest, on s'y aligne ; sinon on note une TODO pour ajouter la conf (sans bloquer le ticket — le composable est assez simple pour etre revu manuellement).
+
+## 12. Securite et traduction d'exceptions
+
+- `LastAdminProtectionException` (domaine) → `BadRequestHttpException` (400) dans les processors. Message francais : "Impossible : au moins un administrateur doit rester sur l'instance."
+- `SystemRoleDeletionException` (existante) → traduction inchangee par le #344, rien a modifier.
+- Auto-suicide existante → message inchange : "Vous ne pouvez pas retirer vos propres droits administrateur."
+- Pas de listener global : traduction locale dans chaque processor, coherent avec le pattern du #344.
+
+## 13. Conventions et architecture
+
+- Respect strict du modular monolith : tous les fichiers crees vivent dans `src/Module/Core/`, `tests/Module/Core/`, ou `frontend/shared/`. Aucun import inter-modules.
+- `declare(strict_types=1)` en tete de tous les nouveaux fichiers PHP.
+- Commentaires PHP et TS en francais, identifiants en anglais (`CLAUDE.md`).
+- Autoconfigure Symfony detecte `PermissionVoter` via `VoterInterface`. `AdminHeadcountGuard` est autowire via son constructeur standard.
+- Les processors suivent le pattern du #344 : `final class`, `#[Autowire]` sur l'inner, `LogicException` fail-fast sur type invalide.
+- Aucune entree necessaire dans `config/modules.php` ni `config/sidebar.php`.
+- Aucune migration Doctrine : le catalogue de permissions est synchronise par `app:sync-permissions` (commande existante #343), pas par une migration.
+
+## 14. Ordre d'execution recommande (subagent-driven)
+
+1. **Catalogue** — ajouter `core.roles.view` dans `CoreModule::permissions()`. Executer `app:sync-permissions` en local pour verifier l'ajout. Pas de test propre (couvert indirectement par les tests sync existants du #343).
+2. **Guard domaine** — creer `LastAdminProtectionException`, ajouter `UserRepositoryInterface::countAdmins()` + impl Doctrine, creer `AdminHeadcountGuard`. Ecrire `AdminHeadcountGuardTest`.
+3. **PermissionVoter** — implementation + `PermissionVoterTest`. Verifier via `make test` que l'auth standard reste verte (aucune regression sur `ROLE_*`).
+4. **UserProcessor DELETE** — creer le processor, wire sur l'operation `Delete` de `User`. Ecrire `UserProcessorTest`.
+5. **UserRbacProcessor extension** — injecter `AdminHeadcountGuard`, brancher apres la garde auto-suicide. Etendre `UserRbacProcessorTest` avec les nouveaux cas.
+6. **Remplacement des 13 gardes ROLE_ADMIN** — modifier `Permission`, `Role`, `User`. Supprimer tous les `// TODO ticket #345`.
+7. **`/api/me` enrichi** — ajouter `#[Groups(['me:read'])]` sur `getEffectivePermissions()`. Creer ou etendre `MeApiTest`.
+8. **Tests fonctionnels RBAC complets** — helper `createUserWithPermission()` dans `AbstractApiTestCase`, puis couverture 403 non-admin / 200 avec permission sur toutes les operations RBAC des 3 ressources. Cas "dernier admin global" PATCH et DELETE.
+9. **Frontend types + composable** — etendre `UserData`, creer `usePermissions.ts`, ecrire le test Vitest.
+10. **Verification finale** — `make test` vert, `make php-cs-fixer-allow-risky` sans delta, build Nuxt OK si modifie.
+
+Chaque etape doit etre revue (spec compliance + code quality) avant de passer a la suivante, pattern subagent-driven-development retenu pour le #344.
+
+## 15. Risques et points d'attention
+
+- **Ordre des voters Symfony** : `PermissionVoter` ne vote jamais sur `ROLE_*` grace au regex de support. Risque quasi-nul d'interference avec `RoleVoter`/`AuthenticatedVoter`, a valider par un test fonctionnel `/login_check` + `GET /api/me` apres ajout du voter.
+- **Serialisation de `getEffectivePermissions()` via API Platform** : la methode existe depuis le #343 mais n'a jamais ete sous serializer. Risque de rencontrer un `ReflectionException` si le nom de propriete deduit ne matche pas (cas rare, API Platform gere les getters normalement). Mitigation : test fonctionnel `/api/me` en premiere validation.
+- **Cout SQL de `countAdmins()`** : 1 `COUNT(*)` par operation de mutation admin sensible. Index recommande sur `user.is_admin` (`idx_user_is_admin`) — a verifier si la migration #343 l'a deja cree. Si non, c'est un ajustement cosmetique qu'on peut reporter puisque la table `user` d'un CRM PME reste petite (< 1000 lignes).
+- **Bypass front/back desynchronise** : si un jour le bypass admin est affine cote back (ex: seulement sur certains modules), le composable front doit bouger en meme temps. Mitigation : commentaire francais explicite dans `usePermissions.ts` pointant vers cette spec.
+- **Tests fonctionnels et fixtures RBAC** : le #344 a introduit `AbstractApiTestCase`, mais les users de test portant une permission specifique (hors admin/user standard) n'existent pas dans les fixtures. Creer une helper `createUserWithPermission()` transactionnelle dans la classe de test, plutot que polluer `AppFixtures` avec des users de test dedies.
+- **Ordre d'evaluation auto-suicide vs dernier admin** : les deux gardes pourraient etre declenchees simultanement (admin unique qui se degrade lui-meme). L'auto-suicide gagne en premier par design. A couvrir explicitement par un test.
+- **Payload `/api/me` plus gros** : l'ajout de `effectivePermissions` alourdit chaque requete `/api/me`. Pour 5 permissions aujourd'hui c'est negligeable, mais si le catalogue grossit fortement (50+ permissions reparties sur plusieurs modules), il faudra peut-etre filtrer cote serveur (ne retourner que les permissions utiles au contexte front). Hors scope, mais a noter pour suivi.
+- **`UserData` partagee entre auth store et composable** : toute modification future de la shape `UserData` peut impacter `usePermissions`. Rester minimal dans le composable et laisser Pinia porter la verite.
+
+## 16. Criteres d'acceptation (DoD)
+
+- Le catalogue `CoreModule::permissions()` contient 5 entrees incluant `core.roles.view`.
+- `PermissionVoter` existe, supporte uniquement les attributs au format `module.resource.action`, bypass admin effectif, test unitaire complet.
+- Les 13 operations API Platform du perimetre RBAC sont toutes gardees par un code metier `core.*.*` et plus par `ROLE_ADMIN`. Les commentaires `// TODO ticket #345` ont disparu du code.
+- `AdminHeadcountGuard` existe comme service domaine, est consomme par `UserRbacProcessor` ET `UserProcessor`, teste en isolation.
+- `UserRepositoryInterface::countAdmins()` existe et est implementee.
+- `UserProcessor` intercepte `DELETE /api/users/{id}` et bloque la suppression du dernier admin avec un message explicite.
+- `UserRbacProcessor` bloque la demotion du dernier admin global (en plus de la garde auto-suicide existante) avec un message distinct.
+- `GET /api/me` retourne `effectivePermissions: string[]` et `isAdmin: boolean` dans son payload.
+- `frontend/shared/composables/usePermissions.ts` expose `can`, `canAny`, `canAll`, stateless, bypasse si `isAdmin`.
+- `frontend/shared/types/user-data.ts` inclut `isAdmin` et `effectivePermissions`.
+- Tests unitaires PHP : `PermissionVoterTest`, `AdminHeadcountGuardTest`, `UserProcessorTest`, extension `UserRbacProcessorTest` — tous verts.
+- Tests fonctionnels API : couverture 403 non-admin / 200 admin-ou-porteur sur chaque operation RBAC des 3 ressources, cas dernier admin PATCH et DELETE, `/api/me` enrichi.
+- Test Vitest `usePermissions.test.ts` vert (ou TODO documentee si setup Vitest absent du projet).
+- `make test` passe ; `make php-cs-fixer-allow-risky` ne laisse aucun delta.
+- Aucun import croise entre modules ; tous les fichiers PHP crees vivent dans `Module/Core/` ou `tests/Module/Core/`, tous les fichiers front dans `frontend/shared/`.
+- Le spec est mergee avec le code (meme PR #3 empilee sur `feat/rbac-api`) pour rester la reference du ticket.
+
+## 17. Remarques de branche
+
+- Branche de travail : `feat/rbac-voter`, tiree de `feat/rbac-api`.
+- Pas de PR dediee : les commits #345 s'empilent sur la PR #3 existante ouverte vers `develop`.
+- Une fois la PR #3 mergee, la branche finale de l'epic RBAC (`feat/rbac-admin-ui` pour #346) partira de `develop`.
--- a/phpunit.dist.xml
+++ b/phpunit.dist.xml
@@ -15,6 +15,7 @@
        <ini name="error_reporting" value="-1" />
        <server name="APP_ENV" value="test" force="true" />
        <server name="SHELL_VERBOSITY" value="-1" />
+        <server name="KERNEL_CLASS" value="App\Kernel" />
    </php>

    <testsuites>
--- a/src/Module/Core/CoreModule.php
+++ b/src/Module/Core/CoreModule.php
@@ -32,8 +32,9 @@ final class CoreModule
        return [
            ['code' => 'core.users.view', 'label' => 'Voir les utilisateurs'],
            ['code' => 'core.users.manage', 'label' => 'Gerer les utilisateurs (creer, editer, supprimer)'],
+            ['code' => 'core.roles.view', 'label' => 'Voir les roles RBAC'],
            ['code' => 'core.roles.manage', 'label' => 'Gerer les roles et permissions'],
-            ['code' => 'core.permissions.view', 'label' => 'Voir la liste des permissions'],
+            ['code' => 'core.permissions.view', 'label' => 'Voir le catalogue des permissions'],
        ];
    }
 }
--- a/src/Module/Core/Domain/Entity/Permission.php
+++ b/src/Module/Core/Domain/Entity/Permission.php
@@ -4,10 +4,33 @@ declare(strict_types=1);

 namespace App\Module\Core\Domain\Entity;

+use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
+use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
 use App\Module\Core\Infrastructure\Doctrine\DoctrinePermissionRepository;
 use Doctrine\ORM\Mapping as ORM;
 use InvalidArgumentException;
+use Symfony\Component\Serializer\Attribute\Groups;

+#[ApiResource(
+    operations: [
+        new GetCollection(
+            normalizationContext: ['groups' => ['permission:read']],
+            // TODO ticket #345 : remplacer par is_granted('core.permissions.view')
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+        new Get(
+            normalizationContext: ['groups' => ['permission:read']],
+            // TODO ticket #345 : remplacer par is_granted('core.permissions.view')
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+    ],
+)]
+#[ApiFilter(SearchFilter::class, properties: ['module' => 'exact'])]
+#[ApiFilter(BooleanFilter::class, properties: ['orphan'])]
 #[ORM\Entity(repositoryClass: DoctrinePermissionRepository::class)]
 #[ORM\Table(name: 'permission')]
 #[ORM\UniqueConstraint(name: 'uniq_permission_code', columns: ['code'])]
@@ -18,18 +41,23 @@ class Permission
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
+    #[Groups(['permission:read'])]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
+    #[Groups(['permission:read'])]
    private string $code;

    #[ORM\Column(length: 255)]
+    #[Groups(['permission:read'])]
    private string $label;

    #[ORM\Column(length: 100)]
+    #[Groups(['permission:read'])]
    private string $module;

    #[ORM\Column(options: ['default' => false])]
+    #[Groups(['permission:read'])]
    private bool $orphan = false;

    /**
--- a/src/Module/Core/Domain/Entity/Role.php
+++ b/src/Module/Core/Domain/Entity/Role.php
@@ -4,12 +4,25 @@ declare(strict_types=1);

 namespace App\Module\Core\Domain\Entity;

+use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
 use App\Module\Core\Domain\Exception\SystemRoleDeletionException;
+use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\RoleProcessor;
 use App\Module\Core\Infrastructure\Doctrine\DoctrineRoleRepository;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\DBAL\Types\Types;
 use Doctrine\ORM\Mapping as ORM;
+use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+use Symfony\Component\Serializer\Attribute\Groups;
+use Symfony\Component\Serializer\Attribute\SerializedName;
+use Symfony\Component\Validator\Constraints as Assert;

 /**
 * Role RBAC : groupe nomme de permissions assignable a un utilisateur.
@@ -18,27 +31,75 @@ use Doctrine\ORM\Mapping as ORM;
 * "personnalise" (cree par un administrateur). Seuls les roles personnalises
 * peuvent etre supprimes.
 */
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            normalizationContext: ['groups' => ['role:read']],
+            // TODO ticket #345 : remplacer par is_granted('core.roles.manage')
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+        new Get(
+            normalizationContext: ['groups' => ['role:read']],
+            // TODO ticket #345 : remplacer par is_granted('core.roles.manage')
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+        new Post(
+            normalizationContext: ['groups' => ['role:read']],
+            denormalizationContext: ['groups' => ['role:write']],
+            // TODO ticket #345 : remplacer par is_granted('core.roles.manage')
+            security: "is_granted('ROLE_ADMIN')",
+            processor: RoleProcessor::class,
+        ),
+        new Patch(
+            normalizationContext: ['groups' => ['role:read']],
+            denormalizationContext: ['groups' => ['role:write']],
+            // TODO ticket #345 : remplacer par is_granted('core.roles.manage')
+            security: "is_granted('ROLE_ADMIN')",
+            processor: RoleProcessor::class,
+        ),
+        new Delete(
+            // TODO ticket #345 : remplacer par is_granted('core.roles.manage')
+            security: "is_granted('ROLE_ADMIN')",
+            processor: RoleProcessor::class,
+        ),
+    ],
+    normalizationContext: ['groups' => ['role:read']],
+    denormalizationContext: ['groups' => ['role:write']],
+)]
+#[ApiFilter(BooleanFilter::class, properties: ['isSystem'])]
 #[ORM\Entity(repositoryClass: DoctrineRoleRepository::class)]
 #[ORM\Table(name: '`role`')]
 #[ORM\UniqueConstraint(name: 'uniq_role_code', columns: ['code'])]
 #[ORM\Index(name: 'idx_role_is_system', columns: ['is_system'])]
+#[UniqueEntity(fields: ['code'], message: 'Un role avec ce code existe deja.')]
 class Role
 {
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
+    #[Groups(['role:read'])]
    private ?int $id = null;

    #[ORM\Column(length: 100)]
+    #[Groups(['role:read', 'role:write'])]
+    #[Assert\NotBlank]
+    #[Assert\Regex(pattern: '/^[a-z][a-z0-9_]*$/', message: 'Le code doit etre en snake_case et commencer par une lettre minuscule.')]
    private string $code;

    #[ORM\Column(length: 255)]
+    #[Groups(['role:read', 'role:write'])]
+    #[Assert\NotBlank]
    private string $label;

    #[ORM\Column(type: Types::TEXT, nullable: true)]
+    #[Groups(['role:read', 'role:write'])]
    private ?string $description = null;

+    // Volontairement exclu du groupe `role:write` : un client ne doit jamais
+    // pouvoir positionner ce flag via l'API. Seules les fixtures et migrations
+    // creent les roles systeme.
    #[ORM\Column(name: 'is_system', options: ['default' => false])]
+    #[Groups(['role:read'])]
    private bool $isSystem = false;

    /** @var Collection<int, Permission> */
@@ -53,6 +114,7 @@ class Role
    //   projection cachee (ticket a ouvrir a ce moment-la).
    #[ORM\ManyToMany(targetEntity: Permission::class, fetch: 'EAGER')]
    #[ORM\JoinTable(name: 'role_permission')]
+    #[Groups(['role:read', 'role:write'])]
    private Collection $permissions;

    public function __construct(string $code, string $label, bool $isSystem = false, ?string $description = null)
@@ -84,6 +146,12 @@ class Role
        return $this->description;
    }

+    // Le getter est annote directement car la convention Symfony PropertyInfo
+    // strip le prefixe `is` et exposerait le champ sous le nom `system`. On
+    // pose donc un SerializedName explicite pour garantir la sortie JSON-LD
+    // sous `isSystem`, nom attendu par les clients de l'API.
+    #[Groups(['role:read'])]
+    #[SerializedName('isSystem')]
    public function isSystem(): bool
    {
        return $this->isSystem;
@@ -95,6 +163,23 @@ class Role
        return $this->permissions;
    }

+    /**
+     * Setter expose uniquement a la denormalisation API Platform pour
+     * permettre au RoleProcessor de detecter une tentative de modification
+     * du code (garde "code immuable"). Le code reste en pratique fige apres
+     * creation : le processor refuse toute modification via 400.
+     *
+     * @internal Ne PAS appeler depuis le domaine, les fixtures ou les commandes.
+     *           Hors contexte API Platform, cette methode modifie silencieusement
+     *           le code sans aucun garde.
+     */
+    public function setCode(string $code): static
+    {
+        $this->code = $code;
+
+        return $this;
+    }
+
    /**
     * Met a jour le libelle affichable du role. Le code reste immuable pour
     * garantir la stabilite des references cote fixtures et migrations.
--- a/src/Module/Core/Domain/Entity/User.php
+++ b/src/Module/Core/Domain/Entity/User.php
@@ -11,6 +11,7 @@ use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Patch;
 use ApiPlatform\Metadata\Post;
 use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\UserPasswordHasherProcessor;
+use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\UserRbacProcessor;
 use App\Module\Core\Infrastructure\ApiPlatform\State\Provider\MeProvider;
 use App\Module\Core\Infrastructure\Doctrine\DoctrineUserRepository;
 use DateTimeImmutable;
@@ -20,6 +21,7 @@ use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Component\Serializer\Attribute\Groups;
+use Symfony\Component\Serializer\Attribute\SerializedName;

 #[ApiResource(
    operations: [
@@ -29,13 +31,24 @@ use Symfony\Component\Serializer\Attribute\Groups;
            normalizationContext: ['groups' => ['me:read']],
        ),
        new Get(
+            security: "is_granted('ROLE_ADMIN')",  // TODO ticket #345 : remplacer par is_granted('core.users.view')
            normalizationContext: ['groups' => ['user:list']],
        ),
        new GetCollection(
+            security: "is_granted('ROLE_ADMIN')",  // TODO ticket #345 : remplacer par is_granted('core.users.view')
            normalizationContext: ['groups' => ['user:list']],
        ),
        new Post(security: "is_granted('ROLE_ADMIN')", processor: UserPasswordHasherProcessor::class),
        new Patch(security: "is_granted('ROLE_ADMIN')", processor: UserPasswordHasherProcessor::class),
+        new Patch(
+            name: 'user_rbac_patch',
+            uriTemplate: '/users/{id}/rbac',
+            // TODO ticket #345 : remplacer par is_granted('core.users.manage')
+            security: "is_granted('ROLE_ADMIN')",
+            normalizationContext: ['groups' => ['user:rbac:read']],
+            denormalizationContext: ['groups' => ['user:rbac:write']],
+            processor: UserRbacProcessor::class,
+        ),
        new Delete(security: "is_granted('ROLE_ADMIN')"),
    ],
    denormalizationContext: ['groups' => ['user:write']],
@@ -47,7 +60,7 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
-    #[Groups(['me:read', 'user:list'])]
+    #[Groups(['me:read', 'user:list', 'user:rbac:read'])]
    private ?int $id = null;

    #[ORM\Column(length: 180, unique: true)]
@@ -55,7 +68,7 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
    private ?string $username = null;

    #[ORM\Column(name: 'is_admin', options: ['default' => false])]
-    #[Groups(['me:read', 'user:list'])]
+    #[Groups(['me:read', 'user:list', 'user:rbac:write', 'user:rbac:read'])]
    private bool $isAdmin = false;

    /**
@@ -70,20 +83,25 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
     */
    #[ORM\ManyToMany(targetEntity: Role::class, fetch: 'EAGER')]
    #[ORM\JoinTable(name: 'user_role')]
-    #[Groups(['me:read', 'user:list'])]
-    private Collection $roles;
+    #[Groups(['me:read', 'user:list', 'user:rbac:write', 'user:rbac:read'])]
+    // La propriete s'appelle `rbacRoles` cote PHP pour ne pas entrer en
+    // collision avec UserInterface::getRoles() (qui renvoie list<string>) ;
+    // on reexpose la cle JSON sous `roles` via SerializedName pour rester
+    // conforme au contrat API documente dans le ticket #344.
+    #[SerializedName('roles')]
+    private Collection $rbacRoles;

    /**
     * Les permissions directes accordees hors des roles.
     *
-     * Meme justification EAGER que pour $roles : garantie que
+     * Meme justification EAGER que pour $rbacRoles : garantie que
     * getEffectivePermissions() fonctionne dans tous les contextes de chargement.
     *
     * @var Collection<int, Permission>
     */
    #[ORM\ManyToMany(targetEntity: Permission::class, fetch: 'EAGER')]
    #[ORM\JoinTable(name: 'user_permission')]
-    #[Groups(['me:read', 'user:list'])]
+    #[Groups(['me:read', 'user:list', 'user:rbac:write', 'user:rbac:read'])]
    private Collection $directPermissions;

    #[ORM\Column]
@@ -98,7 +116,7 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
    public function __construct()
    {
        $this->createdAt         = new DateTimeImmutable();
-        $this->roles             = new ArrayCollection();
+        $this->rbacRoles         = new ArrayCollection();
        $this->directPermissions = new ArrayCollection();
    }

@@ -131,10 +149,12 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
     * ROLE_ADMIN est ajoute si l'utilisateur porte le flag is_admin — c'est le
     * SEUL levier technique de bypass RBAC (cf. section 11 du spec).
     *
-     * Important : ne JAMAIS iterer $this->roles (la Collection de Role) ici.
-     * Cette methode peut etre appelee pendant un refresh JWT, moment ou la
-     * Collection peut ne pas etre hydratee. On se contente d'un calcul base
-     * sur un scalaire.
+     * Important : ne JAMAIS iterer $this->rbacRoles (la Collection de Role)
+     * ici. Cette methode peut etre appelee pendant un refresh JWT, moment ou
+     * la Collection peut ne pas etre hydratee. On se contente d'un calcul
+     * base sur un scalaire.
+     *
+     * @see getRbacRoles() pour la collection RBAC metier (exposee en JSON sous la cle "roles").
     *
     * @return list<string>
     */
@@ -170,13 +190,13 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
     */
    public function getRbacRoles(): Collection
    {
-        return $this->roles;
+        return $this->rbacRoles;
    }

    public function addRbacRole(Role $role): static
    {
-        if (!$this->roles->contains($role)) {
-            $this->roles->add($role);
+        if (!$this->rbacRoles->contains($role)) {
+            $this->rbacRoles->add($role);
        }

        return $this;
@@ -184,7 +204,7 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface

    public function removeRbacRole(Role $role): static
    {
-        $this->roles->removeElement($role);
+        $this->rbacRoles->removeElement($role);

        return $this;
    }
@@ -229,7 +249,7 @@ class User implements UserInterface, PasswordAuthenticatedUserInterface
    {
        $codes = [];

-        foreach ($this->roles as $role) {
+        foreach ($this->rbacRoles as $role) {
            foreach ($role->getPermissions() as $permission) {
                $codes[$permission->getCode()] = true;
            }
--- a/src/Module/Core/Domain/Exception/LastAdminProtectionException.php
+++ b/src/Module/Core/Domain/Exception/LastAdminProtectionException.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Exception;
+
+use DomainException;
+
+/**
+ * Levee lorsqu'une operation mettrait fin a la presence d'au moins un
+ * administrateur sur l'instance.
+ *
+ * L'invariant "au moins un admin doit exister" est protege au niveau du
+ * domaine afin qu'aucun flux (API, CLI, import) ne puisse le contourner.
+ * La traduction HTTP (422 ou 403) est laissee a la couche infrastructure.
+ */
+final class LastAdminProtectionException extends DomainException
+{
+    /**
+     * Construit l'exception avec un message par defaut ou un message fourni par l'appelant.
+     */
+    public function __construct(string $message = 'Impossible : au moins un administrateur doit rester sur l\'instance.')
+    {
+        parent::__construct($message);
+    }
+}
--- a/src/Module/Core/Domain/Repository/UserRepositoryInterface.php
+++ b/src/Module/Core/Domain/Repository/UserRepositoryInterface.php
@@ -13,4 +13,12 @@ interface UserRepositoryInterface
    public function findByUsername(string $username): ?User;

    public function save(User $user): void;
+
+    /**
+     * Retourne le nombre d'utilisateurs ayant le flag isAdmin a true.
+     *
+     * Utilise par AdminHeadcountGuard pour verifier l'invariant
+     * "au moins un administrateur doit rester sur l'instance".
+     */
+    public function countAdmins(): int;
 }
--- a/src/Module/Core/Domain/Security/AdminHeadcountGuard.php
+++ b/src/Module/Core/Domain/Security/AdminHeadcountGuard.php
@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Security;
+
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Core\Domain\Exception\LastAdminProtectionException;
+use App\Module\Core\Domain\Repository\UserRepositoryInterface;
+
+/**
+ * Gardien de l'invariant domaine : l'instance doit toujours conserver
+ * au moins un utilisateur administrateur.
+ *
+ * Ce service est appele avant toute operation susceptible de reduire le
+ * nombre d'admins (retrait du flag isAdmin, suppression d'un utilisateur).
+ * Il compte les admins restants et leve LastAdminProtectionException si
+ * le seuil minimum (1) serait franchi.
+ */
+final class AdminHeadcountGuard
+{
+    public function __construct(private readonly UserRepositoryInterface $userRepository) {}
+
+    /**
+     * Verifie qu'il restera au moins un admin apres la demote de $user.
+     *
+     * L'argument $user est accepte mais non utilise dans la logique de comptage :
+     * l'appelant a deja determine que cet utilisateur va perdre son statut admin ;
+     * le garde se contente de verifier qu'il en reste au moins un autre.
+     * Le parametre est conserve pour la lisibilite du site d'appel et pour
+     * permettre une evolution future (ex : journalisation, audit trail).
+     */
+    public function ensureAtLeastOneAdminRemainsAfterDemotion(User $user): void
+    {
+        $this->checkAdminHeadcount();
+    }
+
+    /**
+     * Verifie qu'il restera au moins un admin apres la suppression de $user.
+     *
+     * Meme principe que ensureAtLeastOneAdminRemainsAfterDemotion() : $user
+     * est accepte pour la symetrie du contrat et les evolutions futures,
+     * mais le comptage ne depend pas de son identite.
+     */
+    public function ensureAtLeastOneAdminRemainsAfterDeletion(User $user): void
+    {
+        $this->checkAdminHeadcount();
+    }
+
+    /**
+     * Compte les administrateurs et leve une exception si le seuil minimum est atteint.
+     *
+     * La verification est volontairement conservative (<=1) pour couvrir
+     * le cas defensif ou la base serait deja dans un etat incoherent (0 admin).
+     *
+     * @throws LastAdminProtectionException si le nombre d'admins est inferieur ou egal a 1
+     */
+    private function checkAdminHeadcount(): void
+    {
+        if ($this->userRepository->countAdmins() <= 1) {
+            throw new LastAdminProtectionException();
+        }
+    }
+}
--- a/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessor.php
+++ b/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessor.php
@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Infrastructure\ApiPlatform\State\Processor;
+
+use ApiPlatform\Metadata\DeleteOperationInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Exception\SystemRoleDeletionException;
+use Doctrine\ORM\EntityManagerInterface;
+use LogicException;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+/**
+ * Processor applicatif pour l'entite Role.
+ *
+ * Choix d'implementation : une seule classe qui recoit en dependances les deux
+ * processors Doctrine decores (Persist et Remove) et branche l'un ou l'autre
+ * selon le type d'operation. Ce choix reste plus lisible que deux classes
+ * jumelees et reflete la symetrie des gardes metier (immuabilite du `code`
+ * cote ecriture, protection des roles systeme cote suppression).
+ *
+ * Gardes metier :
+ *  - DELETE : delegue a Role::ensureDeletable() et traduit la
+ *    SystemRoleDeletionException en AccessDeniedHttpException (403).
+ *  - POST/PATCH : refuse toute modification du `code` (champ immuable apres
+ *    creation), regle uniforme pour les roles systeme ET custom.
+ *
+ * @implements ProcessorInterface<Role, null|Role>
+ */
+final class RoleProcessor implements ProcessorInterface
+{
+    public function __construct(
+        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
+        private readonly ProcessorInterface $persistProcessor,
+        #[Autowire(service: 'api_platform.doctrine.orm.state.remove_processor')]
+        private readonly ProcessorInterface $removeProcessor,
+        private readonly EntityManagerInterface $entityManager,
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    {
+        if (!$data instanceof Role) {
+            // Ce processor est wire exclusivement sur les operations Role.
+            // Si on arrive ici avec autre chose, c'est une misconfiguration
+            // qu'il faut faire remonter fort.
+            throw new LogicException(sprintf(
+                'RoleProcessor attend une instance de %s, %s recu.',
+                Role::class,
+                get_debug_type($data),
+            ));
+        }
+
+        if ($operation instanceof DeleteOperationInterface) {
+            try {
+                $data->ensureDeletable();
+            } catch (SystemRoleDeletionException $e) {
+                // Traduction HTTP : le domaine reste pur, l'API renvoie 403.
+                throw new AccessDeniedHttpException($e->getMessage(), $e);
+            }
+
+            return $this->removeProcessor->process($data, $operation, $uriVariables, $context);
+        }
+
+        // Ecriture (POST/PATCH) : verifier l'immuabilite du `code`.
+        // L'UnitOfWork n'expose un etat d'origine que pour les entites deja
+        // managees (PATCH). Pour un POST (entite nouvelle), `getOriginalEntityData`
+        // retourne un tableau vide : aucune comparaison necessaire.
+        $originalData = $this->entityManager->getUnitOfWork()->getOriginalEntityData($data);
+
+        if (isset($originalData['code']) && $originalData['code'] !== $data->getCode()) {
+            throw new BadRequestHttpException("Le code d'un role est immuable apres creation.");
+        }
+
+        return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
+    }
+}
--- a/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php
+++ b/src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Infrastructure\ApiPlatform\State\Processor;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\Module\Core\Domain\Entity\User;
+use Doctrine\ORM\EntityManagerInterface;
+use LogicException;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+/**
+ * Processor dedie a l'endpoint RBAC `PATCH /api/users/{id}/rbac`.
+ *
+ * Delegue la persistance au PersistProcessor Doctrine decore apres avoir
+ * applique les gardes metier propres aux changements de droits. Cet endpoint
+ * ne touche JAMAIS au mot de passe — c'est une separation volontaire avec le
+ * UserPasswordHasherProcessor qui gere le endpoint profil `/api/users/{id}`.
+ *
+ * Gardes metier :
+ *  - Auto-suicide : un admin ne peut pas retirer son propre flag `isAdmin`.
+ *    On compare l'etat entrant a l'etat d'origine via l'UnitOfWork Doctrine,
+ *    en restreignant la verification au couple "user courant == user cible".
+ *
+ * TODO ticket #345 : garde "dernier admin" globale via inventaire des admins
+ * restants (empeche de retirer `isAdmin` au dernier admin de l'instance, meme
+ * si ce n'est pas sa propre operation).
+ *
+ * @implements ProcessorInterface<User, User>
+ */
+final class UserRbacProcessor implements ProcessorInterface
+{
+    public function __construct(
+        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
+        private readonly ProcessorInterface $persistProcessor,
+        private readonly EntityManagerInterface $entityManager,
+        private readonly Security $security,
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    {
+        if (!$data instanceof User) {
+            // Ce processor est wire exclusivement sur l'operation user_rbac_patch
+            // qui cible User. Si on arrive ici avec autre chose, c'est une
+            // misconfiguration qu'il faut faire remonter fort.
+            throw new LogicException(sprintf(
+                'UserRbacProcessor attend une instance de %s, %s recu.',
+                User::class,
+                get_debug_type($data),
+            ));
+        }
+
+        $currentUser = $this->security->getUser();
+
+        // Garde auto-suicide : l'user courant ne peut pas retirer son propre
+        // flag admin. On ne compare que si la cible == l'user courant.
+        if ($currentUser instanceof User
+            && null !== $currentUser->getId()
+            && $currentUser->getId() === $data->getId()
+        ) {
+            $originalData = $this->entityManager->getUnitOfWork()->getOriginalEntityData($data);
+            $wasAdmin     = $originalData['isAdmin'] ?? null;
+
+            if (true === $wasAdmin && false === $data->isAdmin()) {
+                throw new BadRequestHttpException(
+                    'Vous ne pouvez pas retirer vos propres droits administrateur.'
+                );
+            }
+        }
+
+        return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
+    }
+}
--- a/src/Module/Core/Infrastructure/Doctrine/DoctrineUserRepository.php
+++ b/src/Module/Core/Infrastructure/Doctrine/DoctrineUserRepository.php
@@ -34,4 +34,20 @@ class DoctrineUserRepository extends ServiceEntityRepository implements UserRepo
        $this->getEntityManager()->persist($user);
        $this->getEntityManager()->flush();
    }
+
+    /**
+     * Compte les utilisateurs ayant le flag isAdmin a true.
+     *
+     * Utilise par AdminHeadcountGuard pour verifier que l'instance conserve
+     * toujours au moins un administrateur apres une demote ou une suppression.
+     */
+    public function countAdmins(): int
+    {
+        return (int) $this->createQueryBuilder('u')
+            ->select('COUNT(u.id)')
+            ->where('u.isAdmin = true')
+            ->getQuery()
+            ->getSingleScalarResult()
+        ;
+    }
 }
--- a/tests/Module/Core/Api/AbstractApiTestCase.php
+++ b/tests/Module/Core/Api/AbstractApiTestCase.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Api;
+
+use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
+use ApiPlatform\Symfony\Bundle\Test\Client;
+use Doctrine\ORM\EntityManagerInterface;
+
+/**
+ * Classe de base pour les tests fonctionnels API Platform du module Core.
+ *
+ * Mutualise :
+ *  - `$alwaysBootKernel = true` : bascule le nouveau comportement API Platform 5
+ *    et evite la deprecation emise a la creation du client de test.
+ *  - `authenticatedClient()` : cree un client authentifie via `/login_check`
+ *    (cookie BEARER HTTP-only pose par lexik_jwt_authentication).
+ *  - `getEm()` : recupere l'EntityManager depuis le container courant.
+ *    A rappeler apres chaque createClient() car le kernel est reboote.
+ *
+ * @internal
+ */
+abstract class AbstractApiTestCase extends ApiTestCase
+{
+    // Bascule explicite sur le nouveau comportement API Platform 5 pour
+    // eviter la deprecation emise a la creation du client de test.
+    protected static ?bool $alwaysBootKernel = true;
+
+    /**
+     * Recupere l'EntityManager depuis le container courant. A utiliser a
+     * chaque appel : apres un createClient(), le kernel est reboote et tout
+     * EM precedemment capture est invalide.
+     */
+    protected function getEm(): EntityManagerInterface
+    {
+        if (!self::$kernel) {
+            self::bootKernel();
+        }
+
+        return self::getContainer()->get('doctrine')->getManager();
+    }
+
+    /**
+     * Cree un client authentifie via /login_check. La configuration du projet
+     * pose le JWT dans un cookie HTTP-only `BEARER` (cf. lexik_jwt_authentication.yaml)
+     * et retire le token du body de reponse ; le client BrowserKit persiste
+     * automatiquement le cookie pour les requetes suivantes.
+     */
+    protected function authenticatedClient(string $username, string $password): Client
+    {
+        $client   = self::createClient();
+        $response = $client->request('POST', '/login_check', [
+            'headers' => ['Content-Type' => 'application/json'],
+            'json'    => ['username' => $username, 'password' => $password],
+        ]);
+
+        self::assertContains(
+            $response->getStatusCode(),
+            [200, 204],
+            'Login failed for '.$username.': '.$response->getStatusCode(),
+        );
+
+        return $client;
+    }
+}
--- a/tests/Module/Core/Api/PermissionApiTest.php
+++ b/tests/Module/Core/Api/PermissionApiTest.php
@@ -0,0 +1,181 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Api;
+
+use App\Module\Core\Domain\Entity\Permission;
+
+/**
+ * Tests fonctionnels de l'exposition API Platform de l'entite Permission.
+ *
+ * Strategie de donnees : on cree directement quelques instances de Permission
+ * via l'EntityManager au setUp (choix le plus simple et le plus rapide, pas
+ * besoin de booter la commande app:sync-permissions). Les fixtures de test
+ * sont prefixees par "test." pour ne pas collisionner avec d'eventuelles
+ * permissions reelles et sont nettoyees en tearDown.
+ *
+ * @internal
+ */
+final class PermissionApiTest extends AbstractApiTestCase
+{
+    private const TEST_CODE_PREFIX = 'test.';
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // On boote le kernel une fois pour pouvoir seeder les fixtures.
+        // ATTENTION : ne pas stocker l'EntityManager dans une propriete,
+        // chaque createClient() dans les tests rebootera le kernel et
+        // invalidera tout EM capture ici (cf. $alwaysBootKernel = true).
+        self::bootKernel();
+        $em = $this->getEm();
+
+        // Nettoyage defensif au cas ou un run precedent aurait laisse des restes.
+        $this->cleanupTestPermissions();
+
+        // Donnees de test : deux permissions "core" dont une orpheline,
+        // plus une permission d'un autre module pour verifier le filtre.
+        $p1 = new Permission('test.core.users.view', 'View users (test)', 'core');
+        $p2 = new Permission('test.core.users.manage', 'Manage users (test)', 'core');
+        $p3 = new Permission('test.commercial.clients.view', 'View clients (test)', 'commercial');
+        $p2->markOrphan();
+
+        $em->persist($p1);
+        $em->persist($p2);
+        $em->persist($p3);
+        $em->flush();
+        $em->clear();
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestPermissions();
+        parent::tearDown();
+    }
+
+    public function testGetCollectionAsAdminReturns200(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions');
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        // API Platform 4 emet du JSON-LD 1.1 avec un @context qui utilise un
+        // @vocab : les cles sortent donc non prefixees (`member`, `totalItems`)
+        // au lieu des anciennes `hydra:member` / `hydra:totalItems`.
+        self::assertArrayHasKey('member', $data);
+        self::assertGreaterThanOrEqual(3, $data['totalItems']);
+    }
+
+    public function testCollectionFilterByModule(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions', [
+            'query' => ['module' => 'core'],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        foreach ($data['member'] as $item) {
+            self::assertSame('core', $item['module']);
+        }
+        // Doit contenir au moins nos deux permissions core de test.
+        $codes = array_column($data['member'], 'code');
+        self::assertContains('test.core.users.view', $codes);
+        self::assertContains('test.core.users.manage', $codes);
+        self::assertNotContains('test.commercial.clients.view', $codes);
+    }
+
+    public function testCollectionFilterByOrphanTrue(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions', [
+            'query' => ['orphan' => 'true'],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        foreach ($data['member'] as $item) {
+            self::assertTrue($item['orphan']);
+        }
+        $codes = array_column($data['member'], 'code');
+        // La permission marquee orpheline dans setUp() doit remonter...
+        self::assertContains('test.core.users.manage', $codes);
+        // ...et celles non orphelines doivent etre exclues.
+        self::assertNotContains('test.core.users.view', $codes);
+        self::assertNotContains('test.commercial.clients.view', $codes);
+    }
+
+    public function testCollectionFilterByOrphanFalse(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions', [
+            'query' => ['orphan' => 'false'],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        foreach ($data['member'] as $item) {
+            self::assertFalse($item['orphan']);
+        }
+        $codes = array_column($data['member'], 'code');
+        self::assertContains('test.core.users.view', $codes);
+        self::assertNotContains('test.core.users.manage', $codes);
+    }
+
+    public function testGetItemAsAdminReturnsAllReadFields(): void
+    {
+        /** @var null|Permission $permission */
+        $permission = $this->getEm()->getRepository(Permission::class)
+            ->findOneBy(['code' => 'test.core.users.view'])
+        ;
+        self::assertNotNull($permission);
+
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/permissions/'.$permission->getId());
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        self::assertSame($permission->getId(), $data['id']);
+        self::assertSame('test.core.users.view', $data['code']);
+        self::assertSame('View users (test)', $data['label']);
+        self::assertSame('core', $data['module']);
+        self::assertFalse($data['orphan']);
+    }
+
+    public function testPostIsMethodNotAllowed(): void
+    {
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('POST', '/api/permissions', [
+            'headers' => ['Content-Type' => 'application/ld+json'],
+            'json'    => ['code' => 'test.foo.bar.baz', 'label' => 'Foo', 'module' => 'foo'],
+        ]);
+
+        self::assertResponseStatusCodeSame(405);
+    }
+
+    public function testUnauthenticatedReturns401(): void
+    {
+        $client = self::createClient();
+        $client->request('GET', '/api/permissions');
+
+        self::assertResponseStatusCodeSame(401);
+    }
+
+    public function testNonAdminReturns403(): void
+    {
+        $client = $this->authenticatedClient('alice', 'alice');
+        $client->request('GET', '/api/permissions');
+
+        self::assertResponseStatusCodeSame(403);
+    }
+
+    private function cleanupTestPermissions(): void
+    {
+        $this->getEm()->createQuery(
+            'DELETE FROM '.Permission::class.' p WHERE p.code LIKE :prefix'
+        )->setParameter('prefix', self::TEST_CODE_PREFIX.'%')->execute();
+    }
+}
--- a/tests/Module/Core/Api/RoleApiTest.php
+++ b/tests/Module/Core/Api/RoleApiTest.php
@@ -0,0 +1,402 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Api;
+
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Core\Domain\Security\SystemRoles;
+
+/**
+ * Tests fonctionnels de l'exposition API Platform de l'entite Role (CRUD nominal).
+ *
+ * Strategie :
+ *  - Les roles systeme `admin` et `user` sont deja charges par les fixtures
+ *    (cf. AppFixtures::ensureSystemRole). On ne les touche JAMAIS.
+ *  - Les roles et permissions crees pour les tests ont le prefixe `test.` et
+ *    sont purges en setUp + tearDown par DQL prefixe.
+ *  - Les cas 403 sur role systeme et 400 sur modification de `code` sont
+ *    reportes a la Task 3 (RoleProcessor) et ne sont PAS testes ici.
+ *
+ * @internal
+ */
+final class RoleApiTest extends AbstractApiTestCase
+{
+    // Prefixe pour les roles de test : `test_` (underscore) parce que les
+    // codes de role doivent matcher `/^[a-z][a-z0-9_]*$/` (pas de point
+    // autorise, contrairement aux permissions).
+    private const TEST_ROLE_PREFIX = 'test_';
+
+    // Prefixe pour les permissions de test : `test.` (point) parce que les
+    // codes de permission doivent contenir au moins un `.` (convention
+    // module.resource.action validee dans le constructeur Permission).
+    private const TEST_PERMISSION_PREFIX = 'test.';
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        self::bootKernel();
+        $em = $this->getEm();
+
+        // Nettoyage defensif au cas ou un run precedent aurait laisse des restes.
+        $this->cleanupTestData();
+
+        // Permissions de test reutilisables (notamment pour le PATCH).
+        $p1 = new Permission('test.core.roles.view', 'View roles (test)', 'core');
+        $p2 = new Permission('test.core.roles.manage', 'Manage roles (test)', 'core');
+        $em->persist($p1);
+        $em->persist($p2);
+
+        // Role custom existant : utilise pour les GET / PATCH / DELETE.
+        $editor = new Role('test_editor', 'Editeur (test)', false, 'Role de test editeur');
+        $em->persist($editor);
+
+        // Deuxieme role custom : pour enrichir les collections.
+        $viewer = new Role('test_viewer', 'Visualisateur (test)', false);
+        $em->persist($viewer);
+
+        $em->flush();
+        $em->clear();
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+        parent::tearDown();
+    }
+
+    public function testPostCreatesCustomRoleAsAdmin(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('POST', '/api/roles', [
+            'headers' => ['Content-Type' => 'application/ld+json'],
+            'json'    => [
+                'code'        => 'test_new_editor',
+                'label'       => 'Nouvel editeur',
+                'description' => 'Role de test',
+            ],
+        ]);
+
+        self::assertResponseStatusCodeSame(201);
+        $data = $response->toArray();
+        self::assertSame('test_new_editor', $data['code']);
+        self::assertSame('Nouvel editeur', $data['label']);
+        self::assertFalse($data['isSystem']);
+
+        // Verification cote base : le role existe et isSystem = false.
+        $persisted = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => 'test_new_editor']);
+        self::assertNotNull($persisted);
+        self::assertFalse($persisted->isSystem());
+    }
+
+    public function testPostWithDuplicateCodeReturns422(): void
+    {
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('POST', '/api/roles', [
+            'headers' => ['Content-Type' => 'application/ld+json'],
+            'json'    => [
+                // `admin` est un role systeme charge par les fixtures.
+                'code'  => SystemRoles::ADMIN_CODE,
+                'label' => 'Tentative de doublon',
+            ],
+        ]);
+
+        self::assertResponseStatusCodeSame(422);
+    }
+
+    public function testPostWithInvalidCodeReturns422(): void
+    {
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('POST', '/api/roles', [
+            'headers' => ['Content-Type' => 'application/ld+json'],
+            'json'    => [
+                // Majuscules interdites par la regex snake_case.
+                'code'  => 'BadCode',
+                'label' => 'Code invalide',
+            ],
+        ]);
+
+        self::assertResponseStatusCodeSame(422);
+    }
+
+    public function testPostWithIsSystemTrueIgnoresItAndPersistsFalse(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('POST', '/api/roles', [
+            'headers' => ['Content-Type' => 'application/ld+json'],
+            'json'    => [
+                'code'     => 'test_sneaky',
+                'label'    => 'Tentative systeme',
+                'isSystem' => true,
+            ],
+        ]);
+
+        self::assertResponseStatusCodeSame(201);
+        $data = $response->toArray();
+        self::assertFalse($data['isSystem']);
+
+        $persisted = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => 'test_sneaky']);
+        self::assertNotNull($persisted);
+        self::assertFalse($persisted->isSystem());
+    }
+
+    public function testGetCollectionAsAdminReturnsRoles(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/roles');
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        self::assertArrayHasKey('member', $data);
+        // Au moins admin systeme + user systeme + test_editor + test_viewer.
+        self::assertGreaterThanOrEqual(4, $data['totalItems']);
+        $codes = array_column($data['member'], 'code');
+        self::assertContains('test_editor', $codes);
+    }
+
+    public function testGetCollectionFilterByIsSystemTrue(): void
+    {
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/roles', [
+            'query' => ['isSystem' => 'true'],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        foreach ($data['member'] as $item) {
+            self::assertTrue($item['isSystem']);
+        }
+        $codes = array_column($data['member'], 'code');
+        self::assertNotContains('test_editor', $codes);
+        self::assertNotContains('test_viewer', $codes);
+    }
+
+    public function testGetItemReturnsAllReadFields(): void
+    {
+        $role = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertNotNull($role);
+
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('GET', '/api/roles/'.$role->getId());
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        self::assertSame('test_editor', $data['code']);
+        self::assertSame('Editeur (test)', $data['label']);
+        self::assertSame('Role de test editeur', $data['description']);
+        self::assertFalse($data['isSystem']);
+        self::assertArrayHasKey('permissions', $data);
+        self::assertIsArray($data['permissions']);
+    }
+
+    public function testPatchCustomRoleUpdatesLabelAndAddsPermission(): void
+    {
+        $em   = $this->getEm();
+        $role = $em->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertNotNull($role);
+        $permission = $em->getRepository(Permission::class)->findOneBy(['code' => 'test.core.roles.view']);
+        self::assertNotNull($permission);
+
+        $client   = $this->authenticatedClient('admin', 'admin');
+        $response = $client->request('PATCH', '/api/roles/'.$role->getId(), [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => [
+                'label'       => 'Editeur modifie',
+                'permissions' => ['/api/permissions/'.$permission->getId()],
+            ],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $data = $response->toArray();
+        self::assertSame('Editeur modifie', $data['label']);
+        self::assertCount(1, $data['permissions']);
+
+        // Verification cote base.
+        $em->clear();
+
+        /** @var Role $reloaded */
+        $reloaded = $em->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertSame('Editeur modifie', $reloaded->getLabel());
+        self::assertCount(1, $reloaded->getPermissions());
+    }
+
+    public function testDeleteCustomRoleReturns204(): void
+    {
+        $role = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => 'test_viewer']);
+        self::assertNotNull($role);
+        $id = $role->getId();
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('DELETE', '/api/roles/'.$id);
+
+        self::assertResponseStatusCodeSame(204);
+
+        $em = $this->getEm();
+        $em->clear();
+        self::assertNull($em->getRepository(Role::class)->find($id));
+    }
+
+    public function testDeleteCustomRoleAttachedToUserDoesNotDeleteUser(): void
+    {
+        // Scenario spec #344 sections 7 & 11 : supprimer un role custom rattache
+        // a un user doit laisser le user en base (la FK user_role est nettoyee
+        // par ON DELETE CASCADE, mais jamais le user lui-meme).
+        $em = $this->getEm();
+
+        // Creer un user de test dedie et lui rattacher le role custom `test_editor`.
+        $testUser = new User();
+        $testUser->setUsername('test_cascade_user');
+        // Le hashage du password est hors scope du test mais la colonne est NOT NULL.
+        $testUser->setPassword('not-hashed-ok-for-test');
+
+        /** @var Role $editor */
+        $editor = $em->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertNotNull($editor);
+        $testUser->addRbacRole($editor);
+
+        $em->persist($testUser);
+        $em->flush();
+        $userId   = $testUser->getId();
+        $editorId = $editor->getId();
+        $em->clear();
+
+        // DELETE du role editor via l'API.
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('DELETE', '/api/roles/'.$editorId);
+        self::assertResponseStatusCodeSame(204);
+
+        // Verification : l'user existe toujours et sa collection de roles est vide.
+        $em = $this->getEm();
+
+        /** @var null|User $refreshed */
+        $refreshed = $em->getRepository(User::class)->find($userId);
+        self::assertNotNull($refreshed, 'L\'user ne doit PAS etre supprime par le cascade.');
+        self::assertCount(0, $refreshed->getRbacRoles(), 'La relation user_role doit etre nettoyee par le cascade.');
+
+        // Cleanup explicite : cleanupTestData() ne purge pas les users.
+        $em->remove($refreshed);
+        $em->flush();
+    }
+
+    public function testDeleteSystemRoleReturns403(): void
+    {
+        $role = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => SystemRoles::ADMIN_CODE]);
+        self::assertNotNull($role);
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('DELETE', '/api/roles/'.$role->getId());
+
+        self::assertResponseStatusCodeSame(403);
+
+        // Le role systeme doit toujours exister.
+        $em = $this->getEm();
+        $em->clear();
+        self::assertNotNull($em->getRepository(Role::class)->findOneBy(['code' => SystemRoles::ADMIN_CODE]));
+    }
+
+    public function testPatchSystemRoleLabelReturns200(): void
+    {
+        $em   = $this->getEm();
+        $role = $em->getRepository(Role::class)->findOneBy(['code' => SystemRoles::ADMIN_CODE]);
+        self::assertNotNull($role);
+        $originalLabel = $role->getLabel();
+        $roleId        = $role->getId();
+
+        $client = $this->authenticatedClient('admin', 'admin');
+
+        try {
+            $response = $client->request('PATCH', '/api/roles/'.$roleId, [
+                'headers' => ['Content-Type' => 'application/merge-patch+json'],
+                'json'    => ['label' => 'Administrateur (modifie test)'],
+            ]);
+
+            self::assertResponseIsSuccessful();
+            $data = $response->toArray();
+            self::assertSame('Administrateur (modifie test)', $data['label']);
+            self::assertSame(SystemRoles::ADMIN_CODE, $data['code']);
+            self::assertTrue($data['isSystem']);
+        } finally {
+            // Restauration defensive du label original pour ne pas polluer
+            // les tests suivants (les fixtures systeme sont partagees).
+            $em = $this->getEm();
+
+            /** @var null|Role $reloaded */
+            $reloaded = $em->getRepository(Role::class)->findOneBy(['code' => SystemRoles::ADMIN_CODE]);
+            if (null !== $reloaded && $reloaded->getLabel() !== $originalLabel) {
+                $reloaded->setLabel($originalLabel);
+                $em->flush();
+            }
+        }
+    }
+
+    public function testPatchRoleCodeChangeReturns400(): void
+    {
+        $role = $this->getEm()->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertNotNull($role);
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/roles/'.$role->getId(), [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['code' => 'test_editor_renamed'],
+        ]);
+
+        self::assertResponseStatusCodeSame(400);
+
+        // Verification cote base : le code d'origine n'a pas bouge.
+        $em = $this->getEm();
+        $em->clear();
+        self::assertNotNull($em->getRepository(Role::class)->findOneBy(['code' => 'test_editor']));
+        self::assertNull($em->getRepository(Role::class)->findOneBy(['code' => 'test_editor_renamed']));
+    }
+
+    public function testUnauthenticatedGetCollectionReturns401(): void
+    {
+        $client = self::createClient();
+        $client->request('GET', '/api/roles');
+
+        self::assertResponseStatusCodeSame(401);
+    }
+
+    public function testNonAdminGetCollectionReturns403(): void
+    {
+        $client = $this->authenticatedClient('alice', 'alice');
+        $client->request('GET', '/api/roles');
+
+        self::assertResponseStatusCodeSame(403);
+    }
+
+    /**
+     * Purge les donnees de test (roles et permissions prefixees `test.`).
+     * Ne touche JAMAIS aux roles systeme `admin` et `user` charges par les
+     * fixtures.
+     */
+    private function cleanupTestData(): void
+    {
+        $em = $this->getEm();
+
+        // Le cascade FK de la migration #343 (ON DELETE CASCADE sur
+        // role_permission.role_id et permission_id) nettoie automatiquement
+        // role_permission lors du DELETE SQL emis par Doctrine, meme via DQL
+        // bulk delete : le cascade est applique au niveau FK par PostgreSQL,
+        // pas par l'Unit of Work Doctrine. Verifie par comptage avant/apres
+        // runs successifs de la suite (stable a la ligne de base systeme).
+        // Purge defensive des users de test crees par certains scenarios
+        // (ex: testDeleteCustomRoleAttachedToUserDoesNotDeleteUser). Doit etre
+        // fait AVANT la suppression des roles pour que le cascade FK ne soit
+        // pas sollicite en ordre inverse.
+        $em->createQuery(
+            'DELETE FROM '.User::class.' u WHERE u.username LIKE :prefix'
+        )->setParameter('prefix', self::TEST_ROLE_PREFIX.'%')->execute();
+
+        $em->createQuery(
+            'DELETE FROM '.Role::class.' r WHERE r.code LIKE :prefix'
+        )->setParameter('prefix', self::TEST_ROLE_PREFIX.'%')->execute();
+
+        $em->createQuery(
+            'DELETE FROM '.Permission::class.' p WHERE p.code LIKE :prefix'
+        )->setParameter('prefix', self::TEST_PERMISSION_PREFIX.'%')->execute();
+    }
+}
--- a/tests/Module/Core/Api/UserRbacApiTest.php
+++ b/tests/Module/Core/Api/UserRbacApiTest.php
@@ -0,0 +1,271 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Api;
+
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Entity\User;
+use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
+
+/**
+ * Tests fonctionnels de l'endpoint RBAC dedie `PATCH /api/users/{id}/rbac`.
+ *
+ * Strategie de donnees :
+ *  - On cree des users, roles et permissions prefixes `test_` / `test.`
+ *    en setUp et on les purge en tearDown.
+ *  - On ne touche JAMAIS aux fixtures (admin / alice / bob). Les cas qui
+ *    ont besoin d'un user standard authentifie s'appuient sur alice sans
+ *    modification d'etat.
+ *  - Les users de test incluent un admin dedie pour le cas d'auto-suicide,
+ *    pour ne pas risquer de corrompre l'admin fixture.
+ *
+ * @internal
+ */
+final class UserRbacApiTest extends AbstractApiTestCase
+{
+    private const TEST_USER_PREFIX       = 'test_';
+    private const TEST_ROLE_PREFIX       = 'test_';
+    private const TEST_PERMISSION_PREFIX = 'test.';
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        self::bootKernel();
+        $em = $this->getEm();
+
+        $this->cleanupTestData();
+
+        /** @var UserPasswordHasherInterface $hasher */
+        $hasher = self::getContainer()->get(UserPasswordHasherInterface::class);
+
+        // User cible standard (non admin).
+        $target = new User();
+        $target->setUsername('test_target');
+        $target->setIsAdmin(false);
+        $target->setPassword($hasher->hashPassword($target, 'secret'));
+        $em->persist($target);
+
+        // User admin dedie pour le cas d'auto-suicide (pas l'admin fixture).
+        $selfAdmin = new User();
+        $selfAdmin->setUsername('test_self_admin');
+        $selfAdmin->setIsAdmin(true);
+        $selfAdmin->setPassword($hasher->hashPassword($selfAdmin, 'secret'));
+        $em->persist($selfAdmin);
+
+        // Role custom pour tester le remplacement de la collection roles.
+        $role = new Role('test_editor', 'Editeur (test)', false);
+        $em->persist($role);
+
+        // Permission custom pour tester directPermissions.
+        $permission = new Permission('test.core.users.view', 'View users (test)', 'core');
+        $em->persist($permission);
+
+        $em->flush();
+        $em->clear();
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+        parent::tearDown();
+    }
+
+    public function testPatchRbacPromotesUserToAdmin(): void
+    {
+        $target = $this->getEm()->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertNotNull($target);
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/users/'.$target->getId().'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['isAdmin' => true],
+        ]);
+
+        self::assertResponseIsSuccessful();
+
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertTrue($reloaded->isAdmin());
+    }
+
+    public function testPatchRbacReplacesRolesCollection(): void
+    {
+        $em     = $this->getEm();
+        $target = $em->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        $role   = $em->getRepository(Role::class)->findOneBy(['code' => 'test_editor']);
+        self::assertNotNull($target);
+        self::assertNotNull($role);
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/users/'.$target->getId().'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['roles' => ['/api/roles/'.$role->getId()]],
+        ]);
+
+        self::assertResponseIsSuccessful();
+
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertCount(1, $reloaded->getRbacRoles());
+        self::assertSame('test_editor', $reloaded->getRbacRoles()->first()->getCode());
+    }
+
+    public function testPatchRbacReplacesDirectPermissionsCollection(): void
+    {
+        $em         = $this->getEm();
+        $target     = $em->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        $permission = $em->getRepository(Permission::class)->findOneBy(['code' => 'test.core.users.view']);
+        self::assertNotNull($target);
+        self::assertNotNull($permission);
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/users/'.$target->getId().'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['directPermissions' => ['/api/permissions/'.$permission->getId()]],
+        ]);
+
+        self::assertResponseIsSuccessful();
+
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertCount(1, $reloaded->getDirectPermissions());
+        self::assertSame('test.core.users.view', $reloaded->getDirectPermissions()->first()->getCode());
+    }
+
+    public function testPatchRbacAsStandardUserReturns403(): void
+    {
+        $target = $this->getEm()->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertNotNull($target);
+
+        $client = $this->authenticatedClient('alice', 'alice');
+        $client->request('PATCH', '/api/users/'.$target->getId().'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['isAdmin' => true],
+        ]);
+
+        self::assertResponseStatusCodeSame(403);
+    }
+
+    public function testPatchRbacUnauthenticatedReturns401(): void
+    {
+        $target = $this->getEm()->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertNotNull($target);
+
+        $client = self::createClient();
+        $client->request('PATCH', '/api/users/'.$target->getId().'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['isAdmin' => true],
+        ]);
+
+        self::assertResponseStatusCodeSame(401);
+    }
+
+    public function testPatchRbacIgnoresUsernameField(): void
+    {
+        $target = $this->getEm()->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertNotNull($target);
+        $targetId = $target->getId();
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/users/'.$targetId.'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => [
+                'username' => 'test_target_renamed',
+                'isAdmin'  => true,
+            ],
+        ]);
+
+        self::assertResponseIsSuccessful();
+
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->find($targetId);
+        // `username` n'est pas dans `user:rbac:write` : ignore en denormalization.
+        self::assertSame('test_target', $reloaded->getUsername());
+        // `isAdmin` est bien applique.
+        self::assertTrue($reloaded->isAdmin());
+    }
+
+    public function testPatchProfileEndpointDoesNotModifyIsAdmin(): void
+    {
+        // Confirme la decision 0fc4e16 : `isAdmin` n'est plus dans `user:write`,
+        // donc `PATCH /api/users/{id}` sans `/rbac` ne peut plus promouvoir.
+        $target = $this->getEm()->getRepository(User::class)->findOneBy(['username' => 'test_target']);
+        self::assertNotNull($target);
+        $targetId = $target->getId();
+        self::assertFalse($target->isAdmin());
+
+        $client = $this->authenticatedClient('admin', 'admin');
+        $client->request('PATCH', '/api/users/'.$targetId, [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['isAdmin' => true],
+        ]);
+
+        // Peu importe le code : le champ ne doit tout simplement pas bouger.
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->find($targetId);
+        self::assertFalse($reloaded->isAdmin());
+    }
+
+    public function testPatchRbacSelfRemovingAdminReturns400(): void
+    {
+        // On utilise le user admin dedie (test_self_admin) pour ne pas
+        // corrompre l'admin fixture en cas de bug.
+        $em        = $this->getEm();
+        $selfAdmin = $em->getRepository(User::class)->findOneBy(['username' => 'test_self_admin']);
+        self::assertNotNull($selfAdmin);
+        $selfAdminId = $selfAdmin->getId();
+
+        $client = $this->authenticatedClient('test_self_admin', 'secret');
+        $client->request('PATCH', '/api/users/'.$selfAdminId.'/rbac', [
+            'headers' => ['Content-Type' => 'application/merge-patch+json'],
+            'json'    => ['isAdmin' => false],
+        ]);
+
+        self::assertResponseStatusCodeSame(400);
+
+        $em = $this->getEm();
+        $em->clear();
+
+        /** @var User $reloaded */
+        $reloaded = $em->getRepository(User::class)->find($selfAdminId);
+        self::assertTrue($reloaded->isAdmin());
+    }
+
+    private function cleanupTestData(): void
+    {
+        $em = $this->getEm();
+
+        // Ordre important : delier les collections avant de supprimer les
+        // entites referencees pour que les FK cascade s'appliquent via le
+        // schema PostgreSQL.
+        $em->createQuery(
+            'DELETE FROM '.User::class.' u WHERE u.username LIKE :prefix'
+        )->setParameter('prefix', self::TEST_USER_PREFIX.'%')->execute();
+
+        $em->createQuery(
+            'DELETE FROM '.Role::class.' r WHERE r.code LIKE :prefix'
+        )->setParameter('prefix', self::TEST_ROLE_PREFIX.'%')->execute();
+
+        $em->createQuery(
+            'DELETE FROM '.Permission::class.' p WHERE p.code LIKE :prefix'
+        )->setParameter('prefix', self::TEST_PERMISSION_PREFIX.'%')->execute();
+    }
+}
--- a/tests/Module/Core/Domain/Security/AdminHeadcountGuardTest.php
+++ b/tests/Module/Core/Domain/Security/AdminHeadcountGuardTest.php
@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Domain\Security;
+
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Core\Domain\Exception\LastAdminProtectionException;
+use App\Module\Core\Domain\Repository\UserRepositoryInterface;
+use App\Module\Core\Domain\Security\AdminHeadcountGuard;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests unitaires du gardien d'invariant AdminHeadcountGuard.
+ *
+ * Aucun acces base de donnees : UserRepositoryInterface est mocke.
+ *
+ * @internal
+ */
+class AdminHeadcountGuardTest extends TestCase
+{
+    // ---------------------------------------------------------------
+    // Demote (retrait du flag admin)
+    // ---------------------------------------------------------------
+
+    /**
+     * Autorise la demote quand il reste plus d'un admin (cas nominal).
+     */
+    public function testAllowsDemotionWhenMoreThanOneAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(2);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('alice');
+
+        // Aucune exception ne doit etre levee
+        $guard->ensureAtLeastOneAdminRemainsAfterDemotion($user);
+        $this->addToAssertionCount(1);
+    }
+
+    /**
+     * Bloque la demote quand il ne reste exactement qu'un admin.
+     */
+    public function testBlocksDemotionWhenExactlyOneAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(1);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('alice');
+
+        $this->expectException(LastAdminProtectionException::class);
+        $guard->ensureAtLeastOneAdminRemainsAfterDemotion($user);
+    }
+
+    /**
+     * Bloque la demote de facon defensive si le compteur est a 0 (etat incoherent).
+     */
+    public function testBlocksDemotionDefensivelyWhenZeroAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(0);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('alice');
+
+        $this->expectException(LastAdminProtectionException::class);
+        $guard->ensureAtLeastOneAdminRemainsAfterDemotion($user);
+    }
+
+    // ---------------------------------------------------------------
+    // Deletion (suppression de l'utilisateur)
+    // ---------------------------------------------------------------
+
+    /**
+     * Autorise la suppression quand il reste plus d'un admin (cas nominal).
+     */
+    public function testAllowsDeletionWhenMoreThanOneAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(2);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('bob');
+
+        // Aucune exception ne doit etre levee
+        $guard->ensureAtLeastOneAdminRemainsAfterDeletion($user);
+        $this->addToAssertionCount(1);
+    }
+
+    /**
+     * Bloque la suppression quand il ne reste exactement qu'un admin.
+     */
+    public function testBlocksDeletionWhenExactlyOneAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(1);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('bob');
+
+        $this->expectException(LastAdminProtectionException::class);
+        $guard->ensureAtLeastOneAdminRemainsAfterDeletion($user);
+    }
+
+    /**
+     * Bloque la suppression de facon defensive si le compteur est a 0 (etat incoherent).
+     */
+    public function testBlocksDeletionDefensivelyWhenZeroAdmin(): void
+    {
+        $repo = $this->createMock(UserRepositoryInterface::class);
+        $repo->method('countAdmins')->willReturn(0);
+
+        $guard = new AdminHeadcountGuard($repo);
+        $user  = new User();
+        $user->setUsername('bob');
+
+        $this->expectException(LastAdminProtectionException::class);
+        $guard->ensureAtLeastOneAdminRemainsAfterDeletion($user);
+    }
+}
--- a/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessorTest.php
+++ b/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessorTest.php
@@ -0,0 +1,228 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Infrastructure\ApiPlatform\State\Processor;
+
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\State\ProcessorInterface;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\RoleProcessor;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\UnitOfWork;
+use LogicException;
+use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use stdClass;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+/**
+ * Tests unitaires du RoleProcessor : couvre les gardes metier
+ * (immuabilite du code, refus de suppression des roles systeme) et la
+ * delegation aux processors Doctrine decores.
+ *
+ * @internal
+ */
+#[AllowMockObjectsWithoutExpectations]
+final class RoleProcessorTest extends TestCase
+{
+    private MockObject&ProcessorInterface $persistProcessor;
+    private MockObject&ProcessorInterface $removeProcessor;
+    private EntityManagerInterface&MockObject $entityManager;
+    private MockObject&UnitOfWork $unitOfWork;
+    private RoleProcessor $processor;
+
+    protected function setUp(): void
+    {
+        $this->persistProcessor = $this->createMock(ProcessorInterface::class);
+        $this->removeProcessor  = $this->createMock(ProcessorInterface::class);
+        $this->entityManager    = $this->createMock(EntityManagerInterface::class);
+        $this->unitOfWork       = $this->createMock(UnitOfWork::class);
+
+        $this->entityManager->method('getUnitOfWork')->willReturn($this->unitOfWork);
+
+        $this->processor = new RoleProcessor(
+            $this->persistProcessor,
+            $this->removeProcessor,
+            $this->entityManager,
+        );
+    }
+
+    public function testDeleteCustomRoleDelegatesToRemoveProcessor(): void
+    {
+        $role = new Role('editor', 'Editor', false);
+
+        $this->removeProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($role)
+            ->willReturn(null)
+        ;
+
+        $this->persistProcessor->expects(self::never())->method('process');
+
+        $result = $this->processor->process($role, new Delete());
+
+        self::assertNull($result);
+    }
+
+    public function testDeleteSystemRoleThrowsAccessDeniedHttpException(): void
+    {
+        $role = new Role('admin', 'Admin', true);
+
+        $this->removeProcessor->expects(self::never())->method('process');
+        $this->persistProcessor->expects(self::never())->method('process');
+
+        $this->expectException(AccessDeniedHttpException::class);
+        $this->expectExceptionMessage('Le role systeme "admin" ne peut pas etre supprime.');
+
+        $this->processor->process($role, new Delete());
+    }
+
+    public function testPostCreatesCustomRoleDelegatesToPersistProcessor(): void
+    {
+        $role = new Role('editor', 'Editor', false);
+
+        // Entite nouvelle : l'UnitOfWork n'a pas d'etat d'origine.
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($role)
+            ->willReturn([])
+        ;
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($role)
+            ->willReturn($role)
+        ;
+
+        $this->removeProcessor->expects(self::never())->method('process');
+
+        $result = $this->processor->process($role, new Post());
+
+        self::assertSame($role, $result);
+    }
+
+    public function testPatchWithChangedCodeThrowsBadRequestHttpException(): void
+    {
+        // L'entite arrive avec le nouveau code deja applique par le denormalizer.
+        $role = new Role('editor_renamed', 'Editor', false);
+        $this->setRoleId($role, 42);
+
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($role)
+            ->willReturn([
+                'id'       => 42,
+                'code'     => 'editor',
+                'label'    => 'Editor',
+                'isSystem' => false,
+            ])
+        ;
+
+        $this->persistProcessor->expects(self::never())->method('process');
+        $this->removeProcessor->expects(self::never())->method('process');
+
+        $this->expectException(BadRequestHttpException::class);
+        $this->expectExceptionMessage("Le code d'un role est immuable apres creation.");
+
+        $this->processor->process($role, new Patch());
+    }
+
+    public function testPatchWithUnchangedCodeDelegatesToPersistProcessor(): void
+    {
+        $role = new Role('editor', 'Editor modifie', false, 'desc');
+        $this->setRoleId($role, 42);
+
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($role)
+            ->willReturn([
+                'id'       => 42,
+                'code'     => 'editor',
+                'label'    => 'Editor',
+                'isSystem' => false,
+            ])
+        ;
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($role)
+            ->willReturn($role)
+        ;
+
+        $this->removeProcessor->expects(self::never())->method('process');
+
+        $result = $this->processor->process($role, new Patch());
+
+        self::assertSame($role, $result);
+    }
+
+    public function testPatchSystemRoleLabelDelegatesToPersistProcessor(): void
+    {
+        // Regle uniforme : un role systeme peut voir son label modifie tant
+        // que son code reste inchange. Seul le DELETE est bloque.
+        $role = new Role('admin', 'Administrateur', true);
+        $this->setRoleId($role, 1);
+
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($role)
+            ->willReturn([
+                'id'       => 1,
+                'code'     => 'admin',
+                'label'    => 'Admin',
+                'isSystem' => true,
+            ])
+        ;
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($role)
+            ->willReturn($role)
+        ;
+
+        $this->removeProcessor->expects(self::never())->method('process');
+
+        $result = $this->processor->process($role, new Patch());
+
+        self::assertSame($role, $result);
+    }
+
+    public function testProcessNonRoleDataThrowsLogicException(): void
+    {
+        // Garde-fou contre une misconfiguration : ce processor est wire
+        // exclusivement sur les operations Role.
+        $this->persistProcessor->expects(self::never())->method('process');
+        $this->removeProcessor->expects(self::never())->method('process');
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('RoleProcessor attend une instance de');
+
+        $this->processor->process(new stdClass(), new Patch());
+    }
+
+    /**
+     * Positionne l'id d'un Role via reflection pour simuler une entite deja
+     * persistee (les mocks d'UnitOfWork n'alimentent pas l'id tout seul).
+     */
+    private function setRoleId(Role $role, int $id): void
+    {
+        $refl = new ReflectionClass($role);
+        $prop = $refl->getProperty('id');
+        $prop->setAccessible(true);
+        $prop->setValue($role, $id);
+    }
+}
--- a/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessorTest.php
+++ b/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessorTest.php
@@ -0,0 +1,230 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Infrastructure\ApiPlatform\State\Processor;
+
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\State\ProcessorInterface;
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\UserRbacProcessor;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\UnitOfWork;
+use LogicException;
+use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use stdClass;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+/**
+ * Tests unitaires du UserRbacProcessor : couvre la garde "auto-suicide" et la
+ * delegation au PersistProcessor Doctrine decore pour les trois champs RBAC
+ * (isAdmin, roles, directPermissions).
+ *
+ * @internal
+ */
+#[AllowMockObjectsWithoutExpectations]
+final class UserRbacProcessorTest extends TestCase
+{
+    private MockObject&ProcessorInterface $persistProcessor;
+    private EntityManagerInterface&MockObject $entityManager;
+    private MockObject&UnitOfWork $unitOfWork;
+    private MockObject&Security $security;
+    private UserRbacProcessor $processor;
+
+    protected function setUp(): void
+    {
+        $this->persistProcessor = $this->createMock(ProcessorInterface::class);
+        $this->entityManager    = $this->createMock(EntityManagerInterface::class);
+        $this->unitOfWork       = $this->createMock(UnitOfWork::class);
+        $this->security         = $this->createMock(Security::class);
+
+        $this->entityManager->method('getUnitOfWork')->willReturn($this->unitOfWork);
+
+        $this->processor = new UserRbacProcessor(
+            $this->persistProcessor,
+            $this->entityManager,
+            $this->security,
+        );
+    }
+
+    public function testPatchPromotesUserToAdminDelegatesToPersistProcessor(): void
+    {
+        $target = $this->buildUser(42, 'alice', false);
+        $target->setIsAdmin(true);
+
+        $currentAdmin = $this->buildUser(1, 'admin', true);
+        $this->security->method('getUser')->willReturn($currentAdmin);
+
+        // Cible != user courant : pas de lecture d'UnitOfWork necessaire.
+        $this->unitOfWork->expects(self::never())->method('getOriginalEntityData');
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($target)
+            ->willReturn($target)
+        ;
+
+        $result = $this->processor->process($target, new Patch());
+
+        self::assertSame($target, $result);
+    }
+
+    public function testPatchUpdatesRolesCollectionDelegatesToPersistProcessor(): void
+    {
+        $target = $this->buildUser(42, 'alice', false);
+        $target->addRbacRole(new Role('editor', 'Editor', false));
+
+        $currentAdmin = $this->buildUser(1, 'admin', true);
+        $this->security->method('getUser')->willReturn($currentAdmin);
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($target)
+            ->willReturn($target)
+        ;
+
+        $result = $this->processor->process($target, new Patch());
+
+        self::assertSame($target, $result);
+        self::assertCount(1, $result->getRbacRoles());
+    }
+
+    public function testPatchUpdatesDirectPermissionsCollectionDelegatesToPersistProcessor(): void
+    {
+        $target = $this->buildUser(42, 'alice', false);
+        $target->addDirectPermission(new Permission('core.users.view', 'View', 'core'));
+
+        $currentAdmin = $this->buildUser(1, 'admin', true);
+        $this->security->method('getUser')->willReturn($currentAdmin);
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($target)
+            ->willReturn($target)
+        ;
+
+        $result = $this->processor->process($target, new Patch());
+
+        self::assertSame($target, $result);
+        self::assertCount(1, $result->getDirectPermissions());
+    }
+
+    public function testPatchSelfRemovingAdminThrowsBadRequestHttpException(): void
+    {
+        // Meme identifiant : l'user courant PATCH sa propre ressource.
+        $self = $this->buildUser(1, 'admin', false);
+
+        $this->security->method('getUser')->willReturn($self);
+
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($self)
+            ->willReturn([
+                'id'       => 1,
+                'username' => 'admin',
+                'isAdmin'  => true,
+            ])
+        ;
+
+        $this->persistProcessor->expects(self::never())->method('process');
+
+        $this->expectException(BadRequestHttpException::class);
+        $this->expectExceptionMessage('Vous ne pouvez pas retirer vos propres droits administrateur.');
+
+        $this->processor->process($self, new Patch());
+    }
+
+    public function testPatchAdminDemotingAnotherUserIsAllowed(): void
+    {
+        // Un admin qui retire isAdmin a quelqu'un d'autre : autorise.
+        $target  = $this->buildUser(42, 'alice', false);
+        $current = $this->buildUser(1, 'admin', true);
+
+        $this->security->method('getUser')->willReturn($current);
+
+        // Cible != user courant : pas de verification d'auto-suicide.
+        $this->unitOfWork->expects(self::never())->method('getOriginalEntityData');
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($target)
+            ->willReturn($target)
+        ;
+
+        $result = $this->processor->process($target, new Patch());
+
+        self::assertSame($target, $result);
+    }
+
+    public function testPatchSelfKeepingAdminIsAllowed(): void
+    {
+        // L'user courant se PATCH lui-meme mais garde isAdmin = true :
+        // aucun auto-suicide, on delegue au PersistProcessor.
+        $self = $this->buildUser(1, 'admin', true);
+
+        $this->security->method('getUser')->willReturn($self);
+
+        $this->unitOfWork
+            ->expects(self::once())
+            ->method('getOriginalEntityData')
+            ->with($self)
+            ->willReturn([
+                'id'       => 1,
+                'username' => 'admin',
+                'isAdmin'  => true,
+            ])
+        ;
+
+        $this->persistProcessor
+            ->expects(self::once())
+            ->method('process')
+            ->with($self)
+            ->willReturn($self)
+        ;
+
+        $result = $this->processor->process($self, new Patch());
+
+        self::assertSame($self, $result);
+    }
+
+    public function testProcessNonUserDataThrowsLogicException(): void
+    {
+        // Garde-fou contre une misconfiguration : ce processor est wire
+        // exclusivement sur l'operation user_rbac_patch (cible User).
+        $this->persistProcessor->expects(self::never())->method('process');
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('UserRbacProcessor attend une instance de');
+
+        $this->processor->process(new stdClass(), new Patch());
+    }
+
+    /**
+     * Construit un User avec un id force via reflection (les mocks
+     * d'UnitOfWork n'alimentent pas l'id tout seul).
+     */
+    private function buildUser(int $id, string $username, bool $isAdmin): User
+    {
+        $user = new User();
+        $user->setUsername($username);
+        $user->setIsAdmin($isAdmin);
+
+        $refl = new ReflectionClass($user);
+        $prop = $refl->getProperty('id');
+        $prop->setAccessible(true);
+        $prop->setValue($user, $id);
+
+        return $user;
+    }
+}
Author	SHA1	Message	Date
Matthieu	4325b1d8a0	feat(core) : RBAC #345 - AdminHeadcountGuard domain service	2026-04-15 15:45:55 +02:00
Matthieu	b7aa445cef	feat(core) : RBAC #345 - add core.roles.view permission	2026-04-15 15:42:42 +02:00
Matthieu	fd4ed25c63	docs(core) : RBAC #345 - spec voter + usePermissions	2026-04-15 15:28:51 +02:00
Matthieu	0ccbc70f27	fix(core) : RBAC #344 - ferme leak user list + test cascade delete role	2026-04-15 14:53:49 +02:00
Matthieu	534bdbccdd	refactor(core) : RBAC #344 - polish review - narrow rbac read group + fail-fast processors	2026-04-15 14:28:02 +02:00
Matthieu	3c7dc88fe7	feat(core) : RBAC #344 - UserRbacProcessor + endpoint /users/{id}/rbac Ajoute une operation Patch dediee `PATCH /api/users/{id}/rbac` (nom `user_rbac_patch`) qui accepte exclusivement les champs RBAC isAdmin, roles et directPermissions via le groupe user:rbac:write. L'endpoint est separe volontairement du Patch profil existant pour isoler la modification des droits de celle des donnees profil (decision `0fc4e16`). UserRbacProcessor delegue au PersistProcessor Doctrine decore et applique une garde auto-suicide : un admin ne peut pas retirer ses propres droits administrateur (compare l'etat entrant a l'etat UnitOfWork). La garde 'dernier admin' globale est reportee au ticket #345. La propriete Doctrine $roles est renommee $rbacRoles pour eviter la collision avec UserInterface::getRoles() (qui renvoie list<string>) lors de la normalization API Platform. La cle JSON reste `roles` grace a SerializedName, le contrat API est inchange. Tests : 6 unitaires (UserRbacProcessorTest) + 8 fonctionnels (UserRbacApiTest) couvrant promotion admin, remplacement des collections roles/directPermissions, 401/403, filtrage du groupe denormalization (`username` ignore), preservation de isAdmin sur le Patch profil, et garde auto-suicide.	2026-04-15 14:17:18 +02:00
Matthieu	168a47f2b8	refactor(test) : RBAC #344 - AbstractApiTestCase pour mutualiser auth JWT Extrait l'helper authenticatedClient(), $alwaysBootKernel et getEm() dans une classe de base commune aux tests fonctionnels API Platform du module Core. Supprime la duplication entre PermissionApiTest et RoleApiTest (flaggee en code review de la Task 2). Prepare le terrain pour le nouveau UserRbacApiTest introduit avec la Task 4.	2026-04-15 12:14:20 +02:00
Matthieu	87aa1d0b04	test(core) : RBAC #344 - renforce docblock setCode + assertion message exception	2026-04-15 12:05:26 +02:00
Matthieu	d527fbe2d1	feat(core) : RBAC #344 - RoleProcessor + gardes systeme et code immuable	2026-04-15 11:58:37 +02:00
Matthieu	efc12c8bdb	fix(test) : RBAC #344 - role test cleanup + SystemRoles constant + assertion seuil	2026-04-15 11:53:01 +02:00
Matthieu	7be0260b29	feat(core) : RBAC #344 - API Platform Role CRUD nominal + validators	2026-04-15 11:41:21 +02:00
Matthieu	f79f061131	fix(test) : RBAC #344 - corrige EM stale et ajoute cas orphan=true	2026-04-15 11:15:41 +02:00
Matthieu	fdb7aded82	feat(core) : RBAC #344 - API Platform Permission en lecture seule - Expose l'entite Permission via ApiResource (GetCollection + Get uniquement) - Serialisation limitee au groupe permission:read (id, code, label, module, orphan) - Securite temporaire is_granted('ROLE_ADMIN'), a remplacer par is_granted('core.permissions.view') au ticket #345 - Filtres : SearchFilter exact sur module, BooleanFilter sur orphan - Configure api_platform.mapping.paths pour que le compile pass AP decouvre les ApiResource/ApiFilter declares dans src/Module/Core/Domain/Entity - Ajoute symfony/browser-kit et symfony/http-client en dev pour les tests fonctionnels API Platform, plus KERNEL_CLASS dans phpunit.dist.xml - Tests fonctionnels PermissionApiTest : collection, get item, filtres module et orphan, 405 sur POST, 401 non authentifie, 403 non-admin	2026-04-15 11:03:22 +02:00
Matthieu	1cf550721b	docs(rbac) : spec ticket #344 - API CRUD roles & permissions	2026-04-15 10:31:10 +02:00