feat(patient): enhance session management with billing details and service tracking

src/Patient/Controller/PatientController.php

@@ -5,6 +5,7 @@ namespace App\Patient\Controller;
 use App\Auth\Entity\User;
 use App\Auth\Repository\UserActiveContextRepository;
 use App\Auth\Repository\UserRepository;
+use App\Billing\Repository\InvoiceRepository;
 use App\Billing\Service\ClaimService;
 use App\Billing\Service\InvoiceService;
 use Psr\Log\LoggerInterface;
@@ -45,6 +46,7 @@ class PatientController extends BaseController
         private readonly \App\Insurance\Repository\InsuranceRepository $insuranceRepo,
         private readonly InvoiceService              $invoiceService,
         private readonly ClaimService                $claimService,
+        private readonly InvoiceRepository           $invoiceRepo,
         private readonly LoggerInterface             $logger,
     ) {}
 
@@ -309,13 +311,37 @@ class PatientController extends BaseController
         $total    = $this->sessionRepo->countByRecord($record);
 
         return $this->paginated(
-            array_map(fn($s) => $s->toArray(), $sessions),
+            array_map(fn($s) => $this->sessionWithBilling($s), $sessions),
             $total,
             $page,
             $limit
         );
     }
 
+    /**
+     * خروجی session به‌همراه خلاصه‌ی صورتحساب: uuid فاکتور (در صورت وجود) و
+     * مانده‌ی بدهیِ سهم بیمار. اگر session تسویه شده باشد (payment_method != pending)
+     * بدهی صفر است؛ در غیر این صورت سهم بیمار از فاکتور یا کل مبلغ نهایی.
+     */
+    private function sessionWithBilling(\App\Patient\Entity\PatientSession $session): array
+    {
+        $data    = $session->toArray();
+        $invoice = $session->getId() !== null ? $this->invoiceRepo->findBySession($session->getId()) : null;
+
+        $data['invoice_uuid']   = $invoice?->getUuid();
+        $data['invoice_status'] = $invoice?->getStatus();
+
+        if ($data['is_paid']) {
+            $data['patient_debt_rials'] = 0;
+        } elseif ($invoice !== null) {
+            $data['patient_debt_rials'] = $invoice->getPatientRials();
+        } else {
+            $data['patient_debt_rials'] = $session->getFinalPriceRials();
+        }
+
+        return $data;
+    }
+
     #[Route('/api/v1/patient/{uuid}/session', methods: ['POST'])]
     public function createSession(string $uuid, Request $request, #[CurrentUser] User $user): JsonResponse
     {