feat: Calculer automatiquement les moyennes après chaque saisie de notes

Les enseignants ont besoin de moyennes à jour immédiatement après la publication ou modification des notes, sans attendre un batch nocturne. Le système recalcule via Domain Events synchrones : statistiques d'évaluation (min/max/moyenne/médiane), moyennes matières pondérées (normalisation /20), et moyenne générale par élève. Les résultats sont stockés dans des tables dénormalisées avec cache Redis (TTL 5 min). Trois endpoints API exposent les données avec contrôle d'accès par rôle. Une commande console permet le backfill des données historiques au déploiement.
2026-03-30 06:22:03 +02:00
parent b70d5ec2ad
commit b7dc27f2a5
786 changed files with 118783 additions and 316 deletions
--- a/backend/tests/Unit/Scolarite/Application/Command/CreateAppreciationTemplate/CreateAppreciationTemplateHandlerTest.php
+++ b/backend/tests/Unit/Scolarite/Application/Command/CreateAppreciationTemplate/CreateAppreciationTemplateHandlerTest.php
@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Application\Command\CreateAppreciationTemplate;
+
+use App\Scolarite\Application\Command\CreateAppreciationTemplate\CreateAppreciationTemplateCommand;
+use App\Scolarite\Application\Command\CreateAppreciationTemplate\CreateAppreciationTemplateHandler;
+use App\Scolarite\Domain\Model\Grade\AppreciationCategory;
+use App\Scolarite\Infrastructure\Persistence\InMemory\InMemoryAppreciationTemplateRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CreateAppreciationTemplateHandlerTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string TEACHER_ID = '550e8400-e29b-41d4-a716-446655440010';
+
+    private InMemoryAppreciationTemplateRepository $templateRepository;
+    private Clock $clock;
+
+    protected function setUp(): void
+    {
+        $this->templateRepository = new InMemoryAppreciationTemplateRepository();
+        $this->clock = new class implements Clock {
+            public function now(): DateTimeImmutable
+            {
+                return new DateTimeImmutable('2026-03-31 10:00:00');
+            }
+        };
+    }
+
+    #[Test]
+    public function itCreatesTemplate(): void
+    {
+        $handler = new CreateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $template = $handler(new CreateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            title: 'Très bon travail',
+            content: 'Très bon travail, continuez ainsi !',
+            category: 'positive',
+        ));
+
+        self::assertSame('Très bon travail', $template->title);
+        self::assertSame('Très bon travail, continuez ainsi !', $template->content);
+        self::assertSame(AppreciationCategory::POSITIVE, $template->category);
+        self::assertSame(0, $template->usageCount);
+    }
+
+    #[Test]
+    public function itPersistsTemplate(): void
+    {
+        $handler = new CreateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $template = $handler(new CreateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            title: 'Test',
+            content: 'Contenu test',
+            category: null,
+        ));
+
+        $found = $this->templateRepository->findById(
+            $template->id,
+            TenantId::fromString(self::TENANT_ID),
+        );
+
+        self::assertNotNull($found);
+        self::assertSame('Test', $found->title);
+        self::assertNull($found->category);
+    }
+
+    #[Test]
+    public function itCreatesTemplateWithNullCategory(): void
+    {
+        $handler = new CreateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $template = $handler(new CreateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            title: 'Sans catégorie',
+            content: 'Contenu',
+            category: null,
+        ));
+
+        self::assertNull($template->category);
+    }
+}
--- a/backend/tests/Unit/Scolarite/Application/Command/DeleteAppreciationTemplate/DeleteAppreciationTemplateHandlerTest.php
+++ b/backend/tests/Unit/Scolarite/Application/Command/DeleteAppreciationTemplate/DeleteAppreciationTemplateHandlerTest.php
@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Application\Command\DeleteAppreciationTemplate;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Application\Command\DeleteAppreciationTemplate\DeleteAppreciationTemplateCommand;
+use App\Scolarite\Application\Command\DeleteAppreciationTemplate\DeleteAppreciationTemplateHandler;
+use App\Scolarite\Domain\Exception\AppreciationTemplateNonTrouveeException;
+use App\Scolarite\Domain\Exception\NonProprietaireDuModeleException;
+use App\Scolarite\Domain\Model\Grade\AppreciationCategory;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplate;
+use App\Scolarite\Infrastructure\Persistence\InMemory\InMemoryAppreciationTemplateRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class DeleteAppreciationTemplateHandlerTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string TEACHER_ID = '550e8400-e29b-41d4-a716-446655440010';
+
+    private InMemoryAppreciationTemplateRepository $templateRepository;
+    private Clock $clock;
+
+    protected function setUp(): void
+    {
+        $this->templateRepository = new InMemoryAppreciationTemplateRepository();
+        $this->clock = new class implements Clock {
+            public function now(): DateTimeImmutable
+            {
+                return new DateTimeImmutable('2026-03-31 10:00:00');
+            }
+        };
+    }
+
+    #[Test]
+    public function itDeletesTemplate(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new DeleteAppreciationTemplateHandler($this->templateRepository);
+
+        $handler(new DeleteAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: (string) $template->id,
+        ));
+
+        $found = $this->templateRepository->findById(
+            $template->id,
+            TenantId::fromString(self::TENANT_ID),
+        );
+
+        self::assertNull($found);
+    }
+
+    #[Test]
+    public function itThrowsWhenTemplateNotFound(): void
+    {
+        $handler = new DeleteAppreciationTemplateHandler($this->templateRepository);
+
+        $this->expectException(AppreciationTemplateNonTrouveeException::class);
+
+        $handler(new DeleteAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: '550e8400-e29b-41d4-a716-446655440099',
+        ));
+    }
+
+    #[Test]
+    public function itThrowsWhenTeacherNotOwner(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new DeleteAppreciationTemplateHandler($this->templateRepository);
+
+        $this->expectException(NonProprietaireDuModeleException::class);
+
+        $handler(new DeleteAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: '550e8400-e29b-41d4-a716-446655440099',
+            templateId: (string) $template->id,
+        ));
+    }
+
+    private function seedTemplate(): AppreciationTemplate
+    {
+        $template = AppreciationTemplate::creer(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Template test',
+            content: 'Contenu test',
+            category: AppreciationCategory::POSITIVE,
+            now: $this->clock->now(),
+        );
+
+        $this->templateRepository->save($template);
+
+        return $template;
+    }
+}
--- a/backend/tests/Unit/Scolarite/Application/Command/SaveAppreciation/SaveAppreciationHandlerTest.php
+++ b/backend/tests/Unit/Scolarite/Application/Command/SaveAppreciation/SaveAppreciationHandlerTest.php
@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Application\Command\SaveAppreciation;
+
+use App\Administration\Domain\Model\SchoolClass\ClassId;
+use App\Administration\Domain\Model\Subject\SubjectId;
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Application\Command\SaveAppreciation\SaveAppreciationCommand;
+use App\Scolarite\Application\Command\SaveAppreciation\SaveAppreciationHandler;
+use App\Scolarite\Domain\Exception\AppreciationTropLongueException;
+use App\Scolarite\Domain\Exception\GradeNotFoundException;
+use App\Scolarite\Domain\Exception\NonProprietaireDeLEvaluationException;
+use App\Scolarite\Domain\Model\Evaluation\Coefficient;
+use App\Scolarite\Domain\Model\Evaluation\Evaluation;
+use App\Scolarite\Domain\Model\Evaluation\EvaluationId;
+use App\Scolarite\Domain\Model\Evaluation\EvaluationStatus;
+use App\Scolarite\Domain\Model\Evaluation\GradeScale;
+use App\Scolarite\Domain\Model\Grade\Grade;
+use App\Scolarite\Domain\Model\Grade\GradeStatus;
+use App\Scolarite\Domain\Model\Grade\GradeValue;
+use App\Scolarite\Infrastructure\Persistence\InMemory\InMemoryEvaluationRepository;
+use App\Scolarite\Infrastructure\Persistence\InMemory\InMemoryGradeRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+use function str_repeat;
+
+final class SaveAppreciationHandlerTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string EVALUATION_ID = '550e8400-e29b-41d4-a716-446655440040';
+    private const string TEACHER_ID = '550e8400-e29b-41d4-a716-446655440010';
+    private const string STUDENT_ID = '550e8400-e29b-41d4-a716-446655440050';
+
+    private InMemoryEvaluationRepository $evaluationRepository;
+    private InMemoryGradeRepository $gradeRepository;
+    private Clock $clock;
+    private string $gradeId;
+
+    protected function setUp(): void
+    {
+        $this->evaluationRepository = new InMemoryEvaluationRepository();
+        $this->gradeRepository = new InMemoryGradeRepository();
+        $this->clock = new class implements Clock {
+            public function now(): DateTimeImmutable
+            {
+                return new DateTimeImmutable('2026-03-31 10:00:00');
+            }
+        };
+
+        $this->seedEvaluationAndGrade();
+    }
+
+    #[Test]
+    public function itSavesAppreciation(): void
+    {
+        $handler = $this->createHandler();
+
+        $grade = $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: $this->gradeId,
+            teacherId: self::TEACHER_ID,
+            appreciation: 'Très bon travail',
+        ));
+
+        self::assertSame('Très bon travail', $grade->appreciation);
+        self::assertNotNull($grade->appreciationUpdatedAt);
+    }
+
+    #[Test]
+    public function itClearsAppreciation(): void
+    {
+        $handler = $this->createHandler();
+
+        $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: $this->gradeId,
+            teacherId: self::TEACHER_ID,
+            appreciation: 'Bon travail',
+        ));
+
+        $grade = $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: $this->gradeId,
+            teacherId: self::TEACHER_ID,
+            appreciation: null,
+        ));
+
+        self::assertNull($grade->appreciation);
+    }
+
+    #[Test]
+    public function itThrowsWhenTeacherNotOwner(): void
+    {
+        $handler = $this->createHandler();
+
+        $this->expectException(NonProprietaireDeLEvaluationException::class);
+
+        $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: $this->gradeId,
+            teacherId: '550e8400-e29b-41d4-a716-446655440099',
+            appreciation: 'Test',
+        ));
+    }
+
+    #[Test]
+    public function itThrowsWhenGradeNotFound(): void
+    {
+        $handler = $this->createHandler();
+
+        $this->expectException(GradeNotFoundException::class);
+
+        $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: '550e8400-e29b-41d4-a716-446655440099',
+            teacherId: self::TEACHER_ID,
+            appreciation: 'Test',
+        ));
+    }
+
+    #[Test]
+    public function itThrowsWhenAppreciationTooLong(): void
+    {
+        $handler = $this->createHandler();
+
+        $this->expectException(AppreciationTropLongueException::class);
+
+        $handler(new SaveAppreciationCommand(
+            tenantId: self::TENANT_ID,
+            gradeId: $this->gradeId,
+            teacherId: self::TEACHER_ID,
+            appreciation: str_repeat('a', 501),
+        ));
+    }
+
+    private function createHandler(): SaveAppreciationHandler
+    {
+        return new SaveAppreciationHandler(
+            $this->evaluationRepository,
+            $this->gradeRepository,
+            $this->clock,
+        );
+    }
+
+    private function seedEvaluationAndGrade(): void
+    {
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+
+        $evaluation = Evaluation::reconstitute(
+            id: EvaluationId::fromString(self::EVALUATION_ID),
+            tenantId: $tenantId,
+            classId: ClassId::fromString('550e8400-e29b-41d4-a716-446655440020'),
+            subjectId: SubjectId::fromString('550e8400-e29b-41d4-a716-446655440030'),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Contrôle',
+            description: null,
+            evaluationDate: new DateTimeImmutable('2026-04-15'),
+            gradeScale: new GradeScale(20),
+            coefficient: new Coefficient(1.0),
+            status: EvaluationStatus::PUBLISHED,
+            createdAt: new DateTimeImmutable('2026-03-12 10:00:00'),
+            updatedAt: new DateTimeImmutable('2026-03-12 10:00:00'),
+        );
+
+        $this->evaluationRepository->save($evaluation);
+
+        $grade = Grade::saisir(
+            tenantId: $tenantId,
+            evaluationId: EvaluationId::fromString(self::EVALUATION_ID),
+            studentId: UserId::fromString(self::STUDENT_ID),
+            value: new GradeValue(15.5),
+            status: GradeStatus::GRADED,
+            gradeScale: new GradeScale(20),
+            createdBy: UserId::fromString(self::TEACHER_ID),
+            now: new DateTimeImmutable('2026-03-27 10:00:00'),
+        );
+
+        $this->gradeRepository->save($grade);
+        $this->gradeId = (string) $grade->id;
+    }
+}
--- a/backend/tests/Unit/Scolarite/Application/Command/UpdateAppreciationTemplate/UpdateAppreciationTemplateHandlerTest.php
+++ b/backend/tests/Unit/Scolarite/Application/Command/UpdateAppreciationTemplate/UpdateAppreciationTemplateHandlerTest.php
@@ -0,0 +1,173 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Application\Command\UpdateAppreciationTemplate;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Application\Command\UpdateAppreciationTemplate\UpdateAppreciationTemplateCommand;
+use App\Scolarite\Application\Command\UpdateAppreciationTemplate\UpdateAppreciationTemplateHandler;
+use App\Scolarite\Domain\Exception\AppreciationTemplateNonTrouveeException;
+use App\Scolarite\Domain\Exception\CategorieAppreciationInvalideException;
+use App\Scolarite\Domain\Exception\NonProprietaireDuModeleException;
+use App\Scolarite\Domain\Model\Grade\AppreciationCategory;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplate;
+use App\Scolarite\Infrastructure\Persistence\InMemory\InMemoryAppreciationTemplateRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class UpdateAppreciationTemplateHandlerTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string TEACHER_ID = '550e8400-e29b-41d4-a716-446655440010';
+
+    private InMemoryAppreciationTemplateRepository $templateRepository;
+    private Clock $clock;
+
+    protected function setUp(): void
+    {
+        $this->templateRepository = new InMemoryAppreciationTemplateRepository();
+        $this->clock = new class implements Clock {
+            public function now(): DateTimeImmutable
+            {
+                return new DateTimeImmutable('2026-03-31 10:00:00');
+            }
+        };
+    }
+
+    #[Test]
+    public function itUpdatesTemplate(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $updated = $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: (string) $template->id,
+            title: 'Titre modifié',
+            content: 'Contenu modifié',
+            category: 'improvement',
+        ));
+
+        self::assertSame('Titre modifié', $updated->title);
+        self::assertSame('Contenu modifié', $updated->content);
+        self::assertSame(AppreciationCategory::IMPROVEMENT, $updated->category);
+    }
+
+    #[Test]
+    public function itPersistsUpdatedTemplate(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: (string) $template->id,
+            title: 'Persisté',
+            content: 'Contenu persisté',
+            category: null,
+        ));
+
+        $found = $this->templateRepository->findById(
+            $template->id,
+            TenantId::fromString(self::TENANT_ID),
+        );
+
+        self::assertNotNull($found);
+        self::assertSame('Persisté', $found->title);
+        self::assertNull($found->category);
+    }
+
+    #[Test]
+    public function itThrowsWhenTemplateNotFound(): void
+    {
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $this->expectException(AppreciationTemplateNonTrouveeException::class);
+
+        $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: '550e8400-e29b-41d4-a716-446655440099',
+            title: 'Test',
+            content: 'Contenu',
+            category: null,
+        ));
+    }
+
+    #[Test]
+    public function itThrowsWhenTeacherNotOwner(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $this->expectException(NonProprietaireDuModeleException::class);
+
+        $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: '550e8400-e29b-41d4-a716-446655440099',
+            templateId: (string) $template->id,
+            title: 'Hijack',
+            content: 'Contenu',
+            category: null,
+        ));
+    }
+
+    #[Test]
+    public function itThrowsWhenCategoryInvalid(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $this->expectException(CategorieAppreciationInvalideException::class);
+
+        $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: (string) $template->id,
+            title: 'Test',
+            content: 'Contenu',
+            category: 'invalid_category',
+        ));
+    }
+
+    #[Test]
+    public function itUpdatesTemplateWithNullCategory(): void
+    {
+        $template = $this->seedTemplate();
+        $handler = new UpdateAppreciationTemplateHandler($this->templateRepository, $this->clock);
+
+        $updated = $handler(new UpdateAppreciationTemplateCommand(
+            tenantId: self::TENANT_ID,
+            teacherId: self::TEACHER_ID,
+            templateId: (string) $template->id,
+            title: 'Sans catégorie',
+            content: 'Contenu mis à jour',
+            category: null,
+        ));
+
+        self::assertNull($updated->category);
+        self::assertSame('Sans catégorie', $updated->title);
+    }
+
+    private function seedTemplate(): AppreciationTemplate
+    {
+        $template = AppreciationTemplate::creer(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Template original',
+            content: 'Contenu original',
+            category: AppreciationCategory::POSITIVE,
+            now: $this->clock->now(),
+        );
+
+        $this->templateRepository->save($template);
+
+        return $template;
+    }
+}