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 e745cf326a
733 changed files with 113156 additions and 286 deletions
--- a/backend/tests/Unit/Scolarite/Domain/Model/Grade/AppreciationTemplateTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Grade/AppreciationTemplateTest.php
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Grade;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Domain\Model\Grade\AppreciationCategory;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplate;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplateId;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class AppreciationTemplateTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string TEACHER_ID = '550e8400-e29b-41d4-a716-446655440010';
+
+    #[Test]
+    public function creerSetsAllProperties(): void
+    {
+        $now = new DateTimeImmutable('2026-03-31 10:00:00');
+
+        $template = AppreciationTemplate::creer(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Très bon travail',
+            content: 'Très bon travail, continuez ainsi !',
+            category: AppreciationCategory::POSITIVE,
+            now: $now,
+        );
+
+        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);
+        self::assertEquals($now, $template->createdAt);
+        self::assertEquals($now, $template->updatedAt);
+    }
+
+    #[Test]
+    public function creerAcceptsNullCategory(): void
+    {
+        $template = $this->createTemplate(category: null);
+
+        self::assertNull($template->category);
+    }
+
+    #[Test]
+    public function modifierUpdatesProperties(): void
+    {
+        $template = $this->createTemplate();
+        $modifiedAt = new DateTimeImmutable('2026-03-31 14:00:00');
+
+        $template->modifier(
+            title: 'Nouveau titre',
+            content: 'Nouveau contenu',
+            category: AppreciationCategory::IMPROVEMENT,
+            now: $modifiedAt,
+        );
+
+        self::assertSame('Nouveau titre', $template->title);
+        self::assertSame('Nouveau contenu', $template->content);
+        self::assertSame(AppreciationCategory::IMPROVEMENT, $template->category);
+        self::assertEquals($modifiedAt, $template->updatedAt);
+    }
+
+    #[Test]
+    public function incrementerUtilisationIncreasesCount(): void
+    {
+        $template = $this->createTemplate();
+
+        $template->incrementerUtilisation();
+        self::assertSame(1, $template->usageCount);
+
+        $template->incrementerUtilisation();
+        self::assertSame(2, $template->usageCount);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = AppreciationTemplateId::generate();
+        $createdAt = new DateTimeImmutable('2026-03-31 10:00:00');
+        $updatedAt = new DateTimeImmutable('2026-03-31 14:00:00');
+
+        $template = AppreciationTemplate::reconstitute(
+            id: $id,
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Titre',
+            content: 'Contenu',
+            category: AppreciationCategory::NEUTRAL,
+            usageCount: 5,
+            createdAt: $createdAt,
+            updatedAt: $updatedAt,
+        );
+
+        self::assertTrue($template->id->equals($id));
+        self::assertSame('Titre', $template->title);
+        self::assertSame('Contenu', $template->content);
+        self::assertSame(AppreciationCategory::NEUTRAL, $template->category);
+        self::assertSame(5, $template->usageCount);
+        self::assertEquals($createdAt, $template->createdAt);
+        self::assertEquals($updatedAt, $template->updatedAt);
+    }
+
+    private function createTemplate(?AppreciationCategory $category = AppreciationCategory::POSITIVE): AppreciationTemplate
+    {
+        return AppreciationTemplate::creer(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            teacherId: UserId::fromString(self::TEACHER_ID),
+            title: 'Très bon travail',
+            content: 'Très bon travail, continuez ainsi !',
+            category: $category,
+            now: new DateTimeImmutable('2026-03-31 10:00:00'),
+        );
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Grade/GradeTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Grade/GradeTest.php
@@ -7,6 +7,7 @@ namespace App\Tests\Unit\Scolarite\Domain\Model\Grade;
 use App\Administration\Domain\Model\User\UserId;
 use App\Scolarite\Domain\Event\NoteModifiee;
 use App\Scolarite\Domain\Event\NoteSaisie;
+use App\Scolarite\Domain\Exception\AppreciationTropLongueException;
 use App\Scolarite\Domain\Exception\NoteRequiseException;
 use App\Scolarite\Domain\Exception\ValeurNoteInvalideException;
 use App\Scolarite\Domain\Model\Evaluation\EvaluationId;
@@ -20,6 +21,8 @@ use DateTimeImmutable;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;

+use function str_repeat;
+
 final class GradeTest extends TestCase
 {
    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
@@ -269,6 +272,96 @@ final class GradeTest extends TestCase
        self::assertEmpty($grade->pullDomainEvents());
    }

+    #[Test]
+    public function saisirAppreciationSetsAppreciation(): void
+    {
+        $grade = $this->createGrade();
+        $now = new DateTimeImmutable('2026-03-31 10:00:00');
+
+        $grade->saisirAppreciation('Très bon travail', $now);
+
+        self::assertSame('Très bon travail', $grade->appreciation);
+        self::assertEquals($now, $grade->appreciationUpdatedAt);
+        self::assertEquals($now, $grade->updatedAt);
+    }
+
+    #[Test]
+    public function saisirAppreciationAcceptsNull(): void
+    {
+        $grade = $this->createGrade();
+        $grade->saisirAppreciation('Temporaire', new DateTimeImmutable('2026-03-31 09:00:00'));
+
+        $grade->saisirAppreciation(null, new DateTimeImmutable('2026-03-31 10:00:00'));
+
+        self::assertNull($grade->appreciation);
+    }
+
+    #[Test]
+    public function saisirAppreciationAcceptsEmptyString(): void
+    {
+        $grade = $this->createGrade();
+        $grade->saisirAppreciation('Temporaire', new DateTimeImmutable('2026-03-31 09:00:00'));
+
+        $grade->saisirAppreciation('', new DateTimeImmutable('2026-03-31 10:00:00'));
+
+        self::assertNull($grade->appreciation);
+    }
+
+    #[Test]
+    public function saisirAppreciationThrowsWhenTooLong(): void
+    {
+        $grade = $this->createGrade();
+
+        $this->expectException(AppreciationTropLongueException::class);
+
+        $grade->saisirAppreciation(str_repeat('a', 501), new DateTimeImmutable('2026-03-31 10:00:00'));
+    }
+
+    #[Test]
+    public function saisirAppreciationAcceptsMaxLength(): void
+    {
+        $grade = $this->createGrade();
+
+        $grade->saisirAppreciation(str_repeat('a', 500), new DateTimeImmutable('2026-03-31 10:00:00'));
+
+        self::assertSame(500, mb_strlen($grade->appreciation ?? ''));
+    }
+
+    #[Test]
+    public function newGradeHasNullAppreciation(): void
+    {
+        $grade = $this->createGrade();
+
+        self::assertNull($grade->appreciation);
+        self::assertNull($grade->appreciationUpdatedAt);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAppreciation(): void
+    {
+        $gradeId = GradeId::generate();
+        $createdAt = new DateTimeImmutable('2026-03-27 10:00:00');
+        $updatedAt = new DateTimeImmutable('2026-03-27 14:00:00');
+        $appreciationUpdatedAt = new DateTimeImmutable('2026-03-31 10:00:00');
+
+        $grade = Grade::reconstitute(
+            id: $gradeId,
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            evaluationId: EvaluationId::fromString(self::EVALUATION_ID),
+            studentId: UserId::fromString(self::STUDENT_ID),
+            value: new GradeValue(15.5),
+            status: GradeStatus::GRADED,
+            createdBy: UserId::fromString(self::TEACHER_ID),
+            createdAt: $createdAt,
+            updatedAt: $updatedAt,
+            appreciation: 'Bon travail',
+            appreciationUpdatedAt: $appreciationUpdatedAt,
+        );
+
+        self::assertSame('Bon travail', $grade->appreciation);
+        self::assertEquals($appreciationUpdatedAt, $grade->appreciationUpdatedAt);
+    }
+
    private function createGrade(): Grade
    {
        return Grade::saisir(
--- a/backend/tests/Unit/Scolarite/Domain/Service/AverageCalculatorTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Service/AverageCalculatorTest.php
@@ -0,0 +1,233 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Service;
+
+use App\Scolarite\Domain\Model\Evaluation\Coefficient;
+use App\Scolarite\Domain\Model\Evaluation\GradeScale;
+use App\Scolarite\Domain\Service\AverageCalculator;
+use App\Scolarite\Domain\Service\GradeEntry;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class AverageCalculatorTest extends TestCase
+{
+    private AverageCalculator $calculator;
+
+    protected function setUp(): void
+    {
+        $this->calculator = new AverageCalculator();
+    }
+
+    // --- Subject Average ---
+
+    #[Test]
+    public function subjectAverageReturnsNullWhenNoGrades(): void
+    {
+        self::assertNull($this->calculator->calculateSubjectAverage([]));
+    }
+
+    #[Test]
+    public function subjectAverageWithSingleGrade(): void
+    {
+        $grades = [
+            new GradeEntry(
+                value: 15.0,
+                gradeScale: new GradeScale(20),
+                coefficient: new Coefficient(1.0),
+            ),
+        ];
+
+        self::assertSame(15.0, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageWithEqualCoefficients(): void
+    {
+        $grades = [
+            new GradeEntry(value: 12.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+            new GradeEntry(value: 16.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+            new GradeEntry(value: 8.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+        ];
+
+        // (12 + 16 + 8) / 3 = 12.0
+        self::assertSame(12.0, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageWithDifferentCoefficients(): void
+    {
+        $grades = [
+            new GradeEntry(value: 14.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(2.0)),
+            new GradeEntry(value: 8.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+        ];
+
+        // (14×2 + 8×1) / (2+1) = 36/3 = 12.0
+        self::assertSame(12.0, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageNormalizesToScale20(): void
+    {
+        $grades = [
+            new GradeEntry(value: 8.0, gradeScale: new GradeScale(10), coefficient: new Coefficient(1.0)),
+        ];
+
+        // 8/10 × 20 = 16.0
+        self::assertSame(16.0, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageWithMixedScales(): void
+    {
+        $grades = [
+            new GradeEntry(value: 15.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+            new GradeEntry(value: 40.0, gradeScale: new GradeScale(100), coefficient: new Coefficient(1.0)),
+        ];
+
+        // 15/20×20=15 et 40/100×20=8 → (15+8)/2 = 11.5
+        self::assertSame(11.5, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageWithMixedScalesAndCoefficients(): void
+    {
+        $grades = [
+            new GradeEntry(value: 16.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(3.0)),
+            new GradeEntry(value: 7.0, gradeScale: new GradeScale(10), coefficient: new Coefficient(2.0)),
+        ];
+
+        // 16/20×20=16 (coef 3), 7/10×20=14 (coef 2)
+        // (16×3 + 14×2) / (3+2) = (48+28)/5 = 76/5 = 15.2
+        self::assertSame(15.2, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    #[Test]
+    public function subjectAverageRoundsToTwoDecimals(): void
+    {
+        $grades = [
+            new GradeEntry(value: 13.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+            new GradeEntry(value: 7.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+            new GradeEntry(value: 11.0, gradeScale: new GradeScale(20), coefficient: new Coefficient(1.0)),
+        ];
+
+        // (13+7+11)/3 = 31/3 = 10.333... → 10.33
+        self::assertSame(10.33, $this->calculator->calculateSubjectAverage($grades));
+    }
+
+    // --- General Average ---
+
+    #[Test]
+    public function generalAverageReturnsNullWhenNoSubjects(): void
+    {
+        self::assertNull($this->calculator->calculateGeneralAverage([]));
+    }
+
+    #[Test]
+    public function generalAverageWithSingleSubject(): void
+    {
+        self::assertSame(14.5, $this->calculator->calculateGeneralAverage([14.5]));
+    }
+
+    #[Test]
+    public function generalAverageIsArithmeticMean(): void
+    {
+        // (12.0 + 15.0 + 9.0) / 3 = 12.0
+        self::assertSame(12.0, $this->calculator->calculateGeneralAverage([12.0, 15.0, 9.0]));
+    }
+
+    #[Test]
+    public function generalAverageRoundsToTwoDecimals(): void
+    {
+        // (14.0 + 13.0 + 11.0) / 3 = 38/3 = 12.666... → 12.67
+        self::assertSame(12.67, $this->calculator->calculateGeneralAverage([14.0, 13.0, 11.0]));
+    }
+
+    // --- Class Statistics ---
+
+    #[Test]
+    public function classStatisticsReturnsEmptyWhenNoGrades(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([]);
+
+        self::assertNull($stats->average);
+        self::assertNull($stats->min);
+        self::assertNull($stats->max);
+        self::assertNull($stats->median);
+        self::assertSame(0, $stats->gradedCount);
+    }
+
+    #[Test]
+    public function classStatisticsWithSingleGrade(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([15.0]);
+
+        self::assertSame(15.0, $stats->average);
+        self::assertSame(15.0, $stats->min);
+        self::assertSame(15.0, $stats->max);
+        self::assertSame(15.0, $stats->median);
+        self::assertSame(1, $stats->gradedCount);
+    }
+
+    #[Test]
+    public function classStatisticsWithOddNumberOfGrades(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([8.0, 15.0, 12.0]);
+
+        // Sorted: 8, 12, 15
+        self::assertSame(11.67, $stats->average); // 35/3
+        self::assertSame(8.0, $stats->min);
+        self::assertSame(15.0, $stats->max);
+        self::assertSame(12.0, $stats->median); // middle element
+        self::assertSame(3, $stats->gradedCount);
+    }
+
+    #[Test]
+    public function classStatisticsWithEvenNumberOfGrades(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([7.0, 12.0, 14.0, 18.0]);
+
+        // Sorted: 7, 12, 14, 18
+        self::assertSame(12.75, $stats->average); // 51/4
+        self::assertSame(7.0, $stats->min);
+        self::assertSame(18.0, $stats->max);
+        self::assertSame(13.0, $stats->median); // (12+14)/2
+        self::assertSame(4, $stats->gradedCount);
+    }
+
+    #[Test]
+    public function classStatisticsSortsInputValues(): void
+    {
+        // Input not sorted
+        $stats = $this->calculator->calculateClassStatistics([18.0, 7.0, 14.0, 12.0]);
+
+        self::assertSame(7.0, $stats->min);
+        self::assertSame(18.0, $stats->max);
+        self::assertSame(13.0, $stats->median); // (12+14)/2
+    }
+
+    #[Test]
+    public function classStatisticsWithIdenticalGrades(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([10.0, 10.0, 10.0]);
+
+        self::assertSame(10.0, $stats->average);
+        self::assertSame(10.0, $stats->min);
+        self::assertSame(10.0, $stats->max);
+        self::assertSame(10.0, $stats->median);
+        self::assertSame(3, $stats->gradedCount);
+    }
+
+    #[Test]
+    public function classStatisticsWithTwoGrades(): void
+    {
+        $stats = $this->calculator->calculateClassStatistics([6.0, 16.0]);
+
+        self::assertSame(11.0, $stats->average);
+        self::assertSame(6.0, $stats->min);
+        self::assertSame(16.0, $stats->max);
+        self::assertSame(11.0, $stats->median); // (6+16)/2
+        self::assertSame(2, $stats->gradedCount);
+    }
+}