feat(patients): phase B3 — medical records (پرونده پزشکی)

Add patient medical-exam entries: a new PatientMedicalRecord entity
(record-scoped, CASCADE) + repository, and owner-scoped CRUD endpoints
(GET list, POST create, PATCH, DELETE) under /api/v1/patient. Wire the
"پرونده پزشکی" tab in PatientDetailPage (list + add/edit modal with title,
date and notes + delete). PHPUnit covers CRUD + ownership + validation;
Vitest covers the tab. API docs updated.

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

src/Patient/Controller/PatientController.php

@@ -51,10 +51,96 @@ class PatientController extends BaseController
         private readonly \App\ClinicInvitation\Repository\ClinicDoctorInvitationRepository $invitationRepo,
         private readonly \App\Tag\Repository\TenantTagRepository $tenantTagRepo,
         private readonly \App\Patient\Repository\PatientAttachmentRepository $attachmentRepo,
+        private readonly \App\Patient\Repository\PatientMedicalRecordRepository $medicalRepo,
         private readonly \App\Shared\Service\FileUploadService $fileUpload,
         private readonly LoggerInterface             $logger,
     ) {}
 
+    // ── Medical records (پرونده پزشکی) ────────────────────────────────────────
+
+    #[Route('/api/v1/patient/{uuid}/medical-records', methods: ['GET'])]
+    public function listMedicalRecords(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\PatientMedicalRecord $m) => $m->toArray(),
+            $this->medicalRepo->findByRecord($record)
+        ));
+    }
+
+    #[Route('/api/v1/patient/{uuid}/medical-record', methods: ['POST'])]
+    public function createMedicalRecord(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);
+        }
+
+        $data  = json_decode($request->getContent(), true) ?? [];
+        $title = trim((string) ($data['title'] ?? ''));
+        if ($title === '') {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'عنوان معاینه الزامی است', 422, 'title');
+        }
+
+        $body       = isset($data['body']) ? trim((string) $data['body']) : null;
+        $recordedAt = isset($data['recorded_at']) && $data['recorded_at'] !== '' ? (int) $data['recorded_at'] : null;
+
+        $medical = new \App\Patient\Entity\PatientMedicalRecord($record, $title, $body ?: null, $recordedAt);
+        $this->medicalRepo->save($medical);
+
+        return $this->success($medical->toArray(), 201);
+    }
+
+    #[Route('/api/v1/patient/medical-record/{uuid}', methods: ['PATCH'])]
+    public function updateMedicalRecord(string $uuid, Request $request, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+        $medical = $this->medicalRepo->findByUuid($uuid);
+        if ($medical === null || !$this->ownsRecord($medical->getRecord(), $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_NOT_FOUND_001, 'رکورد پزشکی یافت نشد', 404);
+        }
+
+        $data = json_decode($request->getContent(), true) ?? [];
+        if (isset($data['title'])) {
+            $t = trim((string) $data['title']);
+            if ($t === '') {
+                return $this->error(ErrorCodes::ERR_VALIDATION_001, 'عنوان معاینه الزامی است', 422, 'title');
+            }
+            $medical->setTitle($t);
+        }
+        if (array_key_exists('body', $data)) {
+            $b = trim((string) ($data['body'] ?? ''));
+            $medical->setBody($b === '' ? null : $b);
+        }
+        if (isset($data['recorded_at']) && $data['recorded_at'] !== '') {
+            $medical->setRecordedAt((int) $data['recorded_at']);
+        }
+
+        $this->medicalRepo->save($medical);
+
+        return $this->success($medical->toArray());
+    }
+
+    #[Route('/api/v1/patient/medical-record/{uuid}', methods: ['DELETE'])]
+    public function deleteMedicalRecord(string $uuid, #[CurrentUser] User $user): JsonResponse
+    {
+        [$entityType, $entityId] = $this->resolveEntity($user);
+        $medical = $this->medicalRepo->findByUuid($uuid);
+        if ($medical === null || !$this->ownsRecord($medical->getRecord(), $entityType, $entityId)) {
+            return $this->error(ErrorCodes::ERR_NOT_FOUND_001, 'رکورد پزشکی یافت نشد', 404);
+        }
+
+        $this->medicalRepo->remove($medical);
+
+        return $this->success(['message' => 'رکورد پزشکی حذف شد']);
+    }
+
     // ── Attachments (ضمیمه) ───────────────────────────────────────────────────
 
     #[Route('/api/v1/patient/{uuid}/attachments', methods: ['GET'])]

src/Patient/Entity/PatientMedicalRecord.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Patient\Entity;
+
+use App\Patient\Repository\PatientMedicalRecordRepository;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Uid\Uuid;
+
+/** A medical examination / note entry on a patient record (the «پرونده پزشکی» tab). */
+#[ORM\Entity(repositoryClass: PatientMedicalRecordRepository::class)]
+#[ORM\Table(name: 'patient_medical_records')]
+#[ORM\Index(columns: ['record_id'], name: 'idx_pmr_record')]
+class PatientMedicalRecord
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    private ?int $id = null;
+
+    #[ORM\Column(type: 'string', length: 36, unique: true)]
+    private string $uuid;
+
+    #[ORM\ManyToOne(targetEntity: PatientRecord::class)]
+    #[ORM\JoinColumn(name: 'record_id', nullable: false, onDelete: 'CASCADE')]
+    private PatientRecord $record;
+
+    #[ORM\Column(type: 'string', length: 200)]
+    private string $title;
+
+    #[ORM\Column(type: 'text', nullable: true)]
+    private ?string $body = null;
+
+    /** Exam date (Unix ts); defaults to creation time. */
+    #[ORM\Column(name: 'recorded_at', type: 'integer')]
+    private int $recordedAt;
+
+    #[ORM\Column(name: 'created_at', type: 'integer')]
+    private int $createdAt;
+
+    public function __construct(PatientRecord $record, string $title, ?string $body = null, ?int $recordedAt = null)
+    {
+        $this->uuid       = Uuid::v4()->toRfc4122();
+        $this->record     = $record;
+        $this->title      = $title;
+        $this->body       = $body;
+        $this->createdAt  = time();
+        $this->recordedAt = $recordedAt ?? $this->createdAt;
+    }
+
+    public function getId(): ?int              { return $this->id; }
+    public function getUuid(): string          { return $this->uuid; }
+    public function getRecord(): PatientRecord { return $this->record; }
+
+    public function setTitle(string $v): self       { $this->title = $v; return $this; }
+    public function setBody(?string $v): self       { $this->body = $v; return $this; }
+    public function setRecordedAt(int $v): self     { $this->recordedAt = $v; return $this; }
+
+    public function toArray(): array
+    {
+        return [
+            'uuid'        => $this->uuid,
+            'title'       => $this->title,
+            'body'        => $this->body,
+            'recorded_at' => $this->recordedAt,
+            'created_at'  => $this->createdAt,
+        ];
+    }
+}

src/Patient/Repository/PatientMedicalRecordRepository.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Patient\Repository;
+
+use App\Patient\Entity\PatientMedicalRecord;
+use App\Patient\Entity\PatientRecord;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class PatientMedicalRecordRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, PatientMedicalRecord::class);
+    }
+
+    public function findByUuid(string $uuid): ?PatientMedicalRecord
+    {
+        return $this->findOneBy(['uuid' => $uuid]);
+    }
+
+    /** @return PatientMedicalRecord[] */
+    public function findByRecord(PatientRecord $record): array
+    {
+        return $this->createQueryBuilder('m')
+            ->where('m.record = :record')
+            ->setParameter('record', $record)
+            ->orderBy('m.recordedAt', 'DESC')
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function save(PatientMedicalRecord $m): void
+    {
+        $this->getEntityManager()->persist($m);
+        $this->getEntityManager()->flush();
+    }
+
+    public function remove(PatientMedicalRecord $m): void
+    {
+        $this->getEntityManager()->remove($m);
+        $this->getEntityManager()->flush();
+    }
+}