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>

assets/admin/pages/AppointmentDetailPage.tsx

@@ -11,6 +11,7 @@ import PageHeader from '../components/ui/PageHeader';
 import StatusBadge from '../components/ui/StatusBadge';
 import ConfirmDialog from '../components/ui/ConfirmDialog';
 import SearchableSelect from '../components/ui/SearchableSelect';
+import ConfirmAppointmentModal from '../components/appointments/ConfirmAppointmentModal';
 
 const ALL_STATUSES: { value: AppointmentStatus; label: string }[] = [
   { value: 'pending',             label: 'رزرو شده' },
@@ -50,6 +51,7 @@ export default function AppointmentDetailPage() {
   const navigate = useNavigate();
   const qc = useQueryClient();
   const [cancelOpen, setCancelOpen] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
   const [cancelReason, setCancelReason] = useState('');
   const [newStatus, setNewStatus] = useState('');
 
@@ -68,7 +70,7 @@ export default function AppointmentDetailPage() {
 
   const statusMutation = useMutation({
     mutationFn: (status: string) =>
-      api.patch<ApiResponse<null>>(`/api/v1/appointment/${uuid}/status`, { status }),
+      api.patch<ApiResponse<null>>(`/api/v1/appointment/${uuid}/status`, { status, version: appt?.version }),
     onSuccess: () => {
       toast.success('وضعیت نوبت بروزرسانی شد');
       qc.invalidateQueries({ queryKey: ['appointment', uuid] });
@@ -80,6 +82,7 @@ export default function AppointmentDetailPage() {
   const cancelMutation = useMutation({
     mutationFn: () => api.patch<ApiResponse<null>>(`/api/v1/appointment/${uuid}/status`, {
       status: 'cancelled_by_doctor',
+      version: appt?.version,
       ...(cancelReason.trim() ? { cancel_reason: cancelReason.trim() } : {}),
     }),
     onSuccess: () => {
@@ -94,6 +97,17 @@ export default function AppointmentDetailPage() {
 
   // پاسخ single تودرتو است: { data: { data: {...} } }
   const appt: any = (data?.data as any)?.data ?? data?.data;
+
+  // قطعی‌کردن هزینه و پرداخت دارد؛ از مسیر مودال می‌رود، نه PATCH وضعیت.
+  function applyStatus() {
+    if (!newStatus) return;
+    if (newStatus === 'confirmed') {
+      setConfirmOpen(true);
+      return;
+    }
+    statusMutation.mutate(newStatus);
+  }
+
   // بازگشت به همان روزِ نوبت (نه امروز).
   const day = isoDay(appt?.slot_start);
   const backTo = day ? `/admin/appointments?date=${day}` : '/admin/appointments';
@@ -144,6 +158,15 @@ export default function AppointmentDetailPage() {
               <StatusBadge type="appointment" value={appt.status} />
             </div>
 
+            {appt.status === 'pending' && (
+              <button
+                onClick={() => setConfirmOpen(true)}
+                className="btn primary w-full"
+              >
+                قطعی کردن نوبت
+              </button>
+            )}
+
             <div className="mt-6">
               <label className="cp-label mb-2">تغییر وضعیت:</label>
               <div className="flex gap-2">
@@ -157,7 +180,7 @@ export default function AppointmentDetailPage() {
                   />
                 </div>
                 <button
-                  onClick={() => newStatus && statusMutation.mutate(newStatus)}
+                  onClick={() => applyStatus()}
                   disabled={!newStatus || statusMutation.isPending}
                   className="btn primary sm"
                 >
@@ -233,6 +256,14 @@ export default function AppointmentDetailPage() {
           />
         </div>
       </ConfirmDialog>
+
+      <ConfirmAppointmentModal
+        open={confirmOpen}
+        appointmentUuid={uuid!}
+        appointment={appt}
+        onClose={() => setConfirmOpen(false)}
+        queryKey={['appointment', uuid]}
+      />
     </div>
   );
 }