feat(mail) : MailMessageDetailController - GET /api/mail/messages/{id} (live IMAP + cache 5 min)

- recupere headers + body + attachments via ImapMailProvider::fetchMessage
- cache Symfony pool cache.app, cle mail_body_{md5(messageId)}, TTL 300s
- attachments serialises sans contenu binaire, avec downloadId base64url(messageDbId:partNumber)
- 503 si IMAP indisponible, 404 si message inconnu
- les tests read/flag ROLE_CLIENT/auth seront ajoutes en Task 10 (route deja existante)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/Controller/Mail/MailMessageDetailController.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controller\Mail;
+
+use App\Mail\Exception\MailProviderException;
+use App\Mail\MailProviderInterface;
+use App\Repository\MailMessageRepository;
+use App\Security\MailAccessChecker;
+use DateTimeInterface;
+use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+#[Route('/api/mail/messages/{id}', name: 'mail_message_detail', methods: ['GET'], priority: 1, requirements: ['id' => '\d+'])]
+#[IsGranted('IS_AUTHENTICATED_FULLY')]
+class MailMessageDetailController extends AbstractController
+{
+    public function __construct(
+        private readonly MailMessageRepository $messageRepository,
+        private readonly MailProviderInterface $mailProvider,
+        private readonly MailAccessChecker $accessChecker,
+        private readonly CacheItemPoolInterface $cache,
+    ) {}
+
+    public function __invoke(int $id): JsonResponse
+    {
+        $this->accessChecker->ensureCanAccessMail($this->getUser());
+
+        $message = $this->messageRepository->find($id);
+        if (null === $message) {
+            throw new NotFoundHttpException('Message not found');
+        }
+
+        $cacheKey = 'mail_body_'.md5($message->getMessageId());
+        $item     = $this->cache->getItem($cacheKey);
+
+        if (!$item->isHit()) {
+            try {
+                $detail = $this->mailProvider->fetchMessage(
+                    $message->getFolder()->getPath(),
+                    $message->getUid()
+                );
+                $item->set($detail);
+                $item->expiresAfter(300);
+                $this->cache->save($item);
+            } catch (MailProviderException) {
+                throw new ServiceUnavailableHttpException(null, 'IMAP unavailable: could not fetch message body');
+            }
+        }
+
+        $detail = $item->get();
+
+        $messageId   = $message->getId();
+        $attachments = array_map(static fn ($att) => [
+            'partNumber' => $att->partNumber,
+            'filename'   => $att->filename,
+            'mimeType'   => $att->mimeType,
+            'size'       => $att->size,
+            'downloadId' => rtrim(strtr(base64_encode($messageId.':'.$att->partNumber), '+/', '-_'), '='),
+        ], $detail->attachments);
+
+        return $this->json([
+            'id'             => $message->getId(),
+            'messageId'      => $message->getMessageId(),
+            'uid'            => $message->getUid(),
+            'folderPath'     => $message->getFolder()->getPath(),
+            'subject'        => $detail->header->subject,
+            'fromAddress'    => $detail->header->fromAddress,
+            'fromName'       => $detail->header->fromName,
+            'toAddresses'    => $detail->header->toAddresses,
+            'ccAddresses'    => $detail->header->ccAddresses,
+            'sentAt'         => $detail->header->sentAt->format(DateTimeInterface::ATOM),
+            'isRead'         => $message->isRead(),
+            'isFlagged'      => $message->isFlagged(),
+            'hasAttachments' => $message->hasAttachments(),
+            'bodyHtml'       => $detail->bodyHtml,
+            'bodyText'       => $detail->bodyText,
+            'attachments'    => $attachments,
+        ]);
+    }
+}

tests/Functional/Controller/Mail/MailMessagesControllerTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Functional\Controller\Mail;
+
+use App\Entity\User;
+use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+/**
+ * @internal
+ */
+class MailMessagesControllerTest extends WebTestCase
+{
+    public function testGetMessageDetailReturns401WhenNotAuthenticated(): void
+    {
+        $client = static::createClient();
+        $client->request('GET', '/api/mail/messages/999');
+
+        self::assertResponseStatusCodeSame(401);
+    }
+
+    public function testGetMessageDetailReturns403ForRoleClient(): void
+    {
+        $client    = static::createClient();
+        $container = static::getContainer();
+        $em        = $container->get('doctrine.orm.entity_manager');
+
+        $clientUser = $em->getRepository(User::class)->findOneBy(['username' => 'client-liot']);
+        $client->loginUser($clientUser);
+        $client->request('GET', '/api/mail/messages/999');
+
+        self::assertResponseStatusCodeSame(403);
+    }
+
+    public function testGetMessageDetailReturns404WhenMessageNotFound(): void
+    {
+        $client    = static::createClient();
+        $container = static::getContainer();
+        $em        = $container->get('doctrine.orm.entity_manager');
+
+        $user = $em->getRepository(User::class)->findOneBy(['username' => 'alice']);
+        $client->loginUser($user);
+        $client->request('GET', '/api/mail/messages/99999');
+
+        self::assertResponseStatusCodeSame(404);
+    }
+}