feat(appointments): backend for clinic workflow (Figma نوبت‌ها) — phase A

Extend Appointment for the clinic-facing appointments area: - New nullable relations service_section/service_item/staff (بخش/سرویس/پرسنل) plus deposit_required/deposit_amount_rials (بیعانه) and is_reserve. - New statuses following_up (در حال پیگیری) and salon (سالن) with day-of transition rules; reserve entries never occupy a slot (several reserves may share one day), enforced in refreshActiveSlotKey. - rescheduleTo(slotStart, slotEnd, isReserve) keeps active_slot_key consistent for جا به جایی and reserve transfers. - New PATCH /api/v1/appointment/{uuid}: partial update covering edit, slot move (409 on taken slot, race backstop on the unique key), reserve toggle, patient swap (جایگزینی) and optional status transition; optimistic lock via version like the status endpoint. - POST /my/appointment now accepts the workflow fields and is_reserve (day-level entry: no past-slot rule, no atomic slot booking); GET /my/appointments gains reserve=1 and returns the new fields per row. Migration Version20260713195434 (+ mirrored on db_test). Docs updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-13 23:37:32 +03:30
parent 8287a48af1
commit 4678739d15
8 changed files with 671 additions and 11 deletions
@@ -33,6 +33,9 @@ class AppointmentController extends BaseController
        private readonly PatientService         $patientService,
        private readonly WeeklyScheduleRepository $scheduleRepo,
        private readonly \App\Representation\Service\DomainContextResolver $domainResolver,
+        private readonly \App\ClinicService\Repository\ServiceSectionRepository $sectionRepo,
+        private readonly \App\ClinicService\Repository\ServiceItemRepository $itemRepo,
+        private readonly \App\Staff\Repository\ClinicStaffRepository $staffRepo,
    ) {}

    // ── Public: available slots ───────────────────────────────────────────────
@@ -541,4 +544,111 @@ class AppointmentController extends BaseController

        return $this->success(['data' => $appointment->toArray()]);
    }
+
+    /**
+     * General update (ویرایش / جا به جایی / انتقال به رزرو / جایگزینی).
+     * All fields optional; only what is present in the body changes. Slot moves
+     * go through rescheduleTo so active_slot_key stays consistent. Optimistic
+     * lock via `version` like the status endpoint.
+     */
+    #[Route('/api/v1/appointment/{uuid}', methods: ['PATCH'])]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
+    public function update(string $uuid, Request $request, #[CurrentUser] User $user): JsonResponse
+    {
+        $appointment = $this->appointmentRepo->findByUuid($uuid);
+        if ($appointment === null) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_002, 'نوبت یافت نشد', 404);
+        }
+
+        if (!$this->canManage($appointment, $user)) {
+            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+        }
+
+        $data    = json_decode($request->getContent(), true) ?? [];
+        $version = (int) ($data['version'] ?? $appointment->getVersion());
+
+        // Slot move / reserve toggle — both times together, or neither.
+        $hasStart = array_key_exists('slot_start', $data);
+        $hasEnd   = array_key_exists('slot_end', $data);
+        if ($hasStart !== $hasEnd) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, 'slot_start و slot_end باید با هم ارسال شوند', 422, 'slot_start');
+        }
+        if ($hasStart || array_key_exists('is_reserve', $data)) {
+            $newStart = $hasStart ? (int) $data['slot_start'] : $appointment->getSlotStart();
+            $newEnd   = $hasStart ? (int) $data['slot_end'] : $appointment->getSlotEnd();
+            if ($newEnd < $newStart) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_001, 'ساعت پایان قبل از شروع است', 422, 'slot_end');
+            }
+            $isReserve = array_key_exists('is_reserve', $data) ? (bool) $data['is_reserve'] : null;
+            $movingToLiveSlot = ($isReserve ?? $appointment->isReserve()) === false;
+            if ($movingToLiveSlot && ($newStart !== $appointment->getSlotStart() || $newEnd !== $appointment->getSlotEnd())
+                && $this->appointmentRepo->isSlotTaken($appointment->getDoctor(), $newStart, $newEnd, $appointment->getId())) {
+                return $this->error(ErrorCodes::ERR_CONFLICT_001, 'این بازه زمانی قبلاً رزرو شده است', 409, 'slot_start');
+            }
+            $appointment->rescheduleTo($newStart, $newEnd, $isReserve);
+        }
+
+        // Workflow relations — empty string clears, uuid assigns, unknown → 422.
+        foreach ([
+            'service_section_uuid' => [$this->sectionRepo, 'setServiceSection', 'بخش'],
+            'service_item_uuid'    => [$this->itemRepo, 'setServiceItem', 'سرویس'],
+            'staff_uuid'           => [$this->staffRepo, 'setStaff', 'پرسنل'],
+        ] as $key => [$repo, $setter, $label]) {
+            if (!array_key_exists($key, $data)) {
+                continue;
+            }
+            $value = trim((string) ($data[$key] ?? ''));
+            if ($value === '') {
+                $appointment->$setter(null);
+                continue;
+            }
+            $entity = $repo->findByUuid($value);
+            if ($entity === null) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_002, $label . ' یافت نشد', 422, $key);
+            }
+            $appointment->$setter($entity);
+        }
+
+        if (array_key_exists('deposit_required', $data)) {
+            $appointment->setDepositRequired((bool) $data['deposit_required']);
+        }
+        if (array_key_exists('deposit_amount_rials', $data)) {
+            $appointment->setDepositAmountRials($data['deposit_amount_rials'] !== null ? (int) $data['deposit_amount_rials'] : null);
+        }
+        if (array_key_exists('note', $data)) {
+            $appointment->setNote($data['note'] !== null ? trim((string) $data['note']) : null);
+        }
+        // جایگزینی نوبت — swap the person occupying the slot.
+        if (array_key_exists('patient_name', $data)) {
+            $appointment->setPatientName($data['patient_name'] !== null ? trim((string) $data['patient_name']) : null);
+        }
+        if (array_key_exists('patient_mobile', $data)) {
+            $appointment->setPatientMobile($data['patient_mobile'] !== null ? trim((string) $data['patient_mobile']) : null);
+        }
+
+        // Optional status transition, same rules as the dedicated endpoint.
+        $newStatus = trim((string) ($data['status'] ?? ''));
+        if ($newStatus !== '' && $newStatus !== $appointment->getStatus()) {
+            if (!$appointment->canTransitionTo($newStatus)) {
+                return $this->error(ErrorCodes::ERR_VALIDATION_001, sprintf(
+                    'انتقال از "%s" به "%s" مجاز نیست', $appointment->getStatus(), $newStatus
+                ), 422);
+            }
+            $appointment->transitionTo($newStatus);
+            if ($newStatus === Appointment::STATUS_CONFIRMED) {
+                $this->patientService->autoCreateOnAppointmentConfirm($appointment);
+            }
+        }
+
+        try {
+            $this->appointmentRepo->saveWithLock($appointment, $version);
+        } catch (OptimisticLockException) {
+            return $this->error(ErrorCodes::ERR_CONFLICT_001, 'تداخل ویرایش همزمان. لطفاً دوباره تلاش کنید', 409);
+        } catch (\Doctrine\DBAL\Exception\UniqueConstraintViolationException) {
+            // race backstop: someone grabbed the slot between the pre-check and the flush
+            return $this->error(ErrorCodes::ERR_CONFLICT_001, 'این بازه زمانی قبلاً رزرو شده است', 409, 'slot_start');
+        }
+
+        return $this->success(['data' => $appointment->toArray()]);
+    }
 }