feat : audit log (table + writer + listener + API + admin UI + timeline) (#9)

## Résumé Implémente le journal d'audit append-only couvrant les 5 tickets de `doc/audit-log.md` et embarque au passage plusieurs corrections périphériques (sidebar Admin/Mon compte, drawer RBAC, Swagger, schema_filter Doctrine) ainsi que l'initialisation de la suite e2e Playwright. Toutes les mutations Doctrine sur les entités portant `#[Auditable]` sont tracées dans une table PostgreSQL dédiée, exposée en lecture seule via API Platform et consultable par les admins dans une page dédiée. ## Ce qui change ### Audit log — cœur de la PR **Backend** - Migration : table `audit_log` (UUID v7 natif Postgres en PK, `jsonb changes`, 3 index pour tri chrono, par entité et par utilisateur). - `AuditLogWriter` : service bas-niveau, écrit via une connexion DBAL dédiée `audit` (même DSN que `default`, service séparé) pour sortir de la transaction ORM en batch. Blacklist defense-in-depth `password`/`plainPassword`/`token`/`secret`. - `RequestIdProvider` : UUID v4 généré au `kernel.request` principal, injecté dans chaque ligne d'audit de la requête. - Attributs `#[Auditable]` / `#[AuditIgnore]` dans `src/Shared/Domain/Attribute/` (accessibles par tous les modules). - `AuditListener` : capture `onFlush` / écriture `postFlush` avec pattern swap-and-clear contre les flushes ré-entrants. Erreurs loguées, jamais propagées. Entité `User` annotée (password / plainPassword ignorés). - API Platform read-only `/api/audit-logs` (permission RBAC `core.audit_log.view`) : `GET` collection paginée + `GET` item, pas de POST/PUT/PATCH/DELETE. Filtres `entity_type`, `entity_id`, `action`, `performed_by`, `performed_at[after]`/`[before]`. - `DbalPaginator` implémentant `PaginatorInterface` : `hydra:view` généré automatiquement par API Platform, pas de construction manuelle. - Ressource `AuditLogEntityTypesResource` + provider dédié pour peupler le filtre par type d'entité côté UI (réponse cachée, pas de requête à chaque ouverture du drawer). - Permission `core.audit_log.view` déclarée dans `CoreModule::permissions()`. - `audit_log` exclu du `schema_filter` Doctrine : plus de faux diff sur `make migration-diff`. **Frontend** - Page admin `/admin/audit-log` : tableau paginé, filtres locaux (état dans le composant, non persistés dans l'URL — conforme règle CLAUDE.md « Tableaux : pas de persistance URL »), drawer de détail (diff + timeline complète de l'entité), badges colorés par action. - Composable partagé `useAuditLog` avec `resetAuditLog()` auto-enregistré sur `onAuthSessionCleared` (règle CLAUDE.md composables singletons). - Composant réutilisable `<AuditTimeline :entity-type :entity-id>` : garde permission (pas d'appel API sans le droit), lazy loading (10 items + bouton « Voir plus »), dates relatives FR via `Intl.RelativeTimeFormat`, skeleton loader. - Entrée sidebar « Journal d'audit » gated sur `core.audit_log.view` + clés i18n imbriquées dans `fr.json`. ### Fixes embarqués - **Review fixes audit-log** (commits `37eafd2`, `1505e84`, `99c77eb`) : précision des timestamps, `ESCAPE` sur les `LIKE`, plafond pagination, diverses remarques du 1er tour de review. - **Sidebar** (`701a480`, `e2fbf51`) : nouvelle section « Administration » + groupe « Mon compte », gate de section sur permissions, « Tableau de bord » déplacé dans « Mon compte ». Convention admin documentée. - **Drawer RBAC utilisateurs** (`617ee31`, `5f5afcc`) : corrige l'affichage des sites et l'écrasement via merge-patch (garde anti-écrasement + spec `GET /users/{id}/rbac` documentée). - **Swagger UI** (`6db955f`) : réactivé en ajoutant `symfony/twig-bundle` aux deps (régression depuis l'arrivée d'API Platform 4.2). - **`phpunit.dist.xml`** : `<env APP_ENV=dev>` forçait la suite à tourner sous `framework.test=false` (→ `test.service_container` introuvable) ; `JWT_PASSPHRASE` ne matchait pas les clés de dev. Corrigés pour débloquer la suite. ### E2E Playwright (nouveau, commit `4603ab2`) - `playwright.config.ts` + structure `frontend/tests/e2e/` (personas, helpers `loginAs`, page objects `LoginPage` + `SidebarComponent`). - Specs : `auth/login.spec.ts` + `permissions/sidebar-visibility.spec.ts` (vérifie la visibilité de la sidebar par rôle RBAC). - Commande `SeedE2ECommand` pour préparer un jeu de données déterministe côté backend. - `make e2e` ajouté au Makefile. ## Décisions techniques - **UUID v7 natif Postgres** (16 octets vs 36 en varchar) : index `performed_at` ~40 % plus petit sur une table append-only à croissance infinie. - **`entity_type` format `module.Entity`** (ex: `core.User`) : évite les collisions si deux modules ont des entités de même nom. - **`performed_by` dénormalisé** (string, pas FK) : le nom persiste même après suppression de l'utilisateur. - **Connexion DBAL dédiée `audit`** : évite l'entanglement transactionnel entre audit et ORM en batch. - **`ManyToMany` non audité** : limitation connue (`getEntityChangeSet()` ne couvre pas les collections) ; extension future via `getScheduledCollectionUpdates()` si besoin. - **Filtres locaux non persistés dans l'URL** : choix assumé (cf. CLAUDE.md) pour éviter le couplage table ↔ routeur. ## Test plan - [x] `make test` : 218 tests passent (writer unitaires + listener intégration + API fonctionnels + UserRbacProcessor). - [x] `npm run lint` + `npm run test` + `npm run build` (frontend). - [x] Migration appliquée sur dev + test, `audit_log` ignoré par `schema_filter`. - [x] Permissions synchronisées (`app:sync-permissions`). - [x] Swagger `/api/docs` accessible de nouveau. - [ ] Playwright : `make e2e` vert en local (login + sidebar-visibility). - [ ] Vérifier en local : création/modif/suppression d'un user apparaît dans `/admin/audit-log`. - [ ] Vérifier : user sans `core.audit_log.view` → 403 sur l'endpoint + item absent de la sidebar. - [ ] Vérifier : expansion d'une ligne affiche la timeline de l'entité avec dates relatives FR. - [ ] Vérifier : drawer RBAC utilisateur n'écrase plus la liste des sites au `PATCH`. ## Points d'attention pour le review - `AuditListener` : pattern swap-and-clear sur `postFlush` — relire la gestion des flushes ré-entrants. - `DbalPaginator` : vérifier que l'absence d'`Iterator` custom ne casse pas la normalisation API Platform sur collections vides. - `UserRbacProcessor` : logique merge-patch + garde anti-écrasement des sites (régression corrigée dans `617ee31`). - Playwright : nouvelle dépendance de dev, s'assurer que `make e2e` ne fait pas partie du pipeline CI par défaut (à brancher explicitement). Co-authored-by: Matthieu <mtholot19@gmail.com> Reviewed-on: #9 Co-authored-by: matthieu <matthieu@yuno.malio.fr> Co-committed-by: matthieu <matthieu@yuno.malio.fr>
2026-05-13 08:29:30 +00:00
parent dce189d982
commit e6c8381b3c
92 changed files with 8543 additions and 2309 deletions
--- a/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessorTest.php
+++ b/tests/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessorTest.php
@@ -21,6 +21,8 @@ use PHPUnit\Framework\TestCase;
 use ReflectionClass;
 use stdClass;
 use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;

 /**
@@ -38,6 +40,7 @@ final class UserRbacProcessorTest extends TestCase
    private MockObject&UnitOfWork $unitOfWork;
    private MockObject&Security $security;
    private AdminHeadcountGuardInterface&MockObject $adminHeadcountGuard;
+    private RequestStack $requestStack;
    private UserRbacProcessor $processor;

    protected function setUp(): void
@@ -48,6 +51,12 @@ final class UserRbacProcessorTest extends TestCase
        $this->security            = $this->createMock(Security::class);
        $this->adminHeadcountGuard = $this->createMock(AdminHeadcountGuardInterface::class);

+        // Request vide par defaut pour les tests existants : la garde
+        // anti-ecrasement (restoreAbsentCollections) no-op quand le body est ''
+        // donc elle n'interfere pas avec les assertions deja en place.
+        $this->requestStack = new RequestStack();
+        $this->requestStack->push(new Request());
+
        $this->entityManager->method('getUnitOfWork')->willReturn($this->unitOfWork);

        // wrapInTransaction doit executer reellement la closure pour que le
@@ -63,6 +72,7 @@ final class UserRbacProcessorTest extends TestCase
            $this->entityManager,
            $this->security,
            $this->adminHeadcountGuard,
+            $this->requestStack,
        );
    }

--- a/tests/Module/Core/Infrastructure/Audit/AuditLogWriterTest.php
+++ b/tests/Module/Core/Infrastructure/Audit/AuditLogWriterTest.php
@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Infrastructure\Audit;
+
+use App\Module\Core\Infrastructure\Audit\AuditLogWriter;
+use App\Module\Core\Infrastructure\Audit\RequestIdProvider;
+use Doctrine\DBAL\Connection;
+use PHPUnit\Framework\Attributes\AllowMockObjectsWithoutExpectations;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\Security\Core\User\InMemoryUser;
+
+/**
+ * Tests unitaires de l'AuditLogWriter.
+ *
+ * Verifie les invariants critiques :
+ *  - filtrage des cles sensibles (defense-in-depth par rapport a #[AuditIgnore]) ;
+ *  - utilisation du username courant ou "system" en CLI ;
+ *  - captation IP + request_id si requete HTTP presente ;
+ *  - generation d'un UUID v7 (tri chronologique implicite en PK).
+ *
+ * Aucune BDD : la connexion DBAL est mockee pour capturer l'insert.
+ *
+ * @internal
+ */
+#[AllowMockObjectsWithoutExpectations]
+final class AuditLogWriterTest extends TestCase
+{
+    /**
+     * @var null|array{0: string, 1: array<string, mixed>, 2: array<string, mixed>}
+     *
+     * Capture de l'appel `insert()` : [$table, $data, $types]
+     */
+    private ?array $capturedInsert = null;
+
+    private Connection $connection;
+
+    private RequestStack $requestStack;
+
+    private RequestIdProvider $requestIdProvider;
+
+    protected function setUp(): void
+    {
+        $this->capturedInsert = null;
+
+        $this->connection = $this->createMock(Connection::class);
+        $this->connection
+            ->method('insert')
+            ->willReturnCallback(function (string $table, array $data, array $types = []): int {
+                $this->capturedInsert = [$table, $data, $types];
+
+                return 1;
+            })
+        ;
+
+        $this->requestStack      = new RequestStack();
+        $this->requestIdProvider = new RequestIdProvider();
+    }
+
+    public function testLogsCreateWithAuthenticatedUser(): void
+    {
+        $security = $this->buildSecurityWithUser('alice');
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '42', 'create', ['username' => 'alice']);
+
+        $this->assertNotNull($this->capturedInsert);
+        [$table, $data] = $this->capturedInsert;
+        $this->assertSame('audit_log', $table);
+        $this->assertSame('core.User', $data['entity_type']);
+        $this->assertSame('42', $data['entity_id']);
+        $this->assertSame('create', $data['action']);
+        $this->assertSame(['username' => 'alice'], $data['changes']);
+        $this->assertSame('alice', $data['performed_by']);
+    }
+
+    public function testUsesSystemWhenNoAuthenticatedUser(): void
+    {
+        $security = $this->buildSecurityWithUser(null);
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'update', ['isAdmin' => ['old' => false, 'new' => true]]);
+
+        $this->assertSame('system', $this->capturedInsert[1]['performed_by']);
+    }
+
+    public function testStripsSensitiveKeys(): void
+    {
+        $security = $this->buildSecurityWithUser('alice');
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'create', [
+            'username'      => 'bob',
+            'password'      => 'topsecrethash',
+            'plainPassword' => 'clear',
+            'token'         => 'abc',
+            'secret'        => 'xyz',
+            'email'         => 'bob@example.com',
+        ]);
+
+        $changes = $this->capturedInsert[1]['changes'];
+        $this->assertArrayNotHasKey('password', $changes);
+        $this->assertArrayNotHasKey('plainPassword', $changes);
+        $this->assertArrayNotHasKey('token', $changes);
+        $this->assertArrayNotHasKey('secret', $changes);
+        $this->assertSame('bob', $changes['username']);
+        $this->assertSame('bob@example.com', $changes['email']);
+    }
+
+    public function testStripsSensitiveKeysRecursively(): void
+    {
+        // Defense-in-depth : un appelant direct peut passer un payload
+        // imbrique (ex: relations embarquees). Les cles sensibles doivent
+        // etre supprimees a tous les niveaux de profondeur.
+        $security = $this->buildSecurityWithUser('alice');
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'create', [
+            'username' => 'bob',
+            'profile'  => [
+                'email'    => 'bob@example.com',
+                'password' => 'leaked_in_nested',
+                'nested'   => [
+                    'token'    => 'should_be_stripped',
+                    'harmless' => 'kept',
+                ],
+            ],
+        ]);
+
+        $changes = $this->capturedInsert[1]['changes'];
+        $this->assertArrayNotHasKey('password', $changes['profile']);
+        $this->assertArrayNotHasKey('token', $changes['profile']['nested']);
+        $this->assertSame('kept', $changes['profile']['nested']['harmless']);
+        $this->assertSame('bob@example.com', $changes['profile']['email']);
+    }
+
+    public function testCapturesIpAddressWhenRequestPresent(): void
+    {
+        $request = Request::create('/api/users', 'POST');
+        $request->server->set('REMOTE_ADDR', '203.0.113.42');
+        $this->requestStack->push($request);
+
+        $security = $this->buildSecurityWithUser('alice');
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'create', []);
+
+        $this->assertSame('203.0.113.42', $this->capturedInsert[1]['ip_address']);
+    }
+
+    public function testIpAddressNullInCli(): void
+    {
+        $security = $this->buildSecurityWithUser(null);
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'create', []);
+
+        $this->assertNull($this->capturedInsert[1]['ip_address']);
+        $this->assertNull($this->capturedInsert[1]['request_id']);
+    }
+
+    public function testGeneratesUuidV7PrimaryKey(): void
+    {
+        $security = $this->buildSecurityWithUser('alice');
+        $writer   = new AuditLogWriter($this->connection, $security, $this->requestStack, $this->requestIdProvider);
+
+        $writer->log('core.User', '1', 'create', []);
+
+        $id = $this->capturedInsert[1]['id'];
+        // UUID v7 : le 13e caractere (apres les tirets) vaut "7".
+        // Format : xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx
+        $this->assertMatchesRegularExpression(
+            '/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/i',
+            $id
+        );
+    }
+
+    private function buildSecurityWithUser(?string $username): Security
+    {
+        $security = $this->createMock(Security::class);
+        $user     = null !== $username ? new InMemoryUser($username, 'pwd') : null;
+        $security->method('getUser')->willReturn($user);
+
+        return $security;
+    }
+}
--- a/tests/Module/Core/Infrastructure/Doctrine/AuditListenerTest.php
+++ b/tests/Module/Core/Infrastructure/Doctrine/AuditListenerTest.php
@@ -0,0 +1,423 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Module\Core\Infrastructure\Doctrine;
+
+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\Doctrine\AuditListener;
+use Doctrine\DBAL\Connection;
+use Doctrine\ORM\EntityManagerInterface;
+use ReflectionProperty;
+use stdClass;
+use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
+use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
+
+/**
+ * Tests d'integration de l'AuditListener.
+ *
+ * Contrairement aux tests unitaires du writer, on fait tourner le kernel
+ * complet pour verifier que le listener est bien cable et que les attributs
+ * #[Auditable] / #[AuditIgnore] sur User sont respectes jusqu'a l'insert
+ * final dans audit_log.
+ *
+ * Strategie de nettoyage : chaque test supprime ses fixtures dans tearDown
+ * (pas de rollback transactionnel DAMA sur ce projet).
+ *
+ * @internal
+ */
+final class AuditListenerTest extends KernelTestCase
+{
+    private EntityManagerInterface $em;
+
+    private Connection $auditConnection;
+
+    /** @var list<int> IDs de users crees par le test (nettoyage en tearDown) */
+    private array $createdUserIds = [];
+
+    /** @var list<int> IDs de roles crees par le test (nettoyage en tearDown) */
+    private array $createdRoleIds = [];
+
+    private string $testRunTag;
+
+    protected function setUp(): void
+    {
+        self::bootKernel();
+
+        /** @var EntityManagerInterface $em */
+        $em       = self::getContainer()->get('doctrine')->getManager();
+        $this->em = $em;
+
+        /** @var Connection $conn */
+        $conn                  = self::getContainer()->get('doctrine.dbal.audit_connection');
+        $this->auditConnection = $conn;
+
+        // Tag unique par run pour filtrer les lignes audit_log produites
+        // exclusivement par ce test (la table n'a ni truncate ni rollback).
+        $this->testRunTag = 'audittest'.bin2hex(random_bytes(4));
+    }
+
+    protected function tearDown(): void
+    {
+        // Suppression explicite des users crees (cascade sur user_role /
+        // user_site via les ORM mappings) + nettoyage des lignes audit
+        // correspondantes pour ne pas polluer les runs suivants.
+        if ([] !== $this->createdUserIds) {
+            foreach ($this->createdUserIds as $id) {
+                $user = $this->em->find(User::class, $id);
+                if (null !== $user) {
+                    $this->em->remove($user);
+                }
+            }
+            $this->em->flush();
+        }
+
+        if ([] !== $this->createdRoleIds) {
+            foreach ($this->createdRoleIds as $id) {
+                $role = $this->em->find(Role::class, $id);
+                if (null !== $role) {
+                    $this->em->remove($role);
+                }
+            }
+            $this->em->flush();
+            // Nettoie egalement les lignes audit de ces roles (entity_id est
+            // une colonne text, on delete en boucle pour simplifier le binding).
+            foreach ($this->createdRoleIds as $id) {
+                $this->auditConnection->executeStatement(
+                    'DELETE FROM audit_log WHERE entity_type = \'core.Role\' AND entity_id = :id',
+                    ['id' => (string) $id],
+                );
+            }
+        }
+
+        $this->auditConnection->executeStatement(
+            "DELETE FROM audit_log WHERE entity_type = 'core.User' AND changes->>'username' LIKE :tag",
+            ['tag' => $this->testRunTag.'%'],
+        );
+
+        // Libere la connexion PG : en test, le kernel reboote par test et
+        // sans close explicite, la connexion `audit` reste ouverte jusqu'au
+        // TTL Doctrine, saturant le pool sur une suite de 200+ tests.
+        $this->auditConnection->close();
+
+        parent::tearDown();
+    }
+
+    public function testLogsCreateOnUserInsertion(): void
+    {
+        $user = $this->makeUser();
+
+        $this->em->persist($user);
+        $this->em->flush();
+        $this->createdUserIds[] = $user->getId();
+
+        $rows = $this->fetchAuditRows($user->getId());
+
+        $this->assertCount(1, $rows, 'Une ligne audit attendue a la creation');
+        $row = $rows[0];
+        $this->assertSame('core.User', $row['entity_type']);
+        $this->assertSame('create', $row['action']);
+        $this->assertSame((string) $user->getId(), $row['entity_id']);
+
+        $changes = json_decode($row['changes'], true, 512, JSON_THROW_ON_ERROR);
+        $this->assertArrayHasKey('username', $changes);
+        $this->assertArrayNotHasKey('password', $changes, 'password doit etre #[AuditIgnore]');
+        $this->assertArrayNotHasKey('plainPassword', $changes, 'plainPassword doit etre #[AuditIgnore]');
+    }
+
+    public function testLogsUpdateWithDiff(): void
+    {
+        $user = $this->makeUser();
+        $this->em->persist($user);
+        $this->em->flush();
+        $this->createdUserIds[] = $user->getId();
+
+        // Reset de la baseline : on ne garde que la ligne update.
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_id = :id AND entity_type = \'core.User\'',
+            ['id' => (string) $user->getId()],
+        );
+
+        $user->setIsAdmin(true);
+        $this->em->flush();
+
+        $rows = $this->fetchAuditRows($user->getId());
+        $this->assertCount(1, $rows);
+        $this->assertSame('update', $rows[0]['action']);
+
+        $changes = json_decode($rows[0]['changes'], true, 512, JSON_THROW_ON_ERROR);
+        $this->assertArrayHasKey('isAdmin', $changes);
+        $this->assertSame(false, $changes['isAdmin']['old']);
+        $this->assertSame(true, $changes['isAdmin']['new']);
+    }
+
+    public function testLogsDeleteSnapshot(): void
+    {
+        $user = $this->makeUser();
+        $this->em->persist($user);
+        $this->em->flush();
+        $userId = $user->getId();
+
+        $this->em->remove($user);
+        $this->em->flush();
+
+        $rows = $this->fetchAuditRows($userId);
+        // Deux lignes : la creation + la suppression.
+        $actions = array_column($rows, 'action');
+        $this->assertContains('delete', $actions);
+
+        $deleteRow = $rows[array_search('delete', $actions, true)];
+        $changes   = json_decode($deleteRow['changes'], true, 512, JSON_THROW_ON_ERROR);
+        $this->assertArrayHasKey('username', $changes);
+        $this->assertArrayNotHasKey('password', $changes);
+
+        // On nettoie a la main les lignes restantes (user deja delete).
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_id = :id AND entity_type = \'core.User\'',
+            ['id' => (string) $userId],
+        );
+    }
+
+    /**
+     * Regression test : une entite recuperee via `getReference()` (proxy /
+     * ghost object lazy) doit etre auditee avec le FQCN canonique. Sur
+     * Doctrine ORM 3 + PHP 8.4, les lazy ghosts preservent `::class` reel
+     * — mais sous Doctrine 2 ou en cas de retour a un `__CG__\` proxy,
+     * l'audit doit toujours resoudre la classe via `ClassMetadata` et
+     * jamais aboutir a un `entity_type` de type `Proxies\__CG__\...\User`.
+     */
+    public function testLogsUpdateOnProxyEntity(): void
+    {
+        $user = $this->makeUser();
+        $this->em->persist($user);
+        $this->em->flush();
+        $userId                 = (int) $user->getId();
+        $this->createdUserIds[] = $userId;
+
+        // Detache puis recupere via getReference : sur Doctrine 2, renvoie
+        // un `Proxies\__CG__\...\User` ; sur Doctrine 3 + PHP 8.4 le ghost
+        // object reste instance de la classe reelle — dans tous les cas la
+        // resolution via ClassMetadata doit produire un audit correct.
+        $this->em->clear();
+
+        $proxy = $this->em->getReference(User::class, $userId);
+        self::assertNotNull($proxy);
+
+        // Reset de la baseline : on ne garde que la ligne update du proxy.
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_id = :id AND entity_type = \'core.User\'',
+            ['id' => (string) $userId],
+        );
+
+        $proxy->setIsAdmin(true);
+        $this->em->flush();
+
+        $rows = $this->fetchAuditRows($userId);
+        self::assertCount(1, $rows, 'La mutation sur un proxy doit etre auditee.');
+        self::assertSame('update', $rows[0]['action']);
+        // L'entity_type doit etre le FQCN canonique, pas celui du proxy.
+        self::assertSame('core.User', $rows[0]['entity_type']);
+    }
+
+    /**
+     * Verifie que l'ajout d'une permission a un role est bien audite sous
+     * la forme `{permissions: {added: [id], removed: []}}`. Regression test
+     * pour le bug "ManyToMany collections ignorees par getEntityChangeSet".
+     */
+    public function testLogsManyToManyCollectionAddition(): void
+    {
+        $roleCode = 'audittest_'.bin2hex(random_bytes(3));
+        $role     = new Role($roleCode, 'Test role '.$roleCode);
+        $this->em->persist($role);
+        $this->em->flush();
+        $roleId                 = (int) $role->getId();
+        $this->createdRoleIds[] = $roleId;
+
+        // Reset baseline : on ne veut que le log de l'update de collection.
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_type = \'core.Role\' AND entity_id = :id',
+            ['id' => (string) $roleId],
+        );
+
+        // Recupere une permission existante (fixtures garantissent core.users.view).
+        $permission = $this->em->getRepository(Permission::class)->findOneBy(['code' => 'core.users.view']);
+        self::assertNotNull($permission, 'Fixture core.users.view manquante.');
+
+        $role->addPermission($permission);
+        $this->em->flush();
+
+        $rows = $this->fetchRoleAuditRows($roleId);
+        self::assertCount(1, $rows, 'Une ligne update attendue pour l\'ajout de permission.');
+        self::assertSame('update', $rows[0]['action']);
+
+        $changes = json_decode($rows[0]['changes'], true, 512, JSON_THROW_ON_ERROR);
+        self::assertArrayHasKey('permissions', $changes, 'Le changeset doit contenir le champ "permissions".');
+        self::assertSame([], $changes['permissions']['removed']);
+        self::assertSame([(int) $permission->getId()], $changes['permissions']['added']);
+    }
+
+    /**
+     * Symetrique : retirer une permission d'un role est audite sous
+     * `{permissions: {added: [], removed: [id]}}`.
+     */
+    public function testLogsManyToManyCollectionRemoval(): void
+    {
+        $permission = $this->em->getRepository(Permission::class)->findOneBy(['code' => 'core.users.view']);
+        self::assertNotNull($permission);
+
+        $roleCode = 'audittest_'.bin2hex(random_bytes(3));
+        $role     = new Role($roleCode, 'Test role '.$roleCode);
+        $role->addPermission($permission);
+        $this->em->persist($role);
+        $this->em->flush();
+        $roleId                 = (int) $role->getId();
+        $this->createdRoleIds[] = $roleId;
+
+        // Reset baseline.
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_type = \'core.Role\' AND entity_id = :id',
+            ['id' => (string) $roleId],
+        );
+
+        $role->removePermission($permission);
+        $this->em->flush();
+
+        $rows = $this->fetchRoleAuditRows($roleId);
+        self::assertCount(1, $rows);
+        $changes = json_decode($rows[0]['changes'], true, 512, JSON_THROW_ON_ERROR);
+        self::assertSame([], $changes['permissions']['added']);
+        self::assertSame([(int) $permission->getId()], $changes['permissions']['removed']);
+    }
+
+    /**
+     * Regression test : supprimer un role avec des permissions attachees doit
+     * preserver la liste des permissions dans le snapshot delete. C'etait le
+     * trou principal du fix ManyToMany initial (reviewer Codex round 2).
+     */
+    public function testDeleteSnapshotIncludesManyToManyIds(): void
+    {
+        $permission = $this->em->getRepository(Permission::class)->findOneBy(['code' => 'core.users.view']);
+        self::assertNotNull($permission);
+
+        $roleCode = 'audittest_'.bin2hex(random_bytes(3));
+        $role     = new Role($roleCode, 'Delete test '.$roleCode);
+        $role->addPermission($permission);
+        $this->em->persist($role);
+        $this->em->flush();
+        $roleId = (int) $role->getId();
+
+        $this->em->remove($role);
+        $this->em->flush();
+
+        $rows = $this->fetchRoleAuditRows($roleId);
+        // create + update (permission ajoutee) + delete attendus.
+        $actions = array_column($rows, 'action');
+        self::assertContains('delete', $actions);
+
+        $deleteRow = $rows[array_search('delete', $actions, true)];
+        $changes   = json_decode($deleteRow['changes'], true, 512, JSON_THROW_ON_ERROR);
+
+        // Le snapshot delete doit contenir la liste des IDs de permissions
+        // attachees au role au moment de la suppression.
+        self::assertArrayHasKey('permissions', $changes);
+        self::assertSame([(int) $permission->getId()], $changes['permissions']);
+
+        // Nettoyage manuel (le role est deja supprime, on ne peut plus passer par $this->em).
+        $this->auditConnection->executeStatement(
+            'DELETE FROM audit_log WHERE entity_type = \'core.Role\' AND entity_id = :id',
+            ['id' => (string) $roleId],
+        );
+    }
+
+    /**
+     * Regression : quand un flush precedent a leve une exception avant
+     * d'atteindre postFlush, `$pendingLogs` reste rempli avec des changements
+     * jamais committes. Le flush suivant doit les ecraser, pas les fusionner —
+     * sinon audit_log contient des lignes pour des evenements qui n'ont pas
+     * eu lieu en base.
+     *
+     * Reproduction : on injecte manuellement une entree orpheline dans le
+     * listener (comme si un flush precedent l'avait capturee puis avait plante),
+     * on declenche un flush valide, et on verifie que l'orpheline n'apparait
+     * jamais dans audit_log.
+     */
+    public function testOnFlushResetsStalePendingLogsFromFailedPreviousFlush(): void
+    {
+        /** @var AuditListener $listener */
+        $listener = self::getContainer()->get(AuditListener::class);
+
+        // Injecte une entree orpheline : comme si onFlush avait capture ce
+        // changement, puis que le flush avait plante avant postFlush.
+        $reflection = new ReflectionProperty($listener, 'pendingLogs');
+        $reflection->setValue($listener, [[
+            'entity'     => new stdClass(),
+            'metadata'   => null,
+            'entityType' => 'test.StaleEntity',
+            'action'     => 'create',
+            'changes'    => ['fake' => ['old' => null, 'new' => 'stale']],
+            'capturedId' => 'stale-id-'.$this->testRunTag,
+        ]]);
+
+        // Flush valide qui DOIT re-initialiser pendingLogs avant de capturer
+        // ses propres changements.
+        $user = $this->makeUser();
+        $this->em->persist($user);
+        $this->em->flush();
+        $this->createdUserIds[] = $user->getId();
+
+        $staleRows = $this->auditConnection->fetchAllAssociative(
+            'SELECT * FROM audit_log WHERE entity_type = :t',
+            ['t' => 'test.StaleEntity'],
+        );
+
+        self::assertCount(
+            0,
+            $staleRows,
+            'Une entree orpheline d\'un flush precedent ne doit pas fuiter dans audit_log.',
+        );
+
+        // Sanity : le vrai flush a quand meme bien ecrit sa propre ligne.
+        $userRows = $this->fetchAuditRows($user->getId());
+        self::assertCount(1, $userRows);
+        self::assertSame('create', $userRows[0]['action']);
+    }
+
+    /**
+     * @return list<array{id: string, entity_type: string, entity_id: string, action: string, changes: string}>
+     */
+    private function fetchAuditRows(int $userId): array
+    {
+        // @var list<array{id: string, entity_type: string, entity_id: string, action: string, changes: string}> $rows
+        return $this->auditConnection->fetchAllAssociative(
+            'SELECT id, entity_type, entity_id, action, changes FROM audit_log WHERE entity_type = :type AND entity_id = :id ORDER BY performed_at ASC',
+            ['type' => 'core.User', 'id' => (string) $userId],
+        );
+    }
+
+    private function makeUser(): User
+    {
+        /** @var UserPasswordHasherInterface $hasher */
+        $hasher = self::getContainer()->get(UserPasswordHasherInterface::class);
+
+        $user = new User();
+        $user->setUsername($this->testRunTag.'_'.bin2hex(random_bytes(2)));
+        $user->setIsAdmin(false);
+        $user->setPassword($hasher->hashPassword($user, 'testpass'));
+
+        return $user;
+    }
+
+    /**
+     * @return list<array{id: string, entity_type: string, entity_id: string, action: string, changes: string}>
+     */
+    private function fetchRoleAuditRows(int $roleId): array
+    {
+        // @var list<array{id: string, entity_type: string, entity_id: string, action: string, changes: string}> $rows
+        return $this->auditConnection->fetchAllAssociative(
+            'SELECT id, entity_type, entity_id, action, changes FROM audit_log WHERE entity_type = :type AND entity_id = :id ORDER BY performed_at ASC',
+            ['type' => 'core.Role', 'id' => (string) $roleId],
+        );
+    }
+}