feat(core) : RBAC Task 1 - entites Permission et Role + domaine securite

- Entite Permission avec methodes markOrphan/revive/updateMetadata
- Entite Role avec addPermission/removePermission/ensureDeletable
- Constantes SystemRoles (codes admin/user partages)
- Exception SystemRoleDeletionException pour la garde de suppression
- Tests unitaires couvrant le comportement domaine (pas de BDD)

Ticket #343 - 1/7 : fondations RBAC (domaine pur, sans persistence).
Les entites ne portent pas encore repositoryClass (ajoute en Task 2).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/Module/Core/Domain/Entity/Permission.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+// TODO: brancher repositoryClass au ticket 343 partie 2 (Task 2).
+#[ORM\Entity]
+#[ORM\Table(name: 'permission')]
+#[ORM\UniqueConstraint(name: 'uniq_permission_code', columns: ['code'])]
+#[ORM\Index(name: 'idx_permission_module', columns: ['module'])]
+#[ORM\Index(name: 'idx_permission_orphan', columns: ['orphan'])]
+class Permission
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 255)]
+    private string $code;
+
+    #[ORM\Column(length: 255)]
+    private string $label;
+
+    #[ORM\Column(length: 100)]
+    private string $module;
+
+    #[ORM\Column(options: ['default' => false])]
+    private bool $orphan = false;
+
+    public function __construct(string $code, string $label, string $module)
+    {
+        $this->code   = $code;
+        $this->label  = $label;
+        $this->module = $module;
+    }
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getCode(): string
+    {
+        return $this->code;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->label;
+    }
+
+    public function getModule(): string
+    {
+        return $this->module;
+    }
+
+    public function isOrphan(): bool
+    {
+        return $this->orphan;
+    }
+
+    /**
+     * Marque la permission comme orpheline : son code n'est plus declare par
+     * aucun module. Elle reste en base pour preserver les assignations et
+     * permettre une reactivation ulterieure, mais doit etre ignoree par les
+     * verifications d'autorisation.
+     */
+    public function markOrphan(): self
+    {
+        $this->orphan = true;
+
+        return $this;
+    }
+
+    /**
+     * Reactive une permission precedemment orpheline : son code reapparait
+     * dans le code source d'un module. On en profite pour rafraichir les
+     * metadonnees (libelle et module d'appartenance).
+     */
+    public function revive(string $label, string $module): self
+    {
+        $this->orphan = false;
+        $this->label  = $label;
+        $this->module = $module;
+
+        return $this;
+    }
+
+    /**
+     * Met a jour les metadonnees d'une permission active sans toucher a son
+     * statut d'orphelin. Utilise par la commande de synchronisation lorsque
+     * seul le libelle ou le module proprietaire a change cote code.
+     */
+    public function updateMetadata(string $label, string $module): self
+    {
+        $this->label  = $label;
+        $this->module = $module;
+
+        return $this;
+    }
+}

src/Module/Core/Domain/Entity/Role.php

@@ -0,0 +1,144 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Entity;
+
+use App\Module\Core\Domain\Exception\SystemRoleDeletionException;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\DBAL\Types\Types;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * Role RBAC : groupe nomme de permissions assignable a un utilisateur.
+ *
+ * Un role peut etre "systeme" (cree et protege par la plateforme) ou
+ * "personnalise" (cree par un administrateur). Seuls les roles personnalises
+ * peuvent etre supprimes.
+ */
+// TODO: brancher repositoryClass au ticket 343 partie 2 (Task 2).
+#[ORM\Entity]
+#[ORM\Table(name: '`role`')]
+#[ORM\UniqueConstraint(name: 'uniq_role_code', columns: ['code'])]
+#[ORM\Index(name: 'idx_role_is_system', columns: ['is_system'])]
+class Role
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 100)]
+    private string $code;
+
+    #[ORM\Column(length: 255)]
+    private string $label;
+
+    #[ORM\Column(type: Types::TEXT, nullable: true)]
+    private ?string $description = null;
+
+    #[ORM\Column(name: 'is_system', options: ['default' => false])]
+    private bool $isSystem = false;
+
+    /** @var Collection<int, Permission> */
+    #[ORM\ManyToMany(targetEntity: Permission::class, fetch: 'EAGER')]
+    #[ORM\JoinTable(name: 'role_permission')]
+    private Collection $permissions;
+
+    public function __construct(string $code, string $label, bool $isSystem = false, ?string $description = null)
+    {
+        $this->code        = $code;
+        $this->label       = $label;
+        $this->isSystem    = $isSystem;
+        $this->description = $description;
+        $this->permissions = new ArrayCollection();
+    }
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getCode(): string
+    {
+        return $this->code;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->label;
+    }
+
+    public function getDescription(): ?string
+    {
+        return $this->description;
+    }
+
+    public function isSystem(): bool
+    {
+        return $this->isSystem;
+    }
+
+    /** @return Collection<int, Permission> */
+    public function getPermissions(): Collection
+    {
+        return $this->permissions;
+    }
+
+    /**
+     * Met a jour le libelle affichable du role. Le code reste immuable pour
+     * garantir la stabilite des references cote fixtures et migrations.
+     */
+    public function setLabel(string $label): self
+    {
+        $this->label = $label;
+
+        return $this;
+    }
+
+    /**
+     * Met a jour la description libre du role (champ documentaire).
+     */
+    public function setDescription(?string $description): self
+    {
+        $this->description = $description;
+
+        return $this;
+    }
+
+    /**
+     * Ajoute une permission au role. Idempotent : ajouter deux fois la meme
+     * permission n'entraine pas de doublon dans la collection.
+     */
+    public function addPermission(Permission $permission): self
+    {
+        if (!$this->permissions->contains($permission)) {
+            $this->permissions->add($permission);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Retire une permission du role. Idempotent : retirer une permission
+     * absente est un no-op silencieux.
+     */
+    public function removePermission(Permission $permission): self
+    {
+        $this->permissions->removeElement($permission);
+
+        return $this;
+    }
+
+    /**
+     * Garde domaine : refuse la suppression d'un role marque comme systeme.
+     * La traduction HTTP (403) est faite au niveau application / API Platform.
+     */
+    public function ensureDeletable(): void
+    {
+        if ($this->isSystem) {
+            throw SystemRoleDeletionException::forRole($this);
+        }
+    }
+}

src/Module/Core/Domain/Exception/SystemRoleDeletionException.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Exception;
+
+use App\Module\Core\Domain\Entity\Role;
+use DomainException;
+
+/**
+ * Levee lorsqu'une tentative de suppression vise un role marque comme systeme.
+ *
+ * Les roles systeme (ex : admin, user) sont proteges au niveau du domaine
+ * pour garantir qu'ils ne peuvent jamais etre retires par un administrateur,
+ * une commande ou un processus d'import. La traduction HTTP (403) est faite
+ * ailleurs, cette exception reste purement domaine.
+ */
+final class SystemRoleDeletionException extends DomainException
+{
+    /**
+     * Construit l'exception a partir du role refuse a la suppression.
+     */
+    public static function forRole(Role $role): self
+    {
+        return new self(sprintf('Le role systeme "%s" ne peut pas etre supprime.', $role->getCode()));
+    }
+}

src/Module/Core/Domain/Security/SystemRoles.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Core\Domain\Security;
+
+/**
+ * Source de verite unique pour les codes des roles systeme RBAC.
+ *
+ * Ces constantes sont partagees entre les fixtures applicatives et les
+ * migrations Doctrine (qui inserent les memes codes en SQL brut). Toute
+ * modification ici doit etre repercutee dans la migration correspondante.
+ */
+final class SystemRoles
+{
+    public const string ADMIN_CODE = 'admin';
+    public const string USER_CODE  = 'user';
+
+    /**
+     * Empeche l'instanciation : cette classe est un simple porteur de constantes.
+     */
+    private function __construct() {}
+}

tests/Module/Core/Domain/Entity/PermissionTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Domain\Entity;
+
+use App\Module\Core\Domain\Entity\Permission;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class PermissionTest extends TestCase
+{
+    public function testConstructorInitialState(): void
+    {
+        $permission = new Permission('core.users.view', 'Voir les utilisateurs', 'core');
+
+        self::assertNull($permission->getId());
+        self::assertSame('core.users.view', $permission->getCode());
+        self::assertSame('Voir les utilisateurs', $permission->getLabel());
+        self::assertSame('core', $permission->getModule());
+        self::assertFalse($permission->isOrphan());
+    }
+
+    public function testMarkOrphanSetsFlag(): void
+    {
+        $permission = new Permission('core.users.view', 'Voir les utilisateurs', 'core');
+
+        $permission->markOrphan();
+
+        self::assertTrue($permission->isOrphan());
+    }
+
+    public function testReviveResetsOrphanAndUpdatesMetadata(): void
+    {
+        $permission = new Permission('core.users.view', 'Old label', 'core');
+        $permission->markOrphan();
+
+        $permission->revive('New label', 'commercial');
+
+        self::assertFalse($permission->isOrphan());
+        self::assertSame('New label', $permission->getLabel());
+        self::assertSame('commercial', $permission->getModule());
+    }
+
+    public function testUpdateMetadataDoesNotTouchOrphan(): void
+    {
+        $permission = new Permission('core.users.view', 'Old', 'core');
+        $permission->markOrphan();
+
+        $permission->updateMetadata('Lbl', 'core');
+
+        self::assertTrue($permission->isOrphan());
+        self::assertSame('Lbl', $permission->getLabel());
+    }
+}

tests/Module/Core/Domain/Entity/RoleTest.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Domain\Entity;
+
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Exception\SystemRoleDeletionException;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class RoleTest extends TestCase
+{
+    public function testConstructorInitialState(): void
+    {
+        $role = new Role('custom', 'Custom');
+
+        self::assertNull($role->getId());
+        self::assertSame('custom', $role->getCode());
+        self::assertSame('Custom', $role->getLabel());
+        self::assertNull($role->getDescription());
+        self::assertFalse($role->isSystem());
+        self::assertTrue($role->getPermissions()->isEmpty());
+    }
+
+    public function testAddPermissionAddsOnce(): void
+    {
+        $role       = new Role('custom', 'Custom');
+        $permission = new Permission('core.users.view', 'Voir', 'core');
+
+        $role->addPermission($permission);
+        $role->addPermission($permission);
+
+        self::assertSame(1, $role->getPermissions()->count());
+    }
+
+    public function testRemovePermissionRemovesWhenPresent(): void
+    {
+        $role       = new Role('custom', 'Custom');
+        $permission = new Permission('core.users.view', 'Voir', 'core');
+
+        $role->addPermission($permission);
+        $role->removePermission($permission);
+
+        self::assertSame(0, $role->getPermissions()->count());
+    }
+
+    public function testRemovePermissionIsNoOpWhenAbsent(): void
+    {
+        $role       = new Role('custom', 'Custom');
+        $permission = new Permission('core.users.view', 'Voir', 'core');
+
+        $role->removePermission($permission);
+
+        self::assertSame(0, $role->getPermissions()->count());
+    }
+
+    public function testEnsureDeletableAllowsNonSystemRole(): void
+    {
+        $role = new Role('custom', 'Custom', false);
+
+        $role->ensureDeletable();
+
+        $this->expectNotToPerformAssertions();
+    }
+
+    public function testEnsureDeletableThrowsForSystemRole(): void
+    {
+        $role = new Role('admin', 'Admin', true);
+
+        $this->expectException(SystemRoleDeletionException::class);
+        $this->expectExceptionMessage('admin');
+
+        $role->ensureDeletable();
+    }
+}

tests/Module/Core/Domain/Security/SystemRolesTest.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Domain\Security;
+
+use App\Module\Core\Domain\Security\SystemRoles;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class SystemRolesTest extends TestCase
+{
+    public function testAdminCodeConstant(): void
+    {
+        self::assertSame('admin', SystemRoles::ADMIN_CODE);
+    }
+
+    public function testUserCodeConstant(): void
+    {
+        self::assertSame('user', SystemRoles::USER_CODE);
+    }
+}