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/Repository/AppointmentRepository.php

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