fix(appointment): make resource bookings independent of the doctor's calendar

Booking a device is not booking its doctor: the operator runs it and the doctor
only supervises. But bookAtomically locked the doctor row and isSlotTaken checked
overlap against the doctor alone, ignoring which resource was chosen, so a clinic
whose devices share one supervisor could not run two of them at once. Every
tenant in the database is in that position — clinic 2's six resources all point
at doctor 6.

Resource bookings now skip the doctor lock and carry no active_slot_key; their
guarantee comes from resource_occupancy, which understands capacity and seats.
Both direct paths write occupancy rows the way the hold engine already did, so
ResourceBookingSlotService stops being the only thing holding two sources of
truth together, and cancelling releases the seat.

Occupancy is bucketed in five-minute slices, which is coarser than a booking
time: a booking ending 12:35:04 spilled four seconds into the 12:35 bucket and
collided with the next one starting at that same second, despite zero real
overlap. This surfaced on real rows 76 and 77 during backfill. Resource bookings
now snap both ends of their window down to the bucket grid — schedule-driven
slots are already aligned, so only manually entered times move.

The seat is claimed after persist because it needs the appointment id; losing
the race removes the appointment rather than leaving a booking with no device
behind it.

app:appointment:backfill-resource-occupancy gives existing resource-backed
appointments their missing occupancy and clears the doctor keys that no longer
mean anything. It reports conflicts between two old bookings instead of picking
a loser.

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

src/Appointment/Controller/AppointmentController.php

@@ -49,6 +49,7 @@ class AppointmentController extends BaseController
         private readonly \App\Appointment\Service\AppointmentInsuranceService $appointmentInsurance,
         private readonly \App\Appointment\Service\ServiceBookingCalculator $serviceCalculator,
         private readonly \App\Appointment\Service\ServiceRescheduleService $rescheduleService,
+        private readonly \App\Appointment\Availability\Service\ResourceOccupier $occupier,
         private readonly \Psr\Log\LoggerInterface $logger,
     ) {}
 
@@ -505,6 +506,13 @@ class AppointmentController extends BaseController
             return $this->error(ErrorCodes::ERR_VALIDATION_001, 'زمان این اسلات گذشته است', 422);
         }
 
+        // ساعتِ نوبتِ منبع‌دار با مرز سطل‌های اشغال تراز می‌شود. اسلات‌های برنامهٔ
+        // هفتگی از قبل ترازند و این بی‌اثر است؛ ساعتِ دستی وگرنه با نوبتِ چسبیدهٔ
+        // بعدی سطل مشترک پیدا می‌کرد و بی‌دلیل تعارض می‌ساخت.
+        if ($resource !== null && $slotEnd > $slotStart) {
+            [$slotStart, $slotEnd] = \App\Appointment\Booking\Entity\OccupancyBucket::alignWindow($slotStart, $slotEnd);
+        }
+
         $doctor = $this->doctorRepo->findByUuid($doctorUuid);
         if ($doctor === null) {
             return $this->error(ErrorCodes::ERR_VALIDATION_002, 'دکتر یافت نشد', 404);
@@ -633,6 +641,23 @@ class AppointmentController extends BaseController
             return $this->error(ErrorCodes::ERR_CONFLICT_001, 'این نوبت قبلاً رزرو شده است', 409);
         }
 
+        // بعد از persist چون شناسهٔ نوبت لازم است. اینجاست که واقعاً صندلیِ منبع ادعا
+        // می‌شود؛ شکستش یعنی همین لحظه پر شد و نوبت باید برگردد.
+        if ($resource !== null) {
+            try {
+                $this->occupier->occupy(
+                    $resource,
+                    $appointment->getSlotStart(),
+                    $appointment->getSlotEnd(),
+                    appointmentId: (int) $appointment->getId(),
+                );
+            } catch (\App\Shared\Exception\AppException) {
+                $this->appointmentRepo->remove($appointment);
+
+                return $this->error(ErrorCodes::ERR_CONFLICT_001, 'این منبع در این زمان آزاد نیست', 409, 'resource_uuid');
+            }
+        }
+
         return $this->success(['data' => $appointment->toArray()], 201);
     }
 
@@ -1036,6 +1061,12 @@ class AppointmentController extends BaseController
         if (in_array($newStatus, self::CANCEL_STATUSES, true)) {
             $reason = isset($data['cancel_reason']) ? trim((string) $data['cancel_reason']) : '';
             $this->recordCancellation($appointment, $newStatus, $reason !== '' ? $reason : null, $user);
+
+            // بدون آزادسازی، سطل‌های اشغال می‌مانند و آن دستگاه برای همیشه در آن ساعت
+            // پر به نظر می‌رسد — نوبتی که لغو شده ولی جایش را پس نداده.
+            if ($appointment->getResource() !== null) {
+                $this->occupier->releaseForAppointment((int) $appointment->getId());
+            }
         }
 
         if ($newStatus === Appointment::STATUS_COMPLETED) {

src/Appointment/Controller/MyAppointmentsController.php

@@ -49,6 +49,7 @@ class MyAppointmentsController extends BaseController
         private readonly \App\Appointment\Repository\WeeklyScheduleRepository $scheduleRepo,
         private readonly \App\Resource\Repository\ClinicResourceRepository $resourceRepo,
         private readonly \App\Resource\Service\ResourceBookingSlotService $resourceSlots,
+        private readonly \App\Appointment\Availability\Service\ResourceOccupier $occupier,
     ) {}
 
     /**
@@ -226,6 +227,13 @@ class MyAppointmentsController extends BaseController
             return $this->error(ErrorCodes::VALIDATION, 'هزینه ویزیت الزامی است', 422, 'visit_price_rials');
         }
 
+        // ساعتِ نوبتِ منبع‌دار با مرز سطل‌های اشغال تراز می‌شود. اسلات‌های برنامهٔ
+        // هفتگی از قبل ترازند و این بی‌اثر است؛ ساعتِ دستیِ «ثبت خارج از برنامه»
+        // وگرنه با نوبتِ چسبیدهٔ بعدی سطل مشترک پیدا می‌کرد.
+        if ($resource !== null && !$isReserve && $slotEnd > $slotStart) {
+            [$slotStart, $slotEnd] = \App\Appointment\Booking\Entity\OccupancyBucket::alignWindow($slotStart, $slotEnd);
+        }
+
         // Identity is keyed on the national code (unique) so the case-file stays
         // single per person even when booked under a different mobile.
         $patient = $this->patientResolver->resolveForBooking($nationalCode, $mobile, $patientName);
@@ -277,14 +285,19 @@ class MyAppointmentsController extends BaseController
             }
 
             /**
-             * تداخل روی خودِ منبع جدا سنجیده می‌شود: `bookAtomically` فقط اسلاتِ پزشک
-             * را قفل می‌کند و دو پزشکِ متفاوت می‌توانند یک دستگاه را هم‌زمان بگیرند.
+             * پیش‌بررسیِ زودهنگام تا کاربر پیام روشن بگیرد؛ تضمین واقعی پایین‌تر با
+             * گرفتنِ صندلی در `resource_occupancy` انجام می‌شود، چون این بررسی
+             * به‌تنهایی در برابر دو درخواست هم‌زمان محافظت نمی‌کند.
              */
             if (!$isReserve && !$this->resourceSlots->isFree($resource, $slotStart, $slotEnd)) {
                 return $this->error(ErrorCodes::SLOT_TAKEN, 'این منبع در این زمان آزاد نیست', 409, 'resource_uuid');
             }
 
             $appointment->setResource($resource);
+
+            // شعبهٔ نوبتِ منبع‌دار از خودِ منبع می‌آید، نه از برنامهٔ هفتگی پزشک: دستگاه
+            // در برنامهٔ پزشک اسلاتی ندارد و `resolveSlotLocationId` برایش null می‌داد.
+            $appointment->setAddressId($resource->getAddress()->getId());
         }
 
         // پیوستِ همهٔ سرویس‌های انتخاب‌شده؛ سرویسِ اصلی = اولین سرویس (addServiceItem).
@@ -322,6 +335,24 @@ class MyAppointmentsController extends BaseController
             } catch (SlotTakenException) {
                 return $this->error(ErrorCodes::SLOT_TAKEN, 'این نوبت قبلاً رزرو شده است', 409);
             }
+
+            // بعد از persist چون شناسهٔ نوبت لازم است. شکستِ گرفتن صندلی یعنی منبع
+            // همین حالا پر شد؛ نوبت باید برگردد وگرنه رزروی می‌ماند که هیچ دستگاهی
+            // پشتش نیست.
+            if ($resource !== null) {
+                try {
+                    $this->occupier->occupy(
+                        $resource,
+                        $slotStart,
+                        $slotEnd,
+                        appointmentId: (int) $appointment->getId(),
+                    );
+                } catch (\App\Shared\Exception\AppException) {
+                    $this->appointmentRepo->remove($appointment);
+
+                    return $this->error(ErrorCodes::SLOT_TAKEN, 'این منبع در این زمان آزاد نیست', 409, 'resource_uuid');
+                }
+            }
         }
 
         return $this->success([