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/Domain/Model/Competency/CompetencyEvaluationTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyEvaluationTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Scolarite\Domain\Model\Competency\CompetencyEvaluation;
+use App\Scolarite\Domain\Model\Competency\CompetencyEvaluationId;
+use App\Scolarite\Domain\Model\Competency\CompetencyId;
+use App\Scolarite\Domain\Model\Evaluation\EvaluationId;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CompetencyEvaluationTest extends TestCase
+{
+    #[Test]
+    public function creerSetsAllProperties(): void
+    {
+        $evaluationId = EvaluationId::generate();
+        $competencyId = CompetencyId::generate();
+
+        $ce = CompetencyEvaluation::creer(
+            evaluationId: $evaluationId,
+            competencyId: $competencyId,
+        );
+
+        self::assertTrue($ce->evaluationId->equals($evaluationId));
+        self::assertTrue($ce->competencyId->equals($competencyId));
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = CompetencyEvaluationId::generate();
+        $evaluationId = EvaluationId::generate();
+        $competencyId = CompetencyId::generate();
+
+        $ce = CompetencyEvaluation::reconstitute(
+            id: $id,
+            evaluationId: $evaluationId,
+            competencyId: $competencyId,
+        );
+
+        self::assertTrue($ce->id->equals($id));
+        self::assertTrue($ce->evaluationId->equals($evaluationId));
+        self::assertTrue($ce->competencyId->equals($competencyId));
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyFrameworkTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyFrameworkTest.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Scolarite\Domain\Model\Competency\CompetencyFramework;
+use App\Scolarite\Domain\Model\Competency\CompetencyFrameworkId;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CompetencyFrameworkTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+
+    #[Test]
+    public function creerSetsAllProperties(): void
+    {
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+        $now = new DateTimeImmutable('2026-04-01 10:00:00');
+
+        $framework = CompetencyFramework::creer(
+            tenantId: $tenantId,
+            name: 'Socle commun',
+            isDefault: true,
+            now: $now,
+        );
+
+        self::assertTrue($framework->tenantId->equals($tenantId));
+        self::assertSame('Socle commun', $framework->name);
+        self::assertTrue($framework->isDefault);
+        self::assertEquals($now, $framework->createdAt);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = CompetencyFrameworkId::generate();
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+        $createdAt = new DateTimeImmutable('2026-04-01 10:00:00');
+
+        $framework = CompetencyFramework::reconstitute(
+            id: $id,
+            tenantId: $tenantId,
+            name: 'Référentiel personnalisé',
+            isDefault: false,
+            createdAt: $createdAt,
+        );
+
+        self::assertTrue($framework->id->equals($id));
+        self::assertTrue($framework->tenantId->equals($tenantId));
+        self::assertSame('Référentiel personnalisé', $framework->name);
+        self::assertFalse($framework->isDefault);
+        self::assertEquals($createdAt, $framework->createdAt);
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyLevelTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyLevelTest.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Scolarite\Domain\Model\Competency\CompetencyLevel;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CompetencyLevelTest extends TestCase
+{
+    #[Test]
+    public function hasFourLevels(): void
+    {
+        self::assertCount(4, CompetencyLevel::cases());
+    }
+
+    #[Test]
+    public function levelsHaveCorrectValues(): void
+    {
+        self::assertSame('not_acquired', CompetencyLevel::NOT_ACQUIRED->value);
+        self::assertSame('in_progress', CompetencyLevel::IN_PROGRESS->value);
+        self::assertSame('acquired', CompetencyLevel::ACQUIRED->value);
+        self::assertSame('exceeded', CompetencyLevel::EXCEEDED->value);
+    }
+
+    #[Test]
+    public function labelsAreInFrench(): void
+    {
+        self::assertSame('Non acquis', CompetencyLevel::NOT_ACQUIRED->label());
+        self::assertSame('En cours d\'acquisition', CompetencyLevel::IN_PROGRESS->label());
+        self::assertSame('Acquis', CompetencyLevel::ACQUIRED->label());
+        self::assertSame('Dépassé', CompetencyLevel::EXCEEDED->label());
+    }
+
+    #[Test]
+    public function sortOrderIsAscending(): void
+    {
+        self::assertSame(1, CompetencyLevel::NOT_ACQUIRED->sortOrder());
+        self::assertSame(2, CompetencyLevel::IN_PROGRESS->sortOrder());
+        self::assertSame(3, CompetencyLevel::ACQUIRED->sortOrder());
+        self::assertSame(4, CompetencyLevel::EXCEEDED->sortOrder());
+    }
+
+    #[Test]
+    public function colorsAreValid(): void
+    {
+        foreach (CompetencyLevel::cases() as $level) {
+            self::assertMatchesRegularExpression('/^#[0-9a-f]{6}$/', $level->color());
+        }
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/CompetencyTest.php
@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Scolarite\Domain\Model\Competency\Competency;
+use App\Scolarite\Domain\Model\Competency\CompetencyFrameworkId;
+use App\Scolarite\Domain\Model\Competency\CompetencyId;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CompetencyTest extends TestCase
+{
+    #[Test]
+    public function creerSetsAllProperties(): void
+    {
+        $frameworkId = CompetencyFrameworkId::generate();
+
+        $competency = Competency::creer(
+            frameworkId: $frameworkId,
+            code: 'D1.1',
+            name: 'Comprendre, s\'exprimer en utilisant la langue française',
+            description: 'Domaine 1 - Langages',
+            parentId: null,
+            sortOrder: 1,
+        );
+
+        self::assertTrue($competency->frameworkId->equals($frameworkId));
+        self::assertSame('D1.1', $competency->code);
+        self::assertSame('Comprendre, s\'exprimer en utilisant la langue française', $competency->name);
+        self::assertSame('Domaine 1 - Langages', $competency->description);
+        self::assertNull($competency->parentId);
+        self::assertSame(1, $competency->sortOrder);
+    }
+
+    #[Test]
+    public function creerWithParentId(): void
+    {
+        $frameworkId = CompetencyFrameworkId::generate();
+        $parentId = CompetencyId::generate();
+
+        $competency = Competency::creer(
+            frameworkId: $frameworkId,
+            code: 'D1.1.1',
+            name: 'Lire',
+            description: null,
+            parentId: $parentId,
+            sortOrder: 1,
+        );
+
+        self::assertNotNull($competency->parentId);
+        self::assertTrue($competency->parentId->equals($parentId));
+        self::assertNull($competency->description);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = CompetencyId::generate();
+        $frameworkId = CompetencyFrameworkId::generate();
+        $parentId = CompetencyId::generate();
+
+        $competency = Competency::reconstitute(
+            id: $id,
+            frameworkId: $frameworkId,
+            code: 'D2',
+            name: 'Méthodes et outils pour apprendre',
+            description: 'Domaine 2',
+            parentId: $parentId,
+            sortOrder: 2,
+        );
+
+        self::assertTrue($competency->id->equals($id));
+        self::assertTrue($competency->frameworkId->equals($frameworkId));
+        self::assertSame('D2', $competency->code);
+        self::assertSame('Méthodes et outils pour apprendre', $competency->name);
+        self::assertSame('Domaine 2', $competency->description);
+        self::assertNotNull($competency->parentId);
+        self::assertTrue($competency->parentId->equals($parentId));
+        self::assertSame(2, $competency->sortOrder);
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Competency/CustomCompetencyLevelTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/CustomCompetencyLevelTest.php
@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Scolarite\Domain\Model\Competency\CustomCompetencyLevel;
+use App\Scolarite\Domain\Model\Competency\CustomCompetencyLevelId;
+use App\Shared\Domain\Tenant\TenantId;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class CustomCompetencyLevelTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+
+    #[Test]
+    public function creerSetsAllProperties(): void
+    {
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+
+        $level = CustomCompetencyLevel::creer(
+            tenantId: $tenantId,
+            code: 'excellent',
+            name: 'Excellent',
+            color: '#9b59b6',
+            sortOrder: 5,
+        );
+
+        self::assertTrue($level->tenantId->equals($tenantId));
+        self::assertSame('excellent', $level->code);
+        self::assertSame('Excellent', $level->name);
+        self::assertSame('#9b59b6', $level->color);
+        self::assertSame(5, $level->sortOrder);
+    }
+
+    #[Test]
+    public function creerAllowsNullColor(): void
+    {
+        $level = CustomCompetencyLevel::creer(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            code: 'basic',
+            name: 'Basique',
+            color: null,
+            sortOrder: 1,
+        );
+
+        self::assertNull($level->color);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = CustomCompetencyLevelId::generate();
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+
+        $level = CustomCompetencyLevel::reconstitute(
+            id: $id,
+            tenantId: $tenantId,
+            code: 'progressing',
+            name: 'En progression',
+            color: '#f1c40f',
+            sortOrder: 2,
+        );
+
+        self::assertTrue($level->id->equals($id));
+        self::assertTrue($level->tenantId->equals($tenantId));
+        self::assertSame('progressing', $level->code);
+        self::assertSame('En progression', $level->name);
+        self::assertSame('#f1c40f', $level->color);
+        self::assertSame(2, $level->sortOrder);
+    }
+}
--- a/backend/tests/Unit/Scolarite/Domain/Model/Competency/StudentCompetencyResultTest.php
+++ b/backend/tests/Unit/Scolarite/Domain/Model/Competency/StudentCompetencyResultTest.php
@@ -0,0 +1,140 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Scolarite\Domain\Model\Competency;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Domain\Event\ResultatCompetenceModifie;
+use App\Scolarite\Domain\Event\ResultatCompetenceSaisi;
+use App\Scolarite\Domain\Model\Competency\CompetencyEvaluationId;
+use App\Scolarite\Domain\Model\Competency\CompetencyLevel;
+use App\Scolarite\Domain\Model\Competency\StudentCompetencyResult;
+use App\Scolarite\Domain\Model\Competency\StudentCompetencyResultId;
+use App\Shared\Domain\Tenant\TenantId;
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class StudentCompetencyResultTest extends TestCase
+{
+    private const string TENANT_ID = '550e8400-e29b-41d4-a716-446655440001';
+    private const string STUDENT_ID = '550e8400-e29b-41d4-a716-446655440050';
+
+    #[Test]
+    public function saisirCreatesResultWithCorrectProperties(): void
+    {
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+        $ceId = CompetencyEvaluationId::generate();
+        $studentId = UserId::fromString(self::STUDENT_ID);
+        $now = new DateTimeImmutable('2026-04-01 10:00:00');
+
+        $result = StudentCompetencyResult::saisir(
+            tenantId: $tenantId,
+            competencyEvaluationId: $ceId,
+            studentId: $studentId,
+            levelCode: CompetencyLevel::ACQUIRED->value,
+            now: $now,
+        );
+
+        self::assertTrue($result->tenantId->equals($tenantId));
+        self::assertTrue($result->competencyEvaluationId->equals($ceId));
+        self::assertTrue($result->studentId->equals($studentId));
+        self::assertSame('acquired', $result->levelCode);
+        self::assertEquals($now, $result->createdAt);
+        self::assertEquals($now, $result->updatedAt);
+    }
+
+    #[Test]
+    public function saisirRecordsEvent(): void
+    {
+        $result = $this->createResult();
+
+        $events = $result->pullDomainEvents();
+
+        self::assertCount(1, $events);
+        self::assertInstanceOf(ResultatCompetenceSaisi::class, $events[0]);
+        self::assertSame($result->id, $events[0]->resultId);
+        self::assertSame('acquired', $events[0]->levelCode);
+    }
+
+    #[Test]
+    public function modifierDoesNothingWhenLevelUnchanged(): void
+    {
+        $result = $this->createResult();
+        $result->pullDomainEvents();
+        $createdAt = $result->updatedAt;
+
+        $result->modifier(
+            levelCode: CompetencyLevel::ACQUIRED->value,
+            now: new DateTimeImmutable('2026-04-02 14:00:00'),
+        );
+
+        self::assertSame('acquired', $result->levelCode);
+        self::assertEquals($createdAt, $result->updatedAt);
+        self::assertEmpty($result->pullDomainEvents());
+    }
+
+    #[Test]
+    public function modifierUpdatesLevelAndRecordsEvent(): void
+    {
+        $result = $this->createResult();
+        $result->pullDomainEvents();
+        $modifiedAt = new DateTimeImmutable('2026-04-02 14:00:00');
+
+        $result->modifier(
+            levelCode: CompetencyLevel::EXCEEDED->value,
+            now: $modifiedAt,
+        );
+
+        self::assertSame('exceeded', $result->levelCode);
+        self::assertEquals($modifiedAt, $result->updatedAt);
+
+        $events = $result->pullDomainEvents();
+        self::assertCount(1, $events);
+        self::assertInstanceOf(ResultatCompetenceModifie::class, $events[0]);
+        self::assertSame('acquired', $events[0]->oldLevelCode);
+        self::assertSame('exceeded', $events[0]->newLevelCode);
+    }
+
+    #[Test]
+    public function reconstituteRestoresAllProperties(): void
+    {
+        $id = StudentCompetencyResultId::generate();
+        $tenantId = TenantId::fromString(self::TENANT_ID);
+        $ceId = CompetencyEvaluationId::generate();
+        $studentId = UserId::fromString(self::STUDENT_ID);
+        $createdAt = new DateTimeImmutable('2026-04-01 10:00:00');
+        $updatedAt = new DateTimeImmutable('2026-04-02 14:00:00');
+
+        $result = StudentCompetencyResult::reconstitute(
+            id: $id,
+            tenantId: $tenantId,
+            competencyEvaluationId: $ceId,
+            studentId: $studentId,
+            levelCode: CompetencyLevel::IN_PROGRESS->value,
+            createdAt: $createdAt,
+            updatedAt: $updatedAt,
+        );
+
+        self::assertTrue($result->id->equals($id));
+        self::assertTrue($result->tenantId->equals($tenantId));
+        self::assertTrue($result->competencyEvaluationId->equals($ceId));
+        self::assertTrue($result->studentId->equals($studentId));
+        self::assertSame('in_progress', $result->levelCode);
+        self::assertEquals($createdAt, $result->createdAt);
+        self::assertEquals($updatedAt, $result->updatedAt);
+        self::assertEmpty($result->pullDomainEvents());
+    }
+
+    private function createResult(): StudentCompetencyResult
+    {
+        return StudentCompetencyResult::saisir(
+            tenantId: TenantId::fromString(self::TENANT_ID),
+            competencyEvaluationId: CompetencyEvaluationId::generate(),
+            studentId: UserId::fromString(self::STUDENT_ID),
+            levelCode: CompetencyLevel::ACQUIRED->value,
+            now: new DateTimeImmutable('2026-04-01 10:00:00'),
+        );
+    }
+}