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>

src/Appointment/Controller/AppointmentController.php

@@ -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));