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.

backend/src/Scolarite/Application/Command/CreateAppreciationTemplate/CreateAppreciationTemplateCommand.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\CreateAppreciationTemplate;
+
+final readonly class CreateAppreciationTemplateCommand
+{
+    public function __construct(
+        public string $tenantId,
+        public string $teacherId,
+        public string $title,
+        public string $content,
+        public ?string $category,
+    ) {
+    }
+}

backend/src/Scolarite/Application/Command/CreateAppreciationTemplate/CreateAppreciationTemplateHandler.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\CreateAppreciationTemplate;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Domain\Exception\CategorieAppreciationInvalideException;
+use App\Scolarite\Domain\Model\Grade\AppreciationCategory;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplate;
+use App\Scolarite\Domain\Repository\AppreciationTemplateRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+#[AsMessageHandler(bus: 'command.bus')]
+final readonly class CreateAppreciationTemplateHandler
+{
+    public function __construct(
+        private AppreciationTemplateRepository $templateRepository,
+        private Clock $clock,
+    ) {
+    }
+
+    public function __invoke(CreateAppreciationTemplateCommand $command): AppreciationTemplate
+    {
+        $category = null;
+        if ($command->category !== null) {
+            $category = AppreciationCategory::tryFrom($command->category);
+            if ($category === null) {
+                throw CategorieAppreciationInvalideException::pourValeur($command->category);
+            }
+        }
+
+        $template = AppreciationTemplate::creer(
+            tenantId: TenantId::fromString($command->tenantId),
+            teacherId: UserId::fromString($command->teacherId),
+            title: $command->title,
+            content: $command->content,
+            category: $category,
+            now: $this->clock->now(),
+        );
+
+        $this->templateRepository->save($template);
+
+        return $template;
+    }
+}

backend/src/Scolarite/Application/Command/DeleteAppreciationTemplate/DeleteAppreciationTemplateCommand.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\DeleteAppreciationTemplate;
+
+final readonly class DeleteAppreciationTemplateCommand
+{
+    public function __construct(
+        public string $tenantId,
+        public string $teacherId,
+        public string $templateId,
+    ) {
+    }
+}

backend/src/Scolarite/Application/Command/DeleteAppreciationTemplate/DeleteAppreciationTemplateHandler.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\DeleteAppreciationTemplate;
+
+use App\Scolarite\Domain\Exception\AppreciationTemplateNonTrouveeException;
+use App\Scolarite\Domain\Exception\NonProprietaireDuModeleException;
+use App\Scolarite\Domain\Model\Grade\AppreciationTemplateId;
+use App\Scolarite\Domain\Repository\AppreciationTemplateRepository;
+use App\Shared\Domain\Tenant\TenantId;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+#[AsMessageHandler(bus: 'command.bus')]
+final readonly class DeleteAppreciationTemplateHandler
+{
+    public function __construct(
+        private AppreciationTemplateRepository $templateRepository,
+    ) {
+    }
+
+    public function __invoke(DeleteAppreciationTemplateCommand $command): void
+    {
+        $tenantId = TenantId::fromString($command->tenantId);
+        $templateId = AppreciationTemplateId::fromString($command->templateId);
+
+        $template = $this->templateRepository->findById($templateId, $tenantId);
+
+        if ($template === null) {
+            throw AppreciationTemplateNonTrouveeException::withId($templateId);
+        }
+
+        if ((string) $template->teacherId !== $command->teacherId) {
+            throw NonProprietaireDuModeleException::withId($templateId);
+        }
+
+        $this->templateRepository->delete($templateId, $tenantId);
+    }
+}

backend/src/Scolarite/Application/Command/SaveAppreciation/SaveAppreciationCommand.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\SaveAppreciation;
+
+final readonly class SaveAppreciationCommand
+{
+    public function __construct(
+        public string $tenantId,
+        public string $gradeId,
+        public string $teacherId,
+        public ?string $appreciation,
+    ) {
+    }
+}

backend/src/Scolarite/Application/Command/SaveAppreciation/SaveAppreciationHandler.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\SaveAppreciation;
+
+use App\Administration\Domain\Model\User\UserId;
+use App\Scolarite\Domain\Exception\NonProprietaireDeLEvaluationException;
+use App\Scolarite\Domain\Model\Grade\Grade;
+use App\Scolarite\Domain\Model\Grade\GradeId;
+use App\Scolarite\Domain\Repository\EvaluationRepository;
+use App\Scolarite\Domain\Repository\GradeRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+#[AsMessageHandler(bus: 'command.bus')]
+final readonly class SaveAppreciationHandler
+{
+    public function __construct(
+        private EvaluationRepository $evaluationRepository,
+        private GradeRepository $gradeRepository,
+        private Clock $clock,
+    ) {
+    }
+
+    public function __invoke(SaveAppreciationCommand $command): Grade
+    {
+        $tenantId = TenantId::fromString($command->tenantId);
+        $gradeId = GradeId::fromString($command->gradeId);
+        $teacherId = UserId::fromString($command->teacherId);
+
+        $grade = $this->gradeRepository->get($gradeId, $tenantId);
+
+        $evaluation = $this->evaluationRepository->get($grade->evaluationId, $tenantId);
+
+        if ((string) $evaluation->teacherId !== (string) $teacherId) {
+            throw NonProprietaireDeLEvaluationException::withId($grade->evaluationId);
+        }
+
+        $grade->saisirAppreciation($command->appreciation, $this->clock->now());
+        $this->gradeRepository->saveAppreciation($grade);
+
+        return $grade;
+    }
+}

backend/src/Scolarite/Application/Command/UpdateAppreciationTemplate/UpdateAppreciationTemplateCommand.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\UpdateAppreciationTemplate;
+
+final readonly class UpdateAppreciationTemplateCommand
+{
+    public function __construct(
+        public string $tenantId,
+        public string $teacherId,
+        public string $templateId,
+        public string $title,
+        public string $content,
+        public ?string $category,
+    ) {
+    }
+}

backend/src/Scolarite/Application/Command/UpdateAppreciationTemplate/UpdateAppreciationTemplateHandler.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Scolarite\Application\Command\UpdateAppreciationTemplate;
+
+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\Domain\Model\Grade\AppreciationTemplateId;
+use App\Scolarite\Domain\Repository\AppreciationTemplateRepository;
+use App\Shared\Domain\Clock;
+use App\Shared\Domain\Tenant\TenantId;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+#[AsMessageHandler(bus: 'command.bus')]
+final readonly class UpdateAppreciationTemplateHandler
+{
+    public function __construct(
+        private AppreciationTemplateRepository $templateRepository,
+        private Clock $clock,
+    ) {
+    }
+
+    public function __invoke(UpdateAppreciationTemplateCommand $command): AppreciationTemplate
+    {
+        $tenantId = TenantId::fromString($command->tenantId);
+        $templateId = AppreciationTemplateId::fromString($command->templateId);
+
+        $template = $this->templateRepository->findById($templateId, $tenantId);
+
+        if ($template === null) {
+            throw AppreciationTemplateNonTrouveeException::withId($templateId);
+        }
+
+        if ((string) $template->teacherId !== $command->teacherId) {
+            throw NonProprietaireDuModeleException::withId($templateId);
+        }
+
+        $category = null;
+        if ($command->category !== null) {
+            $category = AppreciationCategory::tryFrom($command->category);
+            if ($category === null) {
+                throw CategorieAppreciationInvalideException::pourValeur($command->category);
+            }
+        }
+
+        $template->modifier(
+            title: $command->title,
+            content: $command->content,
+            category: $category,
+            now: $this->clock->now(),
+        );
+
+        $this->templateRepository->save($template);
+
+        return $template;
+    }
+}