feat: add service-based booking mode to appointment scheduling

- Introduced a new booking mode in WeeklySchedule to support service-based appointments.
- Updated SlotCalculatorService to calculate available start times based on selected service durations and buffer times.
- Enhanced AppointmentController to handle service items during booking, calculating slot_end on the server side.
- Implemented validation to ensure at least one bookable service exists for doctors in service mode.
- Added new API endpoint to retrieve available appointment slots based on selected services.
- Updated MyAppointmentsController to accept service items during appointment creation.
- Modified ServiceItem entity to include a bookable flag, allowing services to be marked for scheduling.
- Created migration to add bookable column to service_items table.
- Added tests for service-based slot calculations and validation logic.

src/Appointment/Controller/AppointmentController.php

@@ -136,6 +136,63 @@ class AppointmentController extends BaseController
         ]);
     }
 
+    /**
+     * حالت نوبت‌دهی سرویسی: زمان‌های خالیِ کافی برای مجموعِ مدت سرویس‌های انتخاب‌شده.
+     * فقط سرویس‌های «نمایش در نوبت‌دهی» (bookable) و دارای مدت پذیرفته می‌شوند.
+     *
+     * GET /api/v1/appointment-service-slots?doctor_uuid=..&date=Y-m-d&service_item_uuids[]=..
+     */
+    #[Route('/api/v1/appointment-service-slots', methods: ['GET'])]
+    public function serviceSlots(Request $request): JsonResponse
+    {
+        $doctorUuid = trim($request->query->get('doctor_uuid', ''));
+        $date       = trim($request->query->get('date', ''));
+
+        $doctor = $this->doctorRepo->findByUuid($doctorUuid);
+        if ($doctor === null) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_002, 'دکتر یافت نشد', 404);
+        }
+        if (empty($date) || !preg_match('/^\d{4}-\d{2}-\d{2}$/', $date)) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'فرمت تاریخ نادرست است (Y-m-d)', 422, 'date');
+        }
+
+        $schedule = $this->scheduleRepo->findByDoctor($doctor);
+        $mode     = ($schedule ? $schedule->getMeta() : WeeklySchedule::DEFAULT_META)['booking_mode'] ?? WeeklySchedule::MODE_SLOT;
+        if ($mode !== WeeklySchedule::MODE_SERVICE) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'این پزشک در حالت نوبت‌دهی سرویسی نیست', 422);
+        }
+
+        $uuids = array_values(array_filter(array_map('trim', (array) $request->query->all('service_item_uuids'))));
+        if (empty($uuids)) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'انتخاب حداقل یک سرویس الزامی است', 422, 'service_item_uuids');
+        }
+
+        $totalMinutes = 0;
+        foreach ($uuids as $u) {
+            $item = $this->itemRepo->findByUuid($u);
+            if ($item === null) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_002, 'سرویس یافت نشد', 422, 'service_item_uuids');
+            }
+            if (!$item->isBookable()) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_001, 'این سرویس برای نوبت‌دهی فعال نیست', 422, 'service_item_uuids');
+            }
+            if (($item->getDurationMinutes() ?? 0) <= 0) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_001, 'مدت سرویس تعریف نشده است', 422, 'service_item_uuids');
+            }
+            $totalMinutes += (int) $item->getDurationMinutes();
+        }
+
+        $meta = $schedule ? $schedule->getMeta() : WeeklySchedule::DEFAULT_META;
+
+        return $this->success([
+            'doctor_uuid'            => $doctorUuid,
+            'date'                   => $date,
+            'total_duration_minutes' => $totalMinutes,
+            'buffer_minutes'         => (int) $meta['buffer_minutes'],
+            'start_times'            => $this->slotCalculator->getServiceStartTimes($doctor, $date, $totalMinutes),
+        ]);
+    }
+
     #[Route('/api/v1/appointment-settings/month-availability/{doctorUuid}', methods: ['GET'])]
     public function monthAvailability(string $doctorUuid, Request $request): JsonResponse
     {
@@ -224,6 +281,29 @@ class AppointmentController extends BaseController
         $slotStart  = (int) ($data['slot_start'] ?? 0);
         $slotEnd    = (int) ($data['slot_end'] ?? 0);
 
+        // حالت نوبت‌دهی سرویسی: مدت نوبت = مجموع مدت سرویس‌های bookableِ انتخاب‌شده،
+        // و slot_end سمت سرور محاسبه می‌شود (به مقدار کلاینت اعتماد نمی‌شود).
+        $serviceUuids = array_values(array_filter(array_map('trim', (array) ($data['service_item_uuids'] ?? []))));
+        $serviceItem  = null;
+        if (!empty($serviceUuids)) {
+            $totalMinutes = 0;
+            foreach ($serviceUuids as $u) {
+                $item = $this->itemRepo->findByUuid($u);
+                if ($item === null) {
+                    return $this->error(ErrorCodes::ERR_VALIDATION_002, 'سرویس یافت نشد', 422, 'service_item_uuids');
+                }
+                if (!$item->isBookable()) {
+                    return $this->error(ErrorCodes::ERR_VALIDATION_001, 'این سرویس برای نوبت‌دهی فعال نیست', 422, 'service_item_uuids');
+                }
+                if (($item->getDurationMinutes() ?? 0) <= 0) {
+                    return $this->error(ErrorCodes::ERR_VALIDATION_001, 'مدت سرویس تعریف نشده است', 422, 'service_item_uuids');
+                }
+                $totalMinutes += (int) $item->getDurationMinutes();
+                $serviceItem ??= $item;
+            }
+            $slotEnd = $slotStart + $totalMinutes * 60;
+        }
+
         if (empty($doctorUuid) || $slotStart <= 0 || $slotEnd <= $slotStart) {
             return $this->error(ErrorCodes::ERR_VALIDATION_001, 'doctor_uuid، slot_start و slot_end الزامی است', 422);
         }
@@ -261,6 +341,7 @@ class AppointmentController extends BaseController
         $appointment = new Appointment($doctor, $user, $slotStart, $slotEnd);
         $appointment->setPatientNationalCode($nationalCode);
         $appointment->setPatientGender($gender);
+        if ($serviceItem !== null) $appointment->setServiceItem($serviceItem);
         if (isset($data['note'])) $appointment->setNote($data['note']);
 
         // نماینده‌ی دامنه‌ی مبدأ رزرو (از Origin مرورگر)؛ گاردِ نهایی پورسانت در لحظه‌ی