feat(appointments,patients): make clinic context a first-class citizen

Three related fixes, all rooted in the same flaw: authorization and scoping decided by the caller's role instead of by the environment the data belongs to. 1. Single-appointment access (clinic operations were entirely broken) AppointmentController::canView/canManage only knew the patient, the owning doctor and admin -- appointment.clinic was never consulted. A clinic user could create an appointment through /my/appointment but got 403 on detail, edit, move, reserve transfer/replace and status change, so nearly every appointment operation failed in clinic mode. AppointmentAccessChecker now decides from appointment.clinic: clinic owner, member doctor (via ClinicDoctorPermissionChecker) and assigned secretary (via active context + DoctorSecretary) are recognised. Actions reuse the existing permission vocabulary, so active=false remains the single source of truth for "collaboration ended". Cancellation is gated separately and an inline status on PATCH /appointment/{uuid} cannot bypass that gate. The patient is narrowed to view + cancel. Also fixed alongside: listByDoctor now serves a clinic manager but scoped to that clinic; todayStats gained an admin branch and no longer passes an array of doctor ids as the clinic parameter; PatientController::appointments filters on appointment.clinic instead of current membership, so deactivating a doctor no longer erases clinic appointment history from the case file. The doctor-only active_slot_key was reviewed and deliberately left alone -- a doctor is one physical person, so adding clinic to the key would permit double-booking, not fix a bug. Reasoning recorded on the entity. 2. Appointment registration and confirmation Panel-created appointments are born pending ("ثبت شده") instead of confirmed. Confirming is now an explicit act: POST /appointment/{uuid}/confirm transitions the status, files the case file for the appointment's environment (reusing an existing record or creating one) and registers full or partial payments on the resulting visit -- all in one transaction. AppointmentExpiryService would have expired those pending appointments the moment their slot time passed; findExpiredPending is now limited to online gateway holds, which are the only pendings carrying a TTL. A pending appointment still occupies its slot, so the time stays reserved. The admin panel gets a "قطعی کردن نوبت" modal showing the visit fee, each selected service, the total, and paid/remaining/status. It is wired inside AppointmentStatusDropdown, so picking "confirmed" anywhere (timeline, detail, reserve list, info modal) goes through it and confirmation can never silently skip the case file and payment. 3. Clinic case-file access PatientRecordScopeResolver replaces the single-destination role mapping: the active context decides, so a doctor invited into a clinic finally sees their patients' records there. A clinic record is per-patient and shared by design, so "their own patients" is derived from appointments with that doctor in that clinic rather than from a new column. Clinic secretaries are limited to their assigned doctors. Read and write share one rule, and out-of-scope records report 404 so other environments are never disclosed. Tests: 29 new cases across the three areas (clinic appointment access, confirm flow, clinic record access). Full suite 466 tests, 2 pre-existing failures unchanged. API docs updated for all three. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-18 21:04:50 +03:30
parent e6422014d1
commit 7921407f33
26 changed files with 2409 additions and 188 deletions
@@ -7,6 +7,7 @@ use App\Appointment\Entity\WeeklySchedule;
 use App\Appointment\Repository\AppointmentRepository;
 use App\Appointment\Repository\SlotTakenException;
 use App\Appointment\Repository\WeeklyScheduleRepository;
+use App\Appointment\Security\AppointmentAccessChecker;
 use App\Appointment\Service\AppointmentConfirmationService;
 use App\Appointment\Service\SlotCalculatorService;
 use App\Clinic\Entity\Clinic;
@@ -40,6 +41,7 @@ class AppointmentController extends BaseController
        private readonly \App\ClinicService\Repository\ServiceItemRepository $itemRepo,
        private readonly \App\Staff\Repository\ClinicStaffRepository $staffRepo,
        private readonly \App\Appointment\Repository\AppointmentEventRepository $eventRepo,
+        private readonly \App\Appointment\Security\AppointmentAccessChecker $accessChecker,
        private readonly \Psr\Log\LoggerInterface $logger,
    ) {}

@@ -576,7 +578,7 @@ class AppointmentController extends BaseController
        }

        if (!$this->canView($appointment, $user)) {
-            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
        }

        return $this->success(['data' => $appointment->toArray()]);
@@ -631,12 +633,17 @@ class AppointmentController extends BaseController
            return $this->error(ErrorCodes::ERR_VALIDATION_002, 'دکتر یافت نشد', 404);
        }

-        if ($doctor->getUser()->getId() !== $user->getId() && !$user->hasRole('ROLE_ADMIN')) {
-            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+        $isOwner = $doctor->getUser()->getId() === $user->getId() || $user->hasRole('ROLE_ADMIN');
+
+        // مدیر کلینیک لیست پزشک عضو را می‌بیند، ولی فقط نوبت‌های همان کلینیک —
+        // نوبت‌های مطب شخصی پزشک به کلینیک نشت نمی‌کند.
+        $scopeClinic = $isOwner ? null : $this->accessChecker->viewableClinicFor($user, $doctor);
+        if (!$isOwner && $scopeClinic === null) {
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
        }

        $status       = $request->query->get('status');
-        $appointments = $this->appointmentRepo->findByDoctor($doctor, $status);
+        $appointments = $this->appointmentRepo->findByDoctor($doctor, $status, $scopeClinic);

        return $this->success(['data' => array_map(fn(Appointment $a) => $a->toArray(), $appointments)]);
    }
@@ -685,16 +692,12 @@ class AppointmentController extends BaseController

    private function canView(Appointment $a, User $user): bool
    {
-        return $a->getUser()->getId() === $user->getId()
-            || $a->getDoctor()->getUser()->getId() === $user->getId()
-            || $user->hasRole('ROLE_ADMIN');
+        return $this->accessChecker->canView($a, $user);
    }

    private function canManage(Appointment $a, User $user): bool
    {
-        return $a->getUser()->getId() === $user->getId()
-            || $a->getDoctor()->getUser()->getId() === $user->getId()
-            || $user->hasRole('ROLE_ADMIN');
+        return $this->accessChecker->canManage($a, $user);
    }

    /**
@@ -855,14 +858,20 @@ class AppointmentController extends BaseController
            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) ?? [];
        $newStatus = trim($data['status'] ?? '');
        $version   = (int) ($data['version'] ?? $appointment->getVersion());

+        // لغو مجوز جداگانه دارد: منشی به‌صورت پیش‌فرض اجازهٔ لغو ندارد ولی وضعیت‌های
+        // دیگر را تغییر می‌دهد.
+        $action = in_array($newStatus, self::CANCEL_STATUSES, true)
+            ? AppointmentAccessChecker::ACTION_CANCEL
+            : AppointmentAccessChecker::ACTION_UPDATE_STATUS;
+
+        if (!$this->accessChecker->can($appointment, $user, $action)) {
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
+        }
+
        if (!$appointment->canTransitionTo($newStatus)) {
            return $this->error(ErrorCodes::ERR_VALIDATION_001, sprintf(
                'انتقال از "%s" به "%s" مجاز نیست', $appointment->getStatus(), $newStatus
@@ -889,6 +898,81 @@ class AppointmentController extends BaseController
        return $this->success(['data' => $appointment->toArray()]);
    }

+    /**
+     * قطعی‌کردن نوبت به‌همراه پرداخت — «ثبت‌شده» → «قطعی».
+     *
+     * یک عملِ اتمیک: انتقال وضعیت، ساخت/یافتنِ پروندهٔ همان محیط با سرویس‌های نوبت،
+     * و ثبت پرداخت‌های کامل یا جزئی روی همان مراجعه. اگر هر مرحله شکست بخورد هیچ‌کدام
+     * ثبت نمی‌شوند.
+     */
+    #[OA\Post(
+        path: '/api/v1/appointment/{uuid}/confirm',
+        summary: 'Confirm an appointment and register its payments on the patient case file',
+        security: [['bearerAuth' => []]],
+        responses: [
+            new OA\Response(response: 200, description: 'Appointment confirmed'),
+            new OA\Response(response: 403, description: 'Access denied, or payments sent without the patient_records feature'),
+            new OA\Response(response: 404, description: 'Appointment not found'),
+            new OA\Response(response: 409, description: 'Version conflict'),
+            new OA\Response(response: 422, description: 'Invalid transition or payment'),
+        ]
+    )]
+    #[Route('/api/v1/appointment/{uuid}/confirm', methods: ['POST'])]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
+    public function confirm(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->accessChecker->can($appointment, $user, AppointmentAccessChecker::ACTION_UPDATE_STATUS)) {
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
+        }
+
+        $data    = json_decode($request->getContent(), true) ?? [];
+        $version = (int) ($data['version'] ?? $appointment->getVersion());
+
+        if (!$appointment->canTransitionTo(Appointment::STATUS_CONFIRMED)) {
+            return $this->error(ErrorCodes::ERR_VALIDATION_001, sprintf(
+                'انتقال از "%s" به "%s" مجاز نیست', $appointment->getStatus(), Appointment::STATUS_CONFIRMED
+            ), 422);
+        }
+
+        $payments = [];
+        foreach ((array) ($data['payments'] ?? []) as $row) {
+            $method = trim((string) ($row['method'] ?? ''));
+            $amount = (int) ($row['amount_rials'] ?? 0);
+            if (!in_array($method, \App\Patient\Entity\SessionPayment::METHODS, true)) {
+                return $this->error(ErrorCodes::ERR_SESSION_PAYMENT_INVALID, ErrorCodes::message(ErrorCodes::ERR_SESSION_PAYMENT_INVALID), 422, 'method');
+            }
+            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];
+        }
+
+        try {
+            $session = $this->appointmentConfirmation->confirmWithPayments($appointment, $version, $payments, $user);
+        } catch (OptimisticLockException) {
+            return $this->error(ErrorCodes::ERR_CONFLICT_001, 'تداخل ویرایش همزمان. لطفاً دوباره تلاش کنید', 409);
+        }
+
+        return $this->success([
+            'appointment' => $appointment->toArray(),
+            'session'     => $session === null ? null : [
+                'uuid'              => $session->getUuid(),
+                'visit_price_rials' => $session->getVisitPriceRials(),
+                'services_total_rials' => $session->getServicesTotalRials(),
+                'final_price_rials' => $session->getFinalPriceRials(),
+                'discount_rials'    => $session->getDiscountRials(),
+                'paid_total_rials'  => $session->getPaidTotalRials(),
+                'remaining_rials'   => $session->getRemainingRials(),
+                'is_paid'           => $session->getRemainingRials() === 0,
+            ],
+        ]);
+    }
+
    /**
     * General update (ویرایش / جا به جایی / انتقال به رزرو / جایگزینی).
     * All fields optional; only what is present in the body changes. Slot moves
@@ -905,12 +989,18 @@ class AppointmentController extends BaseController
        }

        if (!$this->canManage($appointment, $user)) {
-            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
        }

        $data    = json_decode($request->getContent(), true) ?? [];
        $version = (int) ($data['version'] ?? $appointment->getVersion());

+        // status درون‌خطی نباید گیت لغو را دور بزند.
+        if (in_array(trim((string) ($data['status'] ?? '')), self::CANCEL_STATUSES, true)
+            && !$this->accessChecker->canCancel($appointment, $user)) {
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
+        }
+
        // Slot move / reserve toggle — both times together, or neither.
        $hasStart = array_key_exists('slot_start', $data);
        $hasEnd   = array_key_exists('slot_end', $data);
@@ -1015,8 +1105,8 @@ class AppointmentController extends BaseController
        if ($appointment === null) {
            return $this->error(ErrorCodes::ERR_VALIDATION_002, 'نوبت یافت نشد', 404);
        }
-        if (!$this->canManage($appointment, $user)) {
-            return $this->error(ErrorCodes::ERR_AUTH_006, 'دسترسی ممنوع', 403);
+        if (!$this->canView($appointment, $user)) {
+            return $this->error(ErrorCodes::ERR_ACCESS_DENIED, 'دسترسی ممنوع', 403);
        }

        return $this->success($this->eventRepo->findByAppointmentUuid($uuid));
@@ -45,7 +45,6 @@ class MyAppointmentsController extends BaseController
        private readonly \App\Auth\Repository\UserRepository $userRepo,
        private readonly \App\UserProfile\Repository\UserProfileRepository $profileRepo,
        private readonly VisitPriceRequirementResolver $visitPriceResolver,
-        private readonly \App\Appointment\Service\AppointmentConfirmationService $appointmentConfirmation,
    ) {}

    #[Route('/api/v1/my/appointment', methods: ['POST'])]
@@ -186,10 +185,10 @@ class MyAppointmentsController extends BaseController
        $appointment->setPatientName($patient->getRealName() ?: $patientName);
        $appointment->setPatientMobile($mobile);

-        // نوبتی که خودِ کلینیک/پزشک ثبت می‌کند پرداخت آنلاین ندارد و منتظر چیزی نیست؛
-        // قطعی است. transitionTo قبل از ذخیره می‌آید تا active_slot_key با وضعیت نهایی
-        // محاسبه شود.
-        $appointment->transitionTo(Appointment::STATUS_CONFIRMED);
+        // نوبت پنلی «ثبت‌شده» (pending) متولد می‌شود، نه قطعی: قطعی‌شدن یک عملِ جداست
+        // که هزینه‌ها را نشان می‌دهد و پرداخت می‌گیرد (POST /appointment/{uuid}/confirm).
+        // pending هم اسلات را اشغال می‌کند (SLOT_OCCUPYING_STATUSES)، پس جای نوبت
+        // محفوظ می‌ماند. expiresAt ست نمی‌شود، پس هرگز خودبه‌خود منقضی نمی‌شود.

        if ($isReserve) {
            // Day-level reserve: no slot occupation, plain save (no atomic slot check).
@@ -203,8 +202,6 @@ class MyAppointmentsController extends BaseController
            }
        }

-        $this->appointmentConfirmation->onConfirmed($appointment);
-
        return $this->success([
            'uuid'       => $appointment->getUuid(),
            'slot_start' => $slotStart,
@@ -403,30 +400,44 @@ class MyAppointmentsController extends BaseController
            ->groupBy('a.status');

        $roles = $user->getRoles();
-        if (in_array('ROLE_CLINIC', $roles, true)) {
+        if (in_array('ROLE_ADMIN', $roles, true)) {
+            // Admin sees all
+        } elseif (in_array('ROLE_CLINIC', $roles, true)) {
            $clinic = $this->clinicRepo->findByUser($user);
-            if ($clinic) {
-                $qb->join('App\Clinic\Entity\Clinic', 'c', 'WITH', 'd MEMBER OF c.doctors')
-                   ->andWhere('c = :clinic')
-                   ->setParameter('clinic', $clinic);
+            if ($clinic === null) {
+                return $this->emptyTodayStats();
            }
+            $qb->join('App\Clinic\Entity\Clinic', 'c', 'WITH', 'd MEMBER OF c.doctors')
+               ->andWhere('c = :clinic')
+               ->setParameter('clinic', $clinic);
        } elseif (in_array('ROLE_DOCTOR', $roles, true)) {
            $doctor = $this->doctorRepo->findByUser($user);
-            if ($doctor) {
-                $qb->andWhere('a.doctor = :doctor')->setParameter('doctor', $doctor);
+            if ($doctor === null) {
+                return $this->emptyTodayStats();
            }
+            $qb->andWhere('a.doctor = :doctor')->setParameter('doctor', $doctor);
        } elseif (in_array('ROLE_SECRETARY', $roles, true)) {
            $filter = $this->resolveSecretaryFilter($user);
-            if ($filter !== null) {
-                [$filterType, $filterValue] = $filter;
-                if ($filterType === 'clinic') {
-                    $qb->join('App\Clinic\Entity\Clinic', 'c', 'WITH', 'd MEMBER OF c.doctors')
-                       ->andWhere('c = :clinic')
-                       ->setParameter('clinic', $filterValue);
-                } else {
-                    $qb->andWhere('a.doctor = :doctor')->setParameter('doctor', $filterValue);
-                }
+            if ($filter === null) {
+                return $this->emptyTodayStats();
            }
+            // در scope کلینیک، filterValue آرایه‌ی idهای پزشکانِ تخصیص‌یافته است —
+            // نه خود کلینیک؛ هم‌شکل با myAppointments.
+            [$filterType, $filterValue, $canView] = $filter;
+            if (!$canView) {
+                return $this->emptyTodayStats();
+            }
+            if ($filterType === 'clinic') {
+                if (empty($filterValue)) {
+                    return $this->emptyTodayStats();
+                }
+                $qb->andWhere('a.doctor IN (:doctorIds)')->setParameter('doctorIds', $filterValue);
+            } else {
+                $qb->andWhere('a.doctor = :doctor')->setParameter('doctor', $filterValue);
+            }
+        } else {
+            // بیمار عادی: فقط نوبت‌های خودش — نه شمارشِ بی‌محدودهٔ کل سیستم.
+            $qb->andWhere('a.user = :patient')->setParameter('patient', $user);
        }

        $rows = $qb->getQuery()->getArrayResult();
@@ -451,6 +462,11 @@ class MyAppointmentsController extends BaseController
        ]);
    }

+    private function emptyTodayStats(): JsonResponse
+    {
+        return $this->success(['total' => 0, 'completed' => 0, 'waiting' => 0, 'cancelled' => 0]);
+    }
+
    /**
     * Whether the acting user is allowed to book onto this doctor's calendar.
     * The role gate alone is not enough: a doctor/clinic/secretary must be
@@ -200,6 +200,11 @@ class Appointment
    /**
     * Recompute the unique active-slot key from the current status. Non-null
     * while the appointment occupies the slot; null once it is cancelled.
+     *
+     * کلید عمداً clinic ندارد و فقط doctor+slotStart است: برنامهٔ هفتگی هر محیط
+     * جداست (WeeklySchedule با UNIQUE(doctor_id, clinic_key)) و می‌تواند با محیط
+     * دیگر هم‌پوشانی داشته باشد، ولی پزشک یک نفر است. افزودن clinic به کلید یعنی
+     * اجازهٔ رزرو هم‌زمان همان پزشک در مطب و کلینیک — نه رفع باگ.
     */
    private function refreshActiveSlotKey(): void
    {
@@ -356,8 +361,14 @@ class Appointment
            'patient_reason'        => $this->patientReason,
            'service_section' => $this->serviceSection ? ['uuid' => $this->serviceSection->getUuid(), 'name' => $this->serviceSection->getName()] : null,
            'service_item'    => $this->serviceItem ? ['uuid' => $this->serviceItem->getUuid(), 'name' => $this->serviceItem->getName()] : null,
+            // price_rials لازم است تا مودالِ «قطعی کردن نوبت» بتواند هزینه‌ها را قبل از
+            // ساخته‌شدنِ مراجعه نشان دهد.
            'service_items'   => array_map(
-                fn(\App\ClinicService\Entity\ServiceItem $i) => ['uuid' => $i->getUuid(), 'name' => $i->getName()],
+                fn(\App\ClinicService\Entity\ServiceItem $i) => [
+                    'uuid'        => $i->getUuid(),
+                    'name'        => $i->getName(),
+                    'price_rials' => $i->getPriceRials(),
+                ],
                $this->serviceItems->toArray()
            ),
            'staff'           => $this->staff ? ['uuid' => $this->staff->getUuid(), 'full_name' => $this->staff->getFullName()] : null,
@@ -4,6 +4,7 @@ namespace App\Appointment\Repository;

 use App\Appointment\Entity\Appointment;
 use App\Auth\Entity\User;
+use App\Clinic\Entity\Clinic;
 use App\Doctor\Entity\Doctor;
 use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
 use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
@@ -172,13 +173,33 @@ class AppointmentRepository extends ServiceEntityRepository
    }

    /** @return Appointment[] */
-    public function findByDoctor(Doctor $doctor, ?string $status = null): array
+    public function findByDoctor(Doctor $doctor, ?string $status = null, ?Clinic $clinic = null): array
    {
        $criteria = ['doctor' => $doctor];
        if ($status !== null) $criteria['status'] = $status;
+        // محدودکردن به یک محیط: مدیر کلینیک نباید نوبت‌های مطب شخصی پزشک را ببیند.
+        if ($clinic !== null) $criteria['clinic'] = $clinic;
        return $this->findBy($criteria, ['slotStart' => 'ASC']);
    }

+    /**
+     * نوبت‌های یک بیمار در یک کلینیک — بر پایهٔ خودِ محیطِ ثبت‌شدهٔ نوبت، تا غیرفعال
+     * شدنِ بعدیِ پزشک تاریخچه را از پروندهٔ کلینیک حذف نکند.
+     *
+     * @return Appointment[]
+     */
+    public function findByUserAndClinic(User $user, int $clinicId): array
+    {
+        return $this->createQueryBuilder('a')
+            ->where('a.user = :user')
+            ->andWhere('IDENTITY(a.clinic) = :clinicId')
+            ->setParameter('user', $user)
+            ->setParameter('clinicId', $clinicId)
+            ->orderBy('a.slotStart', 'DESC')
+            ->getQuery()
+            ->getResult();
+    }
+
    /** @return Appointment[] */
    public function findByUser(User $user, ?string $status = null): array
    {
@@ -247,11 +268,20 @@ class AppointmentRepository extends ServiceEntityRepository
            ->getResult();
    }

-    /** @return Appointment[] pending appointments older than given timestamp */
+    /**
+     * رزروهای آنلاینِ پرداخت‌نشده که ساعتشان هم گذشته است.
+     *
+     * `expiresAt IS NOT NULL` یعنی فقط نگه‌داشتِ موقتِ درگاه (markPendingWithTtl).
+     * نوبت «ثبت‌شده»ای که کلینیک/پزشک از پنل ثبت کرده TTL ندارد و نباید سرِ ساعتِ
+     * نوبت خودبه‌خود منقضی شود — قطعی/لغو کردنش تصمیم اپراتور است.
+     *
+     * @return Appointment[]
+     */
    public function findExpiredPending(int $before): array
    {
        return $this->createQueryBuilder('a')
            ->where('a.status = :status')
+            ->andWhere('a.expiresAt IS NOT NULL')
            ->andWhere('a.slotStart < :before')
            ->setParameter('status', Appointment::STATUS_PENDING)
            ->setParameter('before', $before)
@@ -0,0 +1,135 @@
+<?php
+
+namespace App\Appointment\Security;
+
+use App\Appointment\Entity\Appointment;
+use App\Auth\Entity\User;
+use App\Auth\Repository\UserActiveContextRepository;
+use App\Clinic\Repository\ClinicRepository;
+use App\Clinic\Security\ClinicDoctorPermissionChecker;
+use App\Doctor\Repository\DoctorRepository;
+use App\Secretary\Repository\DoctorSecretaryRepository;
+use App\Secretary\Security\SecretaryPermissionChecker;
+
+/**
+ * تنها تصمیم‌گیرندهٔ دسترسی روی «یک نوبت مشخص».
+ *
+ * پیش از این، مسیرهای تک‌نوبت فقط بیمار، پزشکِ مالک و ادمین را می‌شناختند؛ نوبتی که
+ * کاربر کلینیک از مسیر /my/appointment می‌ساخت، روی مشاهده و ویرایش ۴۰۳ می‌گرفت.
+ * محیط نوبت با appointment.clinic بیان می‌شود (NULL یعنی مطب شخصی) و همان مبنای
+ * تصمیم است — نه نقش کاربر.
+ *
+ * اکشن‌ها از همان واژگان ClinicDoctorPermission/DoctorSecretary گرفته شده‌اند تا
+ * «پایان همکاری» فقط یک منبع حقیقت داشته باشد: active=false در همان رکوردها.
+ */
+class AppointmentAccessChecker
+{
+    public const ACTION_VIEW          = 'view';
+    public const ACTION_UPDATE_STATUS = 'update_status';
+    public const ACTION_CANCEL        = 'cancel';
+
+    private const RESOURCE = 'appointments';
+
+    public function __construct(
+        private readonly ClinicDoctorPermissionChecker $clinicPermissions,
+        private readonly SecretaryPermissionChecker    $secretaryPermissions,
+        private readonly DoctorSecretaryRepository     $secretaryRepo,
+        private readonly UserActiveContextRepository   $contextRepo,
+        private readonly ClinicRepository              $clinicRepo,
+        private readonly DoctorRepository              $doctorRepo,
+    ) {}
+
+    public function canView(Appointment $appointment, User $user): bool
+    {
+        return $this->can($appointment, $user, self::ACTION_VIEW);
+    }
+
+    /** مجوز تغییر نوبت: ویرایش، جابه‌جایی، رزرو، جایگزینی و تغییر وضعیت. */
+    public function canManage(Appointment $appointment, User $user): bool
+    {
+        return $this->can($appointment, $user, self::ACTION_UPDATE_STATUS);
+    }
+
+    public function canCancel(Appointment $appointment, User $user): bool
+    {
+        return $this->can($appointment, $user, self::ACTION_CANCEL);
+    }
+
+    public function can(Appointment $appointment, User $user, string $action): bool
+    {
+        if ($user->hasRole('ROLE_ADMIN')) {
+            return true;
+        }
+
+        if ($appointment->getDoctor()->getUser()->getId() === $user->getId()) {
+            return true;
+        }
+
+        // بیمار نوبت خودش را می‌بیند و لغو می‌کند، ولی جابه‌جا/ویرایش نمی‌کند.
+        if ($appointment->getUser()->getId() === $user->getId()) {
+            return $action === self::ACTION_VIEW || $action === self::ACTION_CANCEL;
+        }
+
+        $clinic = $appointment->getClinic();
+        if ($clinic !== null && $this->clinicPermissions->can($user, $clinic, self::RESOURCE, $action)) {
+            return true;
+        }
+
+        return $this->secretaryCan($appointment, $user, $action);
+    }
+
+    /**
+     * کلینیکی که این کاربر در آن اجازهٔ دیدن نوبت‌های این پزشک را دارد، یا null.
+     * برای لیست‌هایی که باید به یک محیط محدود شوند (نه تک‌نوبت).
+     */
+    public function viewableClinicFor(User $user, \App\Doctor\Entity\Doctor $doctor): ?\App\Clinic\Entity\Clinic
+    {
+        $dbUuid = $this->contextRepo->findByUser($user)?->getDbUuid();
+        $clinic = $dbUuid !== null ? $this->clinicRepo->findByUuid($dbUuid) : null;
+
+        if ($clinic === null) {
+            $clinic = $this->clinicRepo->findByUser($user);
+        }
+
+        if ($clinic === null || !$clinic->hasDoctor($doctor)) {
+            return null;
+        }
+
+        return $this->clinicPermissions->can($user, $clinic, self::RESOURCE, self::ACTION_VIEW)
+            ? $clinic
+            : null;
+    }
+
+    /**
+     * منشی در محیط فعالِ خودش. در محیط کلینیک، نوبت باید هم متعلق به همان کلینیک
+     * باشد و هم پزشکش جزو پزشکان تخصیص‌یافته به این منشی — عضویت در کلینیک به‌تنهایی
+     * یعنی منشیِ یک پزشک بتواند نوبت پزشک دیگری را دست‌کاری کند.
+     */
+    private function secretaryCan(Appointment $appointment, User $user, string $action): bool
+    {
+        $dbUuid = $this->contextRepo->findByUser($user)?->getDbUuid();
+        if ($dbUuid === null) {
+            return false;
+        }
+
+        $clinic = $this->clinicRepo->findByUuid($dbUuid);
+        if ($clinic !== null) {
+            if ($appointment->getClinic()?->getId() !== $clinic->getId()) {
+                return false;
+            }
+
+            $relation = $this->secretaryRepo->findActiveClinicRow($user, $clinic, $appointment->getDoctor());
+
+            return $relation !== null && $this->secretaryPermissions->can($relation, self::RESOURCE, $action);
+        }
+
+        $doctor = $this->doctorRepo->findByUuid($dbUuid);
+        if ($doctor === null || $doctor->getId() !== $appointment->getDoctor()->getId()) {
+            return false;
+        }
+
+        $relation = $this->secretaryRepo->findActiveBySecretaryForDoctor($user, $doctor);
+
+        return $relation !== null && $this->secretaryPermissions->can($relation, self::RESOURCE, $action);
+    }
+}
@@ -3,7 +3,13 @@
 namespace App\Appointment\Service;

 use App\Appointment\Entity\Appointment;
+use App\Appointment\Repository\AppointmentRepository;
+use App\Auth\Entity\User;
+use App\Patient\Entity\PatientSession;
 use App\Patient\Service\PatientService;
+use App\Shared\Constant\ErrorCodes;
+use App\Shared\Exception\AppException;
+use Doctrine\ORM\EntityManagerInterface;
 use Psr\Log\LoggerInterface;

 /**
@@ -16,8 +22,10 @@ use Psr\Log\LoggerInterface;
 class AppointmentConfirmationService
 {
    public function __construct(
-        private readonly PatientService  $patientService,
-        private readonly LoggerInterface $logger,
+        private readonly PatientService        $patientService,
+        private readonly AppointmentRepository $appointmentRepo,
+        private readonly EntityManagerInterface $em,
+        private readonly LoggerInterface       $logger,
    ) {}

    /**
@@ -27,20 +35,66 @@ class AppointmentConfirmationService
     * رزرو شده و پول پرداخت شده است؛ پرونده را می‌شود با
     * `app:appointment:backfill-sessions` ساخت، ولی رول‌بکِ پرداخت برگشت‌ناپذیر است.
     */
-    public function onConfirmed(Appointment $appointment): void
+    public function onConfirmed(Appointment $appointment): ?PatientSession
    {
        // نوبت رزروِ روز-محور اسلات و ساعت مشخص ندارد؛ مراجعهٔ زمان‌دار برایش معنا ندارد.
        if ($appointment->isReserve()) {
-            return;
+            return null;
        }

        try {
-            $this->patientService->autoCreateOnAppointmentConfirm($appointment);
+            return $this->patientService->autoCreateOnAppointmentConfirm($appointment);
        } catch (\Throwable $e) {
            $this->logger->error('Auto-creating the patient record on confirm failed', [
                'appointment_uuid' => $appointment->getUuid(),
                'exception'        => $e,
            ]);
+
+            return null;
        }
    }
+
+    /**
+     * قطعی‌کردنِ صریح از پنل: انتقال وضعیت، ثبت پرونده/مراجعه و ثبت پرداخت‌ها — همه
+     * در یک تراکنش. برخلاف onConfirmed اینجا شکست خاموش نمی‌ماند: کاربر روبه‌روی
+     * مودالی ایستاده که مبلغ نشان داده و منتظر تأیید است؛ «قطعی شد ولی پول ثبت نشد»
+     * بدترین خروجیِ ممکن است.
+     *
+     * @param  array<int, array{method: string, amount_rials: int}> $payments
+     * @return PatientSession|null null یعنی این tenant قابلیت پرونده را ندارد
+     *                             (فقط وقتی مجاز است که پرداختی هم ارسال نشده باشد)
+     */
+    public function confirmWithPayments(
+        Appointment $appointment,
+        int $expectedVersion,
+        array $payments,
+        User $actor,
+    ): ?PatientSession {
+        return $this->em->wrapInTransaction(function () use ($appointment, $expectedVersion, $payments, $actor) {
+            $appointment->transitionTo(Appointment::STATUS_CONFIRMED);
+            $this->appointmentRepo->saveWithLock($appointment, $expectedVersion);
+
+            $session = $this->patientService->autoCreateOnAppointmentConfirm($appointment);
+
+            if ($session === null) {
+                if ($payments !== []) {
+                    throw new AppException(ErrorCodes::ERR_SUBSCRIPTION_REQUIRED, null, 403);
+                }
+
+                return null;
+            }
+
+            foreach ($payments as $payment) {
+                $this->patientService->addSessionPayment(
+                    $session,
+                    $payment['method'],
+                    $payment['amount_rials'],
+                    null,
+                    $actor,
+                );
+            }
+
+            return $session;
+        });
+    }
 }