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/components/appointments/ConfirmAppointmentModal.tsx

@@ -0,0 +1,220 @@
+import { useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { api } from '../../lib/api';
+import type { ApiResponse } from '../../lib/api';
+import { formatRial, rialToToman, tomanToRial } from '../../lib/utils';
+import Modal from '../ui/Modal';
+import PriceInput from '../ui/PriceInput';
+import SearchableSelect from '../ui/SearchableSelect';
+
+/** همان چهار روشِ SessionPayment::METHODS در بک‌اند. */
+const METHOD_OPTIONS = [
+  { value: 'cash', label: 'پرداخت نقدی' },
+  { value: 'pos', label: 'پرداخت از طریق کارت خوان' },
+  { value: 'card', label: 'کارت به کارت' },
+  { value: 'wallet', label: 'پرداخت از طریق کیف پول' },
+];
+
+interface ServiceItem {
+  uuid: string;
+  name: string;
+  price_rials?: number | null;
+}
+
+interface AppointmentLike {
+  uuid: string;
+  version?: number;
+  visit_price_rials?: number | null;
+  service_items?: ServiceItem[] | null;
+  patient_name?: string | null;
+}
+
+interface Props {
+  open: boolean;
+  appointmentUuid: string;
+  /** اگر صفحه از قبل نوبت را دارد، پاس بده تا درخواست اضافه نرود. */
+  appointment?: AppointmentLike | null;
+  onClose: () => void;
+  /** کلید کوئریِ لیستی که بعد از قطعی‌شدن باید invalidate شود. */
+  queryKey?: unknown[];
+}
+
+const rowStyle: React.CSSProperties = {
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  padding: '10px 0',
+  borderBottom: '1px solid var(--border)',
+};
+
+/**
+ * «قطعی کردن نوبت» — هزینه‌های نوبت را نشان می‌دهد، پرداخت کامل یا جزئی می‌گیرد و
+ * نوبت را از «ثبت شده» به «قطعی شده» می‌برد.
+ *
+ * سرور همین یک درخواست را اتمیک انجام می‌دهد: وضعیت + پرونده/مراجعه + پرداخت‌ها.
+ */
+export default function ConfirmAppointmentModal({
+  open,
+  appointmentUuid,
+  appointment,
+  onClose,
+  queryKey,
+}: Props) {
+  const qc = useQueryClient();
+  const [method, setMethod] = useState('cash');
+  const [amountToman, setAmountToman] = useState(0);
+
+  // وقتی صفحه‌ی میزبان نوبت را ندارد (مثل ردیف لیست) خودمان جزئیات را می‌گیریم:
+  // مبلغ ویزیت و قیمت سرویس‌ها فقط در detail هستند.
+  const detailQuery = useQuery({
+    queryKey: ['appointment', appointmentUuid],
+    queryFn: () => api.get<ApiResponse<AppointmentLike>>(`/api/v1/appointment/${appointmentUuid}`),
+    enabled: open && !appointment,
+  });
+
+  const appt: AppointmentLike | null = appointment
+    ?? ((detailQuery.data?.data as any)?.data ?? detailQuery.data?.data ?? null);
+
+  const visitPrice = Number(appt?.visit_price_rials ?? 0);
+  const services = appt?.service_items ?? [];
+  const servicesTotal = useMemo(
+    () => services.reduce((sum, s) => sum + Number(s.price_rials ?? 0), 0),
+    [services],
+  );
+  const total = visitPrice + servicesTotal;
+
+  const amountRials = tomanToRial(amountToman);
+  const remaining = Math.max(0, total - amountRials);
+  const overpaid = amountRials > total;
+
+  const paymentState = amountRials === 0
+    ? 'بدون پرداخت'
+    : remaining === 0
+      ? 'تسویه کامل'
+      : 'پرداخت جزئی';
+
+  const confirmMut = useMutation({
+    mutationFn: () =>
+      api.post<ApiResponse<unknown>>(`/api/v1/appointment/${appointmentUuid}/confirm`, {
+        version: appt?.version,
+        payments: amountRials > 0 ? [{ method, amount_rials: amountRials }] : [],
+      }),
+    onSuccess: () => {
+      toast.success('نوبت قطعی شد');
+      if (queryKey) qc.invalidateQueries({ queryKey });
+      qc.invalidateQueries({ queryKey: ['appointment', appointmentUuid] });
+      qc.invalidateQueries({ queryKey: ['appointment-events', appointmentUuid] });
+      reset();
+      onClose();
+    },
+    onError: (e: any) => toast.error(e?.message || 'قطعی کردن نوبت ناموفق بود'),
+  });
+
+  function reset() {
+    setAmountToman(0);
+    setMethod('cash');
+  }
+
+  function handleClose() {
+    reset();
+    onClose();
+  }
+
+  const loading = detailQuery.isLoading && !appointment;
+
+  return (
+    <Modal
+      open={open}
+      title="قطعی کردن نوبت"
+      size="md"
+      onClose={handleClose}
+      footer={
+        <>
+          <button type="button" className="btn" onClick={handleClose}>
+            انصراف
+          </button>
+          <button
+            type="button"
+            className="btn primary"
+            disabled={loading || overpaid || confirmMut.isPending}
+            onClick={() => confirmMut.mutate()}
+          >
+            {confirmMut.isPending ? 'در حال ثبت…' : 'تأیید و قطعی کردن'}
+          </button>
+        </>
+      }
+    >
+      {loading ? (
+        <p style={{ color: 'var(--text-2)' }}>در حال دریافت اطلاعات نوبت…</p>
+      ) : (
+        <>
+          {appt?.patient_name && (
+            <p style={{ marginBottom: 12, color: 'var(--text-2)' }}>بیمار: {appt.patient_name}</p>
+          )}
+
+          <div style={{ marginBottom: 18 }}>
+            <div style={rowStyle}>
+              <span>ویزیت</span>
+              <strong>{formatRial(visitPrice)}</strong>
+            </div>
+            {services.map((s) => (
+              <div key={s.uuid} style={rowStyle}>
+                <span>{s.name}</span>
+                <strong>{formatRial(Number(s.price_rials ?? 0))}</strong>
+              </div>
+            ))}
+            <div style={{ ...rowStyle, borderBottom: 'none', fontSize: 16 }}>
+              <span>جمع کل</span>
+              <strong>{formatRial(total)}</strong>
+            </div>
+          </div>
+
+          <div className="field" style={{ marginBottom: 12 }}>
+            <label>روش پرداخت</label>
+            <SearchableSelect
+              value={method}
+              onChange={(v) => setMethod(String(v ?? 'cash'))}
+              options={METHOD_OPTIONS}
+              placeholder="روش پرداخت"
+            />
+          </div>
+
+          <div className="field" style={{ marginBottom: 12 }}>
+            <label>مبلغ پرداختی (تومان)</label>
+            <PriceInput value={amountToman} onChange={setAmountToman} suffix="تومان" />
+            <button
+              type="button"
+              className="btn sm"
+              style={{ marginTop: 8 }}
+              onClick={() => setAmountToman(rialToToman(total))}
+            >
+              پرداخت کامل
+            </button>
+          </div>
+
+          {overpaid && (
+            <p style={{ color: 'var(--danger)', marginBottom: 12 }}>
+              مبلغ پرداخت از جمع کل بیشتر است.
+            </p>
+          )}
+
+          <div style={{ background: 'var(--surface-2)', borderRadius: 'var(--r-sm)', padding: 12 }}>
+            <div style={rowStyle}>
+              <span>پرداخت‌شده</span>
+              <strong>{formatRial(Math.min(amountRials, total))}</strong>
+            </div>
+            <div style={rowStyle}>
+              <span>باقی‌مانده</span>
+              <strong>{formatRial(remaining)}</strong>
+            </div>
+            <div style={{ ...rowStyle, borderBottom: 'none' }}>
+              <span>وضعیت پرداخت</span>
+              <strong>{paymentState}</strong>
+            </div>
+          </div>
+        </>
+      )}
+    </Modal>
+  );
+}