feat: add visit price requirement feature

- Introduced a new boolean flag `require_visit_price` in the `EntityInsurancePricing` to enforce visit price for appointments.
- Updated the appointment creation endpoints to validate `visit_price_rials` based on the new flag.
- Added `visit_price_rials` field to the `Appointment` entity to store the visit price.
- Enhanced the `PatientService` to validate visit price during session creation.
- Updated API documentation to reflect changes in appointment and insurance pricing.
- Implemented a new service `VisitPriceRequirementResolver` to determine if a visit price is required for a doctor based on their pricing settings.
- Added migrations to update the database schema for the new fields.

src/Insurance/Controller/InsuranceController.php

@@ -229,10 +229,12 @@ class InsuranceController extends BaseController
         $rows = $this->pricingRepo->findByEntity($entityType, $entityId);
 
         $freeVisitPriceRials = 0;
+        $requireVisitPrice = false;
         $perInsurance = [];
         foreach ($rows as $row) {
             if ($row->isFreeVisit()) {
                 $freeVisitPriceRials = $row->getPatientShareRials();
+                $requireVisitPrice = $row->isRequireVisitPrice();
             } else {
                 $perInsurance[$row->getInsuranceId()] = $row->getPatientShareRials();
             }
@@ -251,6 +253,7 @@ class InsuranceController extends BaseController
             'entity_type'            => $entityType,
             'entity_id'              => $entityId,
             'free_visit_price_rials' => $freeVisitPriceRials,
+            'require_visit_price'    => $requireVisitPrice,
             'insurances'             => $insurances,
         ]);
     }
@@ -266,8 +269,24 @@ class InsuranceController extends BaseController
 
         $data = json_decode($request->getContent(), true) ?? [];
 
-        if (array_key_exists('free_visit_price_rials', $data)) {
-            $this->upsertPricing($entityType, $entityId, null, (int) $data['free_visit_price_rials']);
+        $freeVisitRow = $this->pricingRepo->findOneForInsurance($entityType, $entityId, null);
+
+        $requireVisitPrice = array_key_exists('require_visit_price', $data)
+            ? (bool) $data['require_visit_price']
+            : ($freeVisitRow?->isRequireVisitPrice() ?? false);
+
+        $freeVisitPrice = array_key_exists('free_visit_price_rials', $data)
+            ? (int) $data['free_visit_price_rials']
+            : ($freeVisitRow?->getPatientShareRials() ?? 0);
+
+        if ($requireVisitPrice && $freeVisitPrice <= 0) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'با فعال بودن «الزامی کردن هزینه ویزیت»، قیمت ویزیت آزاد الزامی است', 422, 'free_visit_price_rials');
+        }
+
+        $touchesFreeVisit = array_key_exists('free_visit_price_rials', $data) || array_key_exists('require_visit_price', $data);
+        if ($touchesFreeVisit && ($freeVisitRow !== null || $freeVisitPrice > 0)) {
+            $this->upsertPricing($entityType, $entityId, null, $freeVisitPrice)
+                ->setRequireVisitPrice($requireVisitPrice);
         }
 
         foreach (($data['insurances'] ?? []) as $row) {
@@ -290,7 +309,7 @@ class InsuranceController extends BaseController
         return $this->getInsurancePricing($user);
     }
 
-    private function upsertPricing(string $entityType, int $entityId, ?int $insuranceId, int $shareRials): void
+    private function upsertPricing(string $entityType, int $entityId, ?int $insuranceId, int $shareRials): EntityInsurancePricing
     {
         $row = $this->pricingRepo->findOneForInsurance($entityType, $entityId, $insuranceId);
         if ($row === null) {
@@ -299,6 +318,8 @@ class InsuranceController extends BaseController
             $row->setPatientShareRials($shareRials);
         }
         $this->pricingRepo->save($row, false);
+
+        return $row;
     }
 
     // ── TenantInsurance — قراردادهای بیمه‌ی tenant ─────────────────────────────