feat: Optimiser la pagination avec cache-aside et ports de lecture dédiés

Les listes paginées (utilisateurs, classes, matières, affectations,
invitations parents, droits à l'image) effectuaient des requêtes SQL
complètes à chaque chargement de page, sans aucun cache. Sur les
établissements avec plusieurs centaines d'enregistrements, cela causait
des temps de réponse perceptibles et une charge inutile sur PostgreSQL.

Cette refactorisation introduit un cache tag-aware (Redis en prod,
filesystem en dev) avec invalidation événementielle, et extrait les
requêtes de lecture dans des ports Application / implémentations DBAL
conformes à l'architecture hexagonale. Un middleware Messenger garantit
l'invalidation synchrone du cache même pour les événements routés en
asynchrone (envoi d'emails), évitant ainsi toute donnée périmée côté UI.

backend/tests/Unit/Administration/Application/Query/GetAllAssignments/GetAllAssignmentsHandlerTest.php

@@ -4,365 +4,140 @@ declare(strict_types=1);
 
 namespace App\Tests\Unit\Administration\Application\Query\GetAllAssignments;
 
+use App\Administration\Application\Dto\PaginatedResult;
+use App\Administration\Application\Port\PaginatedAssignmentsReader;
+use App\Administration\Application\Query\GetAllAssignments\AssignmentWithNamesDto;
 use App\Administration\Application\Query\GetAllAssignments\GetAllAssignmentsHandler;
 use App\Administration\Application\Query\GetAllAssignments\GetAllAssignmentsQuery;
-use App\Administration\Domain\Model\SchoolClass\AcademicYearId;
-use App\Administration\Domain\Model\SchoolClass\ClassName;
-use App\Administration\Domain\Model\SchoolClass\SchoolClass;
-use App\Administration\Domain\Model\SchoolClass\SchoolId;
-use App\Administration\Domain\Model\SchoolClass\SchoolLevel;
-use App\Administration\Domain\Model\Subject\Subject;
-use App\Administration\Domain\Model\Subject\SubjectCode;
-use App\Administration\Domain\Model\Subject\SubjectName;
-use App\Administration\Domain\Model\TeacherAssignment\TeacherAssignment;
-use App\Administration\Domain\Model\User\Email;
-use App\Administration\Domain\Model\User\Role;
-use App\Administration\Domain\Model\User\User;
-use App\Administration\Infrastructure\Persistence\InMemory\InMemoryClassRepository;
-use App\Administration\Infrastructure\Persistence\InMemory\InMemorySubjectRepository;
-use App\Administration\Infrastructure\Persistence\InMemory\InMemoryTeacherAssignmentRepository;
-use App\Administration\Infrastructure\Persistence\InMemory\InMemoryUserRepository;
-use App\Shared\Domain\Tenant\TenantId;
-
-use function count;
-
+use App\Administration\Application\Service\Cache\PaginatedQueryCache;
 use DateTimeImmutable;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
-use Psr\Log\NullLogger;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+use Symfony\Component\Cache\Adapter\TagAwareAdapter;
 
 final class GetAllAssignmentsHandlerTest extends TestCase
 {
-    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440002';
-    private const string OTHER_TENANT_ID = '550e8400-e29b-41d4-a716-446655440099';
-
-    private InMemoryTeacherAssignmentRepository $assignmentRepository;
-    private InMemoryUserRepository $userRepository;
-    private InMemoryClassRepository $classRepository;
-    private InMemorySubjectRepository $subjectRepository;
+    private PaginatedAssignmentsReader $reader;
+    private PaginatedQueryCache $cache;
     private GetAllAssignmentsHandler $handler;
 
     protected function setUp(): void
     {
-        $this->assignmentRepository = new InMemoryTeacherAssignmentRepository();
-        $this->userRepository = new InMemoryUserRepository();
-        $this->classRepository = new InMemoryClassRepository();
-        $this->subjectRepository = new InMemorySubjectRepository();
-        $this->handler = new GetAllAssignmentsHandler(
-            $this->assignmentRepository,
-            $this->userRepository,
-            $this->classRepository,
-            $this->subjectRepository,
-            new NullLogger(),
+        $this->reader = $this->createMock(PaginatedAssignmentsReader::class);
+        $this->cache = new PaginatedQueryCache(
+            new TagAwareAdapter(new ArrayAdapter()),
         );
+        $this->handler = new GetAllAssignmentsHandler($this->reader, $this->cache);
     }
 
     #[Test]
-    public function returnsAllActiveAssignmentsWithNames(): void
+    public function returnsItemsForTenant(): void
     {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(tenantId: self::TENANT_ID);
-        $result = ($this->handler)($query);
-
-        self::assertCount(2, $result->items);
-        self::assertSame(2, $result->total);
-        self::assertSame(1, $result->page);
-        self::assertSame(30, $result->limit);
-
-        // Verify denormalized names are populated
-        $dto = $result->items[0];
-        self::assertNotSame('', $dto->teacherFirstName);
-        self::assertNotSame('', $dto->className);
-        self::assertNotSame('', $dto->subjectName);
-    }
-
-    #[Test]
-    public function searchesByTeacherName(): void
-    {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            search: 'Jean',
+        $dto = $this->createAssignmentDto();
+        $this->reader->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [$dto], total: 1, page: 1, limit: 30),
         );
-        $result = ($this->handler)($query);
+
+        $result = ($this->handler)(new GetAllAssignmentsQuery(tenantId: 'tenant-1'));
 
         self::assertCount(1, $result->items);
-        self::assertSame('Jean', $result->items[0]->teacherFirstName);
+        self::assertSame(1, $result->total);
     }
 
     #[Test]
-    public function searchesByClassName(): void
+    public function mapsDtoFields(): void
     {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            search: '6ème',
+        $dto = $this->createAssignmentDto();
+        $this->reader->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [$dto], total: 1, page: 1, limit: 30),
         );
-        $result = ($this->handler)($query);
 
-        self::assertGreaterThanOrEqual(1, count($result->items));
-        self::assertStringContainsString('6ème', $result->items[0]->className);
-    }
+        $result = ($this->handler)(new GetAllAssignmentsQuery(tenantId: 'tenant-1'));
 
-    #[Test]
-    public function searchesBySubjectName(): void
-    {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            search: 'Français',
-        );
-        $result = ($this->handler)($query);
-
-        self::assertCount(1, $result->items);
-        self::assertSame('Français', $result->items[0]->subjectName);
-    }
-
-    #[Test]
-    public function searchIsCaseInsensitive(): void
-    {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            search: 'jean',
-        );
-        $result = ($this->handler)($query);
-
-        self::assertCount(1, $result->items);
-        self::assertSame('Jean', $result->items[0]->teacherFirstName);
+        $item = $result->items[0];
+        self::assertSame('assign-1', $item->id);
+        self::assertSame('teacher-1', $item->teacherId);
+        self::assertSame('Jean', $item->teacherFirstName);
+        self::assertSame('Dupont', $item->teacherLastName);
+        self::assertSame('class-1', $item->classId);
+        self::assertSame('6eme A', $item->className);
+        self::assertSame('subj-1', $item->subjectId);
+        self::assertSame('Mathematiques', $item->subjectName);
+        self::assertSame('year-1', $item->academicYearId);
+        self::assertSame('active', $item->status);
+        self::assertNull($item->endDate);
     }
 
     #[Test]
     public function paginatesResults(): void
     {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            page: 1,
-            limit: 1,
+        $this->reader->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [], total: 50, page: 2, limit: 10),
         );
-        $result = ($this->handler)($query);
 
-        self::assertCount(1, $result->items);
-        self::assertSame(2, $result->total);
-        self::assertSame(1, $result->page);
-        self::assertSame(1, $result->limit);
-        self::assertSame(2, $result->totalPages());
-    }
+        $result = ($this->handler)(new GetAllAssignmentsQuery(tenantId: 'tenant-1', page: 2, limit: 10));
 
-    #[Test]
-    public function returnsSecondPage(): void
-    {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            page: 2,
-            limit: 1,
-        );
-        $result = ($this->handler)($query);
-
-        self::assertCount(1, $result->items);
-        self::assertSame(2, $result->total);
+        self::assertSame(50, $result->total);
         self::assertSame(2, $result->page);
+        self::assertSame(10, $result->limit);
     }
 
     #[Test]
-    public function returnsEmptyWhenNoMatches(): void
+    public function cachesResult(): void
     {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            search: 'nonexistent',
+        $dto = $this->createAssignmentDto();
+        $this->reader->expects(self::once())->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [$dto], total: 1, page: 1, limit: 30),
         );
+
+        $query = new GetAllAssignmentsQuery(tenantId: 'tenant-1');
+        ($this->handler)($query);
         $result = ($this->handler)($query);
 
-        self::assertCount(0, $result->items);
-        self::assertSame(0, $result->total);
-    }
-
-    #[Test]
-    public function excludesAssignmentsFromOtherTenants(): void
-    {
-        $this->seedData();
-
-        $query = new GetAllAssignmentsQuery(tenantId: self::OTHER_TENANT_ID);
-        $result = ($this->handler)($query);
-
-        self::assertCount(0, $result->items);
-        self::assertSame(0, $result->total);
-    }
-
-    #[Test]
-    public function handlesOrphanedAssignment(): void
-    {
-        // Create an assignment with no matching teacher/class/subject
-        $tenantId = TenantId::fromString(self::TENANT_ID);
-        $now = new DateTimeImmutable('2026-02-01 10:00:00');
-
-        $orphanedClass = SchoolClass::creer(
-            tenantId: $tenantId,
-            schoolId: SchoolId::generate(),
-            academicYearId: AcademicYearId::generate(),
-            name: new ClassName('Orphan Class'),
-            level: null,
-            capacity: null,
-            createdAt: $now,
-        );
-        $this->classRepository->save($orphanedClass);
-
-        $orphanedSubject = Subject::creer(
-            tenantId: $tenantId,
-            schoolId: SchoolId::generate(),
-            name: new SubjectName('Orphan Subject'),
-            code: new SubjectCode('ORPH'),
-            color: null,
-            createdAt: $now,
-        );
-        $this->subjectRepository->save($orphanedSubject);
-
-        // Teacher does NOT exist in userRepository
-        $orphanedTeacher = User::inviter(
-            email: new Email('orphan@example.com'),
-            role: Role::PROF,
-            tenantId: TenantId::fromString(self::OTHER_TENANT_ID), // Different tenant — won't be found
-            schoolName: 'Autre',
-            firstName: 'Ghost',
-            lastName: 'Teacher',
-            invitedAt: $now,
-        );
-        $this->userRepository->save($orphanedTeacher);
-
-        $assignment = TeacherAssignment::creer(
-            tenantId: $tenantId,
-            teacherId: $orphanedTeacher->id,
-            classId: $orphanedClass->id,
-            subjectId: $orphanedSubject->id,
-            academicYearId: AcademicYearId::generate(),
-            createdAt: $now,
-        );
-        $this->assignmentRepository->save($assignment);
-
-        $query = new GetAllAssignmentsQuery(tenantId: self::TENANT_ID);
-        $result = ($this->handler)($query);
-
-        // Assignment should appear with empty teacher names (orphaned reference logged as warning)
         self::assertCount(1, $result->items);
-        self::assertSame('', $result->items[0]->teacherFirstName);
-        self::assertSame('', $result->items[0]->teacherLastName);
     }
 
     #[Test]
-    public function clampsInvalidPageToOne(): void
+    public function clampsPageToMinimumOne(): void
     {
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            page: -1,
+        $this->reader->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [], total: 0, page: 1, limit: 30),
         );
 
-        self::assertSame(1, $query->page);
+        $result = ($this->handler)(new GetAllAssignmentsQuery(tenantId: 'tenant-1', page: -5));
+
+        self::assertSame(1, $result->page);
     }
 
     #[Test]
-    public function clampsExcessiveLimitToMax(): void
+    public function clampsLimitToMaximumHundred(): void
     {
-        $query = new GetAllAssignmentsQuery(
-            tenantId: self::TENANT_ID,
-            limit: 999,
+        $this->reader->method('findPaginated')->willReturn(
+            new PaginatedResult(items: [], total: 0, page: 1, limit: 100),
         );
 
-        self::assertSame(100, $query->limit);
+        $result = ($this->handler)(new GetAllAssignmentsQuery(tenantId: 'tenant-1', limit: 500));
+
+        self::assertSame(100, $result->limit);
     }
 
-    private function seedData(): void
+    private function createAssignmentDto(): AssignmentWithNamesDto
     {
-        $tenantId = TenantId::fromString(self::TENANT_ID);
-        $schoolId = SchoolId::generate();
-        $academicYearId = AcademicYearId::generate();
-        $now = new DateTimeImmutable('2026-02-01 10:00:00');
-
-        // Create teachers
-        $teacher1 = User::inviter(
-            email: new Email('teacher1@example.com'),
-            role: Role::PROF,
-            tenantId: $tenantId,
-            schoolName: 'École Alpha',
-            firstName: 'Jean',
-            lastName: 'Dupont',
-            invitedAt: $now,
+        return new AssignmentWithNamesDto(
+            id: 'assign-1',
+            teacherId: 'teacher-1',
+            teacherFirstName: 'Jean',
+            teacherLastName: 'Dupont',
+            classId: 'class-1',
+            className: '6eme A',
+            subjectId: 'subj-1',
+            subjectName: 'Mathematiques',
+            academicYearId: 'year-1',
+            status: 'active',
+            startDate: new DateTimeImmutable('2026-02-01'),
+            endDate: null,
+            createdAt: new DateTimeImmutable('2026-01-15'),
         );
-        $this->userRepository->save($teacher1);
-
-        $teacher2 = User::inviter(
-            email: new Email('teacher2@example.com'),
-            role: Role::PROF,
-            tenantId: $tenantId,
-            schoolName: 'École Alpha',
-            firstName: 'Marie',
-            lastName: 'Martin',
-            invitedAt: $now,
-        );
-        $this->userRepository->save($teacher2);
-
-        // Create classes
-        $class1 = SchoolClass::creer(
-            tenantId: $tenantId,
-            schoolId: $schoolId,
-            academicYearId: $academicYearId,
-            name: new ClassName('6ème A'),
-            level: SchoolLevel::SIXIEME,
-            capacity: 30,
-            createdAt: $now,
-        );
-        $this->classRepository->save($class1);
-
-        // Create subjects
-        $subject1 = Subject::creer(
-            tenantId: $tenantId,
-            schoolId: $schoolId,
-            name: new SubjectName('Mathématiques'),
-            code: new SubjectCode('MATH'),
-            color: null,
-            createdAt: $now,
-        );
-        $this->subjectRepository->save($subject1);
-
-        $subject2 = Subject::creer(
-            tenantId: $tenantId,
-            schoolId: $schoolId,
-            name: new SubjectName('Français'),
-            code: new SubjectCode('FR'),
-            color: null,
-            createdAt: $now,
-        );
-        $this->subjectRepository->save($subject2);
-
-        // Create assignments
-        $assignment1 = TeacherAssignment::creer(
-            tenantId: $tenantId,
-            teacherId: $teacher1->id,
-            classId: $class1->id,
-            subjectId: $subject1->id,
-            academicYearId: $academicYearId,
-            createdAt: $now,
-        );
-        $this->assignmentRepository->save($assignment1);
-
-        $assignment2 = TeacherAssignment::creer(
-            tenantId: $tenantId,
-            teacherId: $teacher2->id,
-            classId: $class1->id,
-            subjectId: $subject2->id,
-            academicYearId: $academicYearId,
-            createdAt: $now,
-        );
-        $this->assignmentRepository->save($assignment2);
     }
 }