Add migration to enhance session_payments table with payment_method_uuid and reference fields for split-payment details

src/Appointment/Controller/AppointmentController.php

@@ -1004,6 +1004,8 @@ class AppointmentController extends BaseController
             ), 422);
         }
 
+        // پرداختِ چندروشی (split): هر ردیف یک روش + مبلغ، و به‌اختیار جزئیاتِ روش
+        // (uuid کارت‌خوان/حساب بانکیِ ثبت‌شده + شناسه تراکنش).
         $payments = [];
         foreach ((array) ($data['payments'] ?? []) as $row) {
             $method = trim((string) ($row['method'] ?? ''));
@@ -1014,7 +1016,14 @@ class AppointmentController extends BaseController
             if ($amount <= 0) {
                 return $this->error(ErrorCodes::ERR_SESSION_PAYMENT_INVALID, ErrorCodes::message(ErrorCodes::ERR_SESSION_PAYMENT_INVALID), 422, 'amount_rials');
             }
-            $payments[] = ['method' => $method, 'amount_rials' => $amount];
+            $methodUuid = trim((string) ($row['payment_method_uuid'] ?? ''));
+            $reference  = trim((string) ($row['reference'] ?? ''));
+            $payments[] = [
+                'method'              => $method,
+                'amount_rials'        => $amount,
+                'payment_method_uuid' => $methodUuid !== '' ? mb_substr($methodUuid, 0, 36) : null,
+                'reference'           => $reference !== '' ? mb_substr($reference, 0, 255) : null,
+            ];
         }
 
         try {

src/Appointment/Service/AppointmentConfirmationService.php

@@ -60,7 +60,7 @@ class AppointmentConfirmationService
      * مودالی ایستاده که مبلغ نشان داده و منتظر تأیید است؛ «قطعی شد ولی پول ثبت نشد»
      * بدترین خروجیِ ممکن است.
      *
-     * @param  array<int, array{method: string, amount_rials: int}> $payments
+     * @param  array<int, array{method: string, amount_rials: int, payment_method_uuid?: ?string, reference?: ?string}> $payments
      * @return PatientSession|null null یعنی این tenant قابلیت پرونده را ندارد
      *                             (فقط وقتی مجاز است که پرداختی هم ارسال نشده باشد)
      */
@@ -91,6 +91,8 @@ class AppointmentConfirmationService
                     $payment['amount_rials'],
                     null,
                     $actor,
+                    $payment['payment_method_uuid'] ?? null,
+                    $payment['reference'] ?? null,
                 );
             }
 

src/Patient/Entity/SessionPayment.php

@@ -35,6 +35,14 @@ class SessionPayment
     #[ORM\Column(name: 'amount_rials', type: 'integer')]
     private int $amountRials;
 
+    /** uuid یک کارت‌خوان (Pos) یا حساب بانکی (BankAccount) ثبت‌شده — برای pos/card. */
+    #[ORM\Column(name: 'payment_method_uuid', type: 'string', length: 36, nullable: true)]
+    private ?string $paymentMethodUuid = null;
+
+    /** شناسه تراکنش / شماره پیگیری پرداخت (اختیاری). */
+    #[ORM\Column(name: 'reference', type: 'string', length: 255, nullable: true)]
+    private ?string $reference = null;
+
     #[ORM\Column(name: 'paid_at', type: 'integer')]
     private int $paidAt;
 
@@ -63,6 +71,8 @@ class SessionPayment
     public function getSession(): PatientSession { return $this->session; }
     public function getMethod(): string          { return $this->method; }
     public function getAmountRials(): int        { return $this->amountRials; }
+    public function getPaymentMethodUuid(): ?string { return $this->paymentMethodUuid; }
+    public function getReference(): ?string      { return $this->reference; }
     public function getPaidAt(): int             { return $this->paidAt; }
     public function getCreatedBy(): ?User        { return $this->createdBy; }
     public function getCreatedByName(): ?string  { return $this->createdByName; }
@@ -72,17 +82,21 @@ class SessionPayment
     public function setCreatedByName(?string $n): self { $this->createdByName = $n; return $this; }
     public function setMethod(string $m): self         { $this->method = $m; return $this; }
     public function setAmountRials(int $v): self       { $this->amountRials = $v; return $this; }
+    public function setPaymentMethodUuid(?string $v): self { $this->paymentMethodUuid = $v; return $this; }
+    public function setReference(?string $v): self     { $this->reference = $v; return $this; }
     public function setPaidAt(int $v): self            { $this->paidAt = $v; return $this; }
 
     public function toArray(): array
     {
         return [
-            'uuid'            => $this->uuid,
-            'method'          => $this->method,
-            'amount_rials'    => $this->amountRials,
-            'paid_at'         => $this->paidAt,
-            'created_by_name' => $this->createdByName,
-            'created_at'      => $this->createdAt,
+            'uuid'                => $this->uuid,
+            'method'              => $this->method,
+            'amount_rials'        => $this->amountRials,
+            'payment_method_uuid' => $this->paymentMethodUuid,
+            'reference'           => $this->reference,
+            'paid_at'             => $this->paidAt,
+            'created_by_name'     => $this->createdByName,
+            'created_at'          => $this->createdAt,
         ];
     }
 }

src/Patient/Service/PatientService.php

@@ -596,6 +596,8 @@ class PatientService
         int $amountRials,
         ?int $paidAt = null,
         ?User $actor = null,
+        ?string $paymentMethodUuid = null,
+        ?string $reference = null,
     ): SessionPayment {
         if (!in_array($method, SessionPayment::METHODS, true)) {
             throw new AppException(ErrorCodes::ERR_SESSION_PAYMENT_INVALID, null, 422, 'method');
@@ -627,7 +629,9 @@ class PatientService
 
         $payment = new SessionPayment($session, $method, $amountRials, $paidAt);
         $payment->setCreatedBy($actor)
-            ->setCreatedByName($this->walletService->resolveActorName($actor));
+            ->setCreatedByName($this->walletService->resolveActorName($actor))
+            ->setPaymentMethodUuid($paymentMethodUuid !== null && $paymentMethodUuid !== '' ? $paymentMethodUuid : null)
+            ->setReference($reference !== null && $reference !== '' ? $reference : null);
         $this->sessionPaymentRepo->save($payment);
         $session->addPayment($payment);