feat(client-portal) : phase 1 foundations — ROLE_CLIENT hardening + ClientTicket (back)

LST-69 (3.2) phase 1. New ClientPortal module + security foundations for the
client portal (spec docs/superpowers/specs/2026-03-15-client-portal-design.md).

- Security: User::getRoles() no longer adds ROLE_USER to ROLE_CLIENT users;
  role_hierarchy ROLE_ADMIN: [ROLE_USER, ROLE_CLIENT]. Existing Task/Project/
  Client/TimeEntry/metadata endpoints already required ROLE_USER -> a pure
  ROLE_CLIENT is walled off (verified: 403).
- User (Core): client (ManyToOne ClientInterface, SET NULL) + allowedProjects
  (ManyToMany ProjectInterface). UserInterface extended (getClient/
  getAllowedProjects).
- New ClientTicket entity (module ClientPortal) + enums + repository + API with
  per-client isolation (ClientTicketProvider: own tickets ∩ allowedProjects),
  per-project numbering under advisory lock (rejects if user.client null),
  status transition rules. ClientTicketInterface contract for Task/TaskDocument.
- TaskDocument generalized: task nullable + clientTicket (CASCADE) + CHECK;
  per-role access. Task.clientTicket exposed in task:read.
- Additive migration; demo client fixtures.
- Tenancy tests assert the isolation invariant (a client never sees another
  client's tickets) rather than brittle absolute counts (shared test DB).

178 tests green, mapping valid, cs-fixer clean.

src/Module/ProjectManagement/Infrastructure/ApiPlatform/State/TaskDocumentProcessor.php

@@ -14,6 +14,8 @@ use App\Module\Integration\Domain\Service\FileSource;
 use App\Module\Integration\Domain\Service\SharePathResolver;
 use App\Module\ProjectManagement\Domain\Entity\Task;
 use App\Module\ProjectManagement\Domain\Entity\TaskDocument;
+use App\Shared\Domain\Contract\ClientTicketInterface;
+use App\Shared\Domain\Contract\UserInterface;
 use DateTimeImmutable;
 use Doctrine\ORM\EntityManagerInterface;
 use Symfony\Bundle\SecurityBundle\Security;
@@ -75,11 +77,12 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
      */
     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): TaskDocument
     {
-        // Défense en profondeur : l'opération Post est déjà protégée par ROLE_ADMIN, mais on
-        // re-vérifie ici pour que les deux chemins (upload ET lien partage) restent sûrs si la
-        // configuration de sécurité de l'opération venait à changer.
-        if (!$this->security->isGranted('ROLE_ADMIN')) {
-            throw new AccessDeniedHttpException('Creating task documents requires admin privileges.');
+        // Défense en profondeur : l'opération Post est déjà protégée par
+        // ROLE_ADMIN ou ROLE_CLIENT, mais on re-vérifie ici pour que les deux
+        // chemins (upload ET lien partage) restent sûrs si la configuration de
+        // sécurité de l'opération venait à changer.
+        if (!$this->security->isGranted('ROLE_ADMIN') && !$this->security->isGranted('ROLE_CLIENT')) {
+            throw new AccessDeniedHttpException('Creating documents requires admin or client privileges.');
         }
 
         $request = $this->requestStack->getCurrentRequest();
@@ -136,8 +139,6 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
             throw new BadRequestHttpException('File size exceeds 50 MB limit.');
         }
 
-        $task = $this->resolveTask($request->request->get('task', ''));
-
         // Use server-detected MIME type (finfo), not the client-supplied one
         $originalName = $file->getClientOriginalName();
         $mimeType     = $file->getMimeType() ?: 'application/octet-stream';
@@ -157,7 +158,7 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
         $file->move($this->uploadDir, $fileName);
 
         $document = new TaskDocument();
-        $document->setTask($task);
+        $this->attachTarget($document, $request);
         $document->setOriginalName($originalName);
         $document->setFileName($fileName);
         $document->setMimeType($mimeType);
@@ -168,15 +169,6 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
 
     private function createShareLink(Request $request, string $rawSharePath): TaskDocument
     {
-        $taskIri = $request->request->get('task');
-
-        if (!is_string($taskIri) || '' === $taskIri) {
-            $payload = json_decode($request->getContent() ?: '{}', true);
-            $taskIri = is_array($payload) ? ($payload['task'] ?? '') : '';
-        }
-
-        $task = $this->resolveTask((string) $taskIri);
-
         try {
             $path = $this->pathResolver->normalizeRelative($rawSharePath);
         } catch (InvalidPathException) {
@@ -198,7 +190,7 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
         }
 
         $document = new TaskDocument();
-        $document->setTask($task);
+        $this->attachTarget($document, $request);
         $document->setOriginalName($entry->name);
         $document->setSharePath($path);
         $document->setMimeType($entry->mimeType);
@@ -233,12 +225,61 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
         return null;
     }
 
-    private function resolveTask(string $taskIri): Task
+    /**
+     * Attaches the document to a task OR a client ticket, enforcing per-role
+     * access. Exactly one of the two targets must be provided.
+     *
+     * - ROLE_ADMIN may attach to any task or any client ticket.
+     * - ROLE_CLIENT may only attach to a client ticket they submitted, and may
+     *   never attach to a task.
+     */
+    private function attachTarget(TaskDocument $document, Request $request): void
     {
-        if ('' === $taskIri) {
-            throw new BadRequestHttpException('A task IRI is required.');
+        $taskIri         = $this->readField($request, 'task');
+        $clientTicketIri = $this->readField($request, 'clientTicket');
+
+        if ('' === $taskIri && '' === $clientTicketIri) {
+            throw new BadRequestHttpException('A task or a clientTicket IRI is required.');
+        }
+        if ('' !== $taskIri && '' !== $clientTicketIri) {
+            throw new BadRequestHttpException('Provide either a task or a clientTicket, not both.');
         }
 
+        $isClient = $this->security->isGranted('ROLE_CLIENT') && !$this->security->isGranted('ROLE_ADMIN');
+
+        if ('' !== $clientTicketIri) {
+            $document->setClientTicket($this->resolveClientTicket($clientTicketIri, $isClient));
+
+            return;
+        }
+
+        if ($isClient) {
+            throw new AccessDeniedHttpException('Client users can only attach documents to a client ticket.');
+        }
+
+        $document->setTask($this->resolveTask($taskIri));
+    }
+
+    private function readField(Request $request, string $field): string
+    {
+        $value = $request->request->get($field);
+
+        if (is_string($value) && '' !== $value) {
+            return $value;
+        }
+
+        if (str_contains((string) $request->headers->get('Content-Type'), 'application/json')) {
+            $payload = json_decode($request->getContent() ?: '{}', true);
+            if (is_array($payload) && isset($payload[$field]) && is_string($payload[$field])) {
+                return $payload[$field];
+            }
+        }
+
+        return '';
+    }
+
+    private function resolveTask(string $taskIri): Task
+    {
         $task = $this->entityManager->getRepository(Task::class)->find((int) basename($taskIri));
 
         if (null === $task) {
@@ -247,4 +288,24 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
 
         return $task;
     }
+
+    private function resolveClientTicket(string $ticketIri, bool $isClient): ClientTicketInterface
+    {
+        $ticket = $this->entityManager->getRepository(ClientTicketInterface::class)->find((int) basename($ticketIri));
+
+        if (null === $ticket) {
+            throw new BadRequestHttpException('Client ticket not found.');
+        }
+
+        if ($isClient) {
+            $user = $this->security->getUser();
+            assert($user instanceof UserInterface);
+
+            if ($ticket->getSubmittedBy() !== $user) {
+                throw new AccessDeniedHttpException('You can only attach documents to your own tickets.');
+            }
+        }
+
+        return $ticket;
+    }
 }