feat(patients): phase B2 — attachments (ضمیمه)

Add patient file attachments: a new PatientAttachment entity (record-scoped,
CASCADE) + repository, and endpoints GET /patient/{uuid}/attachments,
POST /patient/{uuid}/attachment (raw-body upload) and DELETE
/patient/attachment/{uuid} (owner-scoped). Factor the shared raw-body upload
logic into FileUploadService. Wire the "ضمیمه" tab in PatientDetailPage
(upload + list + delete). PHPUnit covers list/delete/ownership; Vitest covers
the tab. API docs updated.

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

src/Patient/Controller/PatientController.php

@@ -50,9 +50,64 @@ class PatientController extends BaseController
         private readonly \App\Appointment\Repository\AppointmentRepository $appointmentRepo,
         private readonly \App\ClinicInvitation\Repository\ClinicDoctorInvitationRepository $invitationRepo,
         private readonly \App\Tag\Repository\TenantTagRepository $tenantTagRepo,
+        private readonly \App\Patient\Repository\PatientAttachmentRepository $attachmentRepo,
+        private readonly \App\Shared\Service\FileUploadService $fileUpload,
         private readonly LoggerInterface             $logger,
     ) {}
 
+    // ── Attachments (ضمیمه) ───────────────────────────────────────────────────
+
+    #[Route('/api/v1/patient/{uuid}/attachments', methods: ['GET'])]
+    public function listAttachments(string $uuid, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+        $record = $this->recordRepo->findByUuid($uuid);
+        if ($record === null || !$this->ownsRecord($record, $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_PATIENT_NOT_FOUND, ErrorCodes::message(ErrorCodes::ERR_PATIENT_NOT_FOUND), 404);
+        }
+
+        return $this->success(array_map(
+            fn(\App\Patient\Entity\PatientAttachment $a) => $a->toArray(),
+            $this->attachmentRepo->findByRecord($record)
+        ));
+    }
+
+    #[Route('/api/v1/patient/{uuid}/attachment', methods: ['POST'])]
+    public function uploadAttachment(string $uuid, Request $request, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+        $record = $this->recordRepo->findByUuid($uuid);
+        if ($record === null || !$this->ownsRecord($record, $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_PATIENT_NOT_FOUND, ErrorCodes::message(ErrorCodes::ERR_PATIENT_NOT_FOUND), 404);
+        }
+
+        try {
+            $stored = $this->fileUpload->storeFromRequest($request, 'patients/attachments');
+        } catch (\RuntimeException $e) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, $e->getMessage(), 422);
+        }
+
+        $name = trim((string) $request->query->get('name', '')) ?: $stored['filename'];
+        $attachment = new \App\Patient\Entity\PatientAttachment($record, $name, $stored['url'], $stored['filemime'], $stored['size']);
+        $this->attachmentRepo->save($attachment);
+
+        return $this->success($attachment->toArray(), 201);
+    }
+
+    #[Route('/api/v1/patient/attachment/{uuid}', methods: ['DELETE'])]
+    public function deleteAttachment(string $uuid, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+        $attachment = $this->attachmentRepo->findByUuid($uuid);
+        if ($attachment === null || !$this->ownsRecord($attachment->getRecord(), $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_NOT_FOUND_001, 'ضمیمه یافت نشد', 404);
+        }
+
+        $this->attachmentRepo->remove($attachment);
+
+        return $this->success(['message' => 'ضمیمه حذف شد']);
+    }
+
     /**
      * Assign record labels from the payload (`tags` = array of TenantTag uuids),
      * scoped to the caller's entity. Returns a 422 response on a foreign tag,