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/Domain/Entity/Task.php

@@ -19,6 +19,7 @@ use App\Module\ProjectManagement\Infrastructure\ApiPlatform\State\TaskCalendarPr
 use App\Module\ProjectManagement\Infrastructure\ApiPlatform\State\TaskNumberProcessor;
 use App\Module\ProjectManagement\Infrastructure\Doctrine\DoctrineTaskRepository;
 use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\ClientTicketInterface;
 use App\Shared\Domain\Contract\TaskInterface;
 use App\Shared\Domain\Contract\TimestampableInterface;
 use App\Shared\Domain\Contract\UserInterface;
@@ -162,6 +163,16 @@ class Task implements TaskInterface, TimestampableInterface, BlamableInterface
     #[Groups(['task:read', 'task:write'])]
     private ?TaskRecurrence $recurrence = null;
 
+    /**
+     * Optional manual link to a client ticket. Exposed (number/type/status/title)
+     * in task:read so the kanban can show the linked-ticket icon without giving
+     * ROLE_USER access to the /api/client_tickets collection.
+     */
+    #[ORM\ManyToOne(targetEntity: ClientTicketInterface::class)]
+    #[ORM\JoinColumn(name: 'client_ticket_id', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    #[Groups(['task:read', 'task:write'])]
+    private ?ClientTicketInterface $clientTicket = null;
+
     public function __construct()
     {
         $this->tags          = new ArrayCollection();
@@ -440,6 +451,18 @@ class Task implements TaskInterface, TimestampableInterface, BlamableInterface
         return $this;
     }
 
+    public function getClientTicket(): ?ClientTicketInterface
+    {
+        return $this->clientTicket;
+    }
+
+    public function setClientTicket(?ClientTicketInterface $clientTicket): static
+    {
+        $this->clientTicket = $clientTicket;
+
+        return $this;
+    }
+
     #[Assert\Callback]
     public function validateScheduledDates(ExecutionContextInterface $context): void
     {

src/Module/ProjectManagement/Domain/Entity/TaskDocument.php

@@ -14,6 +14,7 @@ use ApiPlatform\Metadata\Post;
 use App\Module\ProjectManagement\Infrastructure\ApiPlatform\State\TaskDocumentProcessor;
 use App\Module\ProjectManagement\Infrastructure\ApiPlatform\State\TaskDocumentProvider;
 use App\Module\ProjectManagement\Infrastructure\EventListener\TaskDocumentListener;
+use App\Shared\Domain\Contract\ClientTicketInterface;
 use App\Shared\Domain\Contract\UserInterface;
 use DateTimeImmutable;
 use Doctrine\ORM\Mapping as ORM;
@@ -21,10 +22,10 @@ use Symfony\Component\Serializer\Attribute\Groups;
 
 #[ApiResource(
     operations: [
-        new GetCollection(paginationEnabled: false, security: "is_granted('ROLE_USER')", provider: TaskDocumentProvider::class),
-        new Get(security: "is_granted('ROLE_USER')", provider: TaskDocumentProvider::class),
+        new GetCollection(paginationEnabled: false, security: "is_granted('ROLE_USER') or is_granted('ROLE_CLIENT')", provider: TaskDocumentProvider::class),
+        new Get(security: "is_granted('ROLE_USER') or is_granted('ROLE_CLIENT')", provider: TaskDocumentProvider::class),
         new Post(
-            security: "is_granted('ROLE_ADMIN')",
+            security: "is_granted('ROLE_ADMIN') or is_granted('ROLE_CLIENT')",
             processor: TaskDocumentProcessor::class,
             deserialize: false,
         ),
@@ -34,9 +35,11 @@ use Symfony\Component\Serializer\Attribute\Groups;
     denormalizationContext: ['groups' => ['task_document:write']],
     order: ['id' => 'DESC'],
 )]
-#[ApiFilter(SearchFilter::class, properties: ['task' => 'exact'])]
+#[ApiFilter(SearchFilter::class, properties: ['task' => 'exact', 'clientTicket' => 'exact'])]
 #[ORM\Entity]
 #[ORM\EntityListeners([TaskDocumentListener::class])]
+// A document must be attached to either a task or a client ticket.
+#[ORM\Table(name: 'task_document')]
 class TaskDocument
 {
     #[ORM\Id]
@@ -46,10 +49,16 @@ class TaskDocument
     private ?int $id = null;
 
     #[ORM\ManyToOne(targetEntity: Task::class, inversedBy: 'documents')]
-    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]
+    #[ORM\JoinColumn(name: 'task_id', referencedColumnName: 'id', nullable: true, onDelete: 'CASCADE')]
     #[Groups(['task_document:read', 'task_document:write'])]
     private ?Task $task = null;
 
+    /** Client ticket this document is attached to (alternative to task). */
+    #[ORM\ManyToOne(targetEntity: ClientTicketInterface::class)]
+    #[ORM\JoinColumn(name: 'client_ticket_id', referencedColumnName: 'id', nullable: true, onDelete: 'CASCADE')]
+    #[Groups(['task_document:read', 'task_document:write', 'client_ticket:read'])]
+    private ?ClientTicketInterface $clientTicket = null;
+
     #[ORM\Column(length: 255)]
     #[Groups(['task_document:read', 'task:read'])]
     private ?string $originalName = null;
@@ -100,6 +109,18 @@ class TaskDocument
         return $this;
     }
 
+    public function getClientTicket(): ?ClientTicketInterface
+    {
+        return $this->clientTicket;
+    }
+
+    public function setClientTicket(?ClientTicketInterface $clientTicket): static
+    {
+        $this->clientTicket = $clientTicket;
+
+        return $this;
+    }
+
     public function getOriginalName(): ?string
     {
         return $this->originalName;

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;
+    }
 }

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

@@ -12,6 +12,12 @@ use Doctrine\ORM\EntityManagerInterface;
 use Symfony\Bundle\SecurityBundle\Security;
 
 /**
+ * Provider for TaskDocument read operations.
+ *
+ * - ROLE_ADMIN: every document.
+ * - ROLE_USER: documents attached to a task (task IS NOT NULL).
+ * - ROLE_CLIENT: documents attached to a client ticket the user submitted.
+ *
  * @implements ProviderInterface<TaskDocument>
  */
 final readonly class TaskDocumentProvider implements ProviderInterface
@@ -26,25 +32,56 @@ final readonly class TaskDocumentProvider implements ProviderInterface
         $user = $this->security->getUser();
         assert($user instanceof UserInterface);
 
+        $isAdmin  = $this->security->isGranted('ROLE_ADMIN');
+        $isClient = $this->security->isGranted('ROLE_CLIENT');
+
         $repo = $this->entityManager->getRepository(TaskDocument::class);
 
-        // Single item
+        // Single item.
         if (isset($uriVariables['id'])) {
-            return $repo->find($uriVariables['id']);
+            $document = $repo->find($uriVariables['id']);
+            if (null === $document) {
+                return null;
+            }
+            if ($isAdmin) {
+                return $document;
+            }
+            if ($isClient) {
+                $ticket = $document->getClientTicket();
+
+                return null !== $ticket && $ticket->getSubmittedBy() === $user ? $document : null;
+            }
+
+            // ROLE_USER: task-linked documents only.
+            return null !== $document->getTask() ? $document : null;
         }
 
-        // Collection
+        // Collection.
         $qb = $repo->createQueryBuilder('d')
             ->orderBy('d.id', 'DESC')
         ;
 
-        // Apply filters from query parameters
+        if ($isClient && !$isAdmin) {
+            $qb->innerJoin('d.clientTicket', 'ct')
+                ->andWhere('ct.submittedBy = :user')
+                ->setParameter('user', $user)
+            ;
+        } elseif (!$isAdmin) {
+            // ROLE_USER: only documents attached to a task.
+            $qb->andWhere('d.task IS NOT NULL');
+        }
+
         $filters = $context['filters'] ?? [];
         if (isset($filters['task'])) {
             $qb->andWhere('d.task = :task')
                 ->setParameter('task', self::extractId($filters['task']))
             ;
         }
+        if (isset($filters['clientTicket'])) {
+            $qb->andWhere('d.clientTicket = :clientTicket')
+                ->setParameter('clientTicket', self::extractId($filters['clientTicket']))
+            ;
+        }
 
         return $qb->getQuery()->getResult();
     }