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>

docs/api/patient.md

@@ -5,7 +5,46 @@
 Patient records track patients per entity (doctor or clinic). Each record holds multiple sessions (visits). Access requires an active subscription with the `patient_records` feature.
 
 **Base path:** `/api/v1`  
-**Auth:** Bearer JWT (doctor, clinic, or secretary with `appointments.view` permission required)
+**Auth:** Bearer JWT (doctor, clinic, or secretary)
+
+---
+
+## Record access model
+
+Every endpoint in this file resolves the caller's environment through
+`App\Patient\Security\PatientRecordScopeResolver`. The **active context**
+(`UserActiveContext`, set by `POST /api/v1/auth/switch-context`) decides it — not the role
+alone, because a doctor invited into a clinic has records in both places.
+
+| Caller | Scope | Visible records |
+|---|---|---|
+| Clinic owner | `clinic:<id>` | every record of the clinic |
+| Doctor, active context = a clinic they belong to | `clinic:<id>` | only records of **their own** patients in that clinic |
+| Doctor, otherwise | `doctor:<id>` | their personal-office records only |
+| Secretary, active context = clinic | `clinic:<id>` | records of the doctors assigned to that secretary |
+| Secretary, active context = doctor | `doctor:<id>` | that doctor's records |
+
+**"Their own patients" is derived, not stored.** A clinic record is per-patient
+(`UNIQUE(entity_type, entity_id, user_id)`) and deliberately shared between the clinic's
+doctors — there is no doctor column on it and none should be added. A record counts as a
+member doctor's when the patient has at least one appointment with that doctor **in that
+clinic**. Manually created visits carry no doctor (`PatientSession` has no creator column),
+so they never widen a member doctor's view on their own.
+
+The member-doctor path additionally requires `ClinicDoctorPermission.patients.view`, and a
+clinic secretary requires an active `DoctorSecretary` row. Both refuse when `active = false`,
+so **deactivating a doctor or secretary is the single mechanism that ends their access** —
+the clinic owner keeps everything, and no record is moved or deleted. A doctor whose clinic
+membership was revoked silently falls back to their personal-office scope.
+
+> **Read and write use the same rule.** An active member doctor who can see a record can
+> also manage it (notes, sessions, payments, attachments): the clinic record is shared by
+> design, and per-visit ownership is not modelled, so inventing a write-only restriction on
+> top of it would produce confusing 403s. A clinic owner who wants a read-only doctor
+> revokes `patients.update` for them.
+
+A record outside the caller's scope is reported as `404 ERR_PATIENT_NOT_FOUND` (not 403), so
+the existence of another environment's records is never disclosed.
 
 ---
 
@@ -17,7 +56,10 @@ Patient records track patients per entity (doctor or clinic). Each record holds
 GET /api/v1/patients
 ```
 
-Returns a paginated list of patient records belonging to the authenticated entity.
+Returns a paginated list of patient records belonging to the authenticated entity, already
+narrowed by the [record access model](#record-access-model) — a member doctor or clinic
+secretary receives only their own patients, with `meta.totalRecords` counted over the same
+restriction.
 
 **Query params:**
 
@@ -356,7 +398,11 @@ GET /api/v1/patient/{uuid}/appointments
 نوبت‌های همین بیمار را برمی‌گرداند. برای جلوگیری از نشتِ اطلاعات بین ارائه‌دهنده‌ها، فقط نوبت‌هایی نمایش داده می‌شوند که با پزشک(های) خودِ صاحب پرونده گرفته شده‌اند:
 
 - ارائه‌دهنده‌ی **پزشک**: نوبت‌های بیمار با همان پزشک.
-- ارائه‌دهنده‌ی **کلینیک** (و منشیِ فعالِ کلینیک): نوبت‌های بیمار با پزشکانی که دعوت پذیرفته‌شده (`accepted`) در آن کلینیک دارند.
+- ارائه‌دهنده‌ی **کلینیک** (و منشیِ فعالِ کلینیک): نوبت‌هایی که `appointment.clinic_id` آن‌ها همین کلینیک است.
+
+> شاخهٔ کلینیک قبلاً بر اساس «پزشکانِ دارای دعوتِ پذیرفته‌شده در این کلینیک» کوئری می‌شد؛
+> با پایان همکاری یا غیرفعال شدن پزشک، تاریخچهٔ نوبت‌های همان کلینیک از پرونده ناپدید
+> می‌شد. مبنا حالا خودِ محیطِ ثبت‌شدهٔ نوبت است، که تغییرناپذیر است.
 
 مرتب‌شده بر اساس `starts_at` نزولی. خروجی آرایه‌ی ساده است (بدون صفحه‌بندی).