feat: enhance resource calendar validation and UI

- Implement real-time validation for overlapping shifts in the ResourceWorkingHoursPanel.
- Remove the copy shift functionality to simplify the UI and prevent confusion.
- Introduce ResourceExceptionsCard to manage resource exceptions, including leave and maintenance.
- Update ClinicAppointmentSettingsPage to utilize new components and improve tab navigation for resource management.
- Add comprehensive validation tests for resource calendar to ensure overlapping shifts are correctly handled.
- Update API documentation to reflect new validation error messages and rules.

assets/admin/components/resources/ResourceExceptionsPanel.tsx

@@ -1,14 +1,10 @@
-import React, { useId, useMemo, useState } from 'react';
-import { Link } from 'react-router-dom';
-import { XMarkIcon } from '@heroicons/react/24/outline';
-import ConfirmDialog from '../ui/ConfirmDialog';
-import SearchableSelect from '../ui/SearchableSelect';
-import PersianDateInput from '../ui/PersianDateInput';
-import { useResourceAvailability, useResourceExceptions } from '../../hooks/useResourceCalendar';
+import React from 'react';
+import { useResourceAvailability } from '../../hooks/useResourceCalendar';
 import { formatDate, formatNumber } from '../../lib/utils';
 import { DAY_LABELS } from './ResourceWorkingHoursPanel';
 import NationalHolidaysCard from '../holidays/NationalHolidaysCard';
-import type { ResourceAvailability, ResourceException } from '../../types';
+import ResourceExceptionsCard from './ResourceExceptionsCard';
+import type { ResourceAvailability } from '../../types';
 
 /** چرا یک روز خالی است — بدون ترجمه، پاسخ خام سرور به کاربر نشان داده می‌شد. */
 const REASON_LABELS: Record<string, string> = {
@@ -20,13 +16,6 @@ const REASON_LABELS: Record<string, string> = {
   address_inactive: 'محل نوبت‌دهی غیرفعال است',
 };
 
-const EXCEPTION_TYPES = [
-  { value: 'leave', label: 'مرخصی' },
-  { value: 'absence', label: 'غیبت' },
-  { value: 'maintenance', label: 'سرویس دوره‌ای' },
-  { value: 'closure', label: 'تعطیلی موردی' },
-];
-
 /** نیمه‌شبِ امروز به‌صورت timestamp ثانیه‌ای. */
 function todayMidnight(): number {
   const d = new Date();
@@ -35,21 +24,16 @@ function todayMidnight(): number {
 }
 
 /**
- * تعطیلات و استثناهای یک منبع، کنار پیش‌نمایش دو هفتهٔ ساعت آزاد.
+ * تقویمِ استثناهای یک منبع: تعطیلات رسمی، مرخصی و سرویس، و پیش‌نمایش دو هفته.
  *
- * پیش‌نمایش عمداً «ساعت آزاد» نامیده نشده بلکه «خام» است: نوبت‌های ثبت‌شده در آن
- * کسر نشده‌اند و اشتباه گرفتنش با «وقت قابل رزرو» به بیش‌رزروی می‌انجامد.
- *
- * دو ستون، نه `auto-fit`: تعطیلات و استثنا هر دو ورودی‌اند و کنار هم می‌مانند،
- * پیش‌نمایش خروجی است و ستون خودش را می‌گیرد.
+ * این ترکیب مخصوص صفحهٔ جزئیات منبع است، جایی که کل صفحه دربارهٔ همان یک منبع است
+ * و پیش‌نمایش پاسخِ «بعد از این تنظیمات، چه ساعتی باز می‌ماند؟» را می‌دهد. صفحهٔ
+ * تنظیمات نوبت‌دهی همان دو کارت را بدون پیش‌نمایش و به‌صورت تب می‌چیند.
  */
 export default function ResourceExceptionsPanel({ resourceUuid, canUpdate }: {
   resourceUuid?: string;
   canUpdate: boolean;
 }) {
-  const { exceptions, create, remove } = useResourceExceptions(resourceUuid);
-  const [toDelete, setToDelete] = useState<ResourceException | null>(null);
-
   const previewFrom = todayMidnight();
   const previewTo = previewFrom + 13 * 86400;
   const { availability } = useResourceAvailability(resourceUuid, previewFrom, previewTo);
@@ -58,27 +42,10 @@ export default function ResourceExceptionsPanel({ resourceUuid, canUpdate }: {
     <div className="wh-two-col">
       <div style={{ display: 'grid', gap: 'var(--gap)' }}>
         <NationalHolidaysCard canUpdate={canUpdate} />
-        <ExceptionsCard
-          exceptions={exceptions}
-          canUpdate={canUpdate}
-          saving={create.isPending}
-          onCreate={(payload) => create.mutate(payload)}
-          onDelete={setToDelete}
-        />
+        <ResourceExceptionsCard resourceUuid={resourceUuid} canUpdate={canUpdate} />
       </div>
 
       <PreviewCard availability={availability} />
-
-      <ConfirmDialog
-        open={!!toDelete}
-        title="حذف استثنا"
-        message={`آیا از حذف «${toDelete?.type_label}» مطمئن هستید؟`}
-        confirmLabel="حذف"
-        danger
-        loading={remove.isPending}
-        onConfirm={() => toDelete && remove.mutate(toDelete.uuid, { onSuccess: () => setToDelete(null) })}
-        onCancel={() => setToDelete(null)}
-      />
     </div>
   );
 }
@@ -137,155 +104,3 @@ function PreviewCard({ availability }: { availability?: ResourceAvailability })
     </div>
   );
 }
-
-function ExceptionsCard({
-  exceptions, canUpdate, saving, onCreate, onDelete,
-}: {
-  exceptions: ResourceException[];
-  canUpdate: boolean;
-  saving: boolean;
-  onCreate: (payload: { type: string; starts_at: number; ends_at: number; reason?: string | null }) => void;
-  onDelete: (e: ResourceException) => void;
-}) {
-  const [type, setType] = useState<string>('leave');
-  const [startDate, setStartDate] = useState('');
-  const [endDate, setEndDate] = useState('');
-  const [reason, setReason] = useState('');
-
-  // id یکتا لازم است: این کارت در صفحهٔ منبع و صفحهٔ تنظیمات نوبت‌دهی هر دو رندر می‌شود.
-  const uid = useId();
-
-  const toTimestamp = (value: string): number | null => {
-    if (value === '') return null;
-    const ms = new Date(`${value}T00:00:00`).getTime();
-    return Number.isNaN(ms) ? null : Math.floor(ms / 1000);
-  };
-
-  const start = toTimestamp(startDate);
-  const end = toTimestamp(endDate);
-  // پایان روزِ انتخاب‌شده، نه آغازش: مرخصیِ «تا سه‌شنبه» شامل خودِ سه‌شنبه است.
-  const endExclusive = end === null ? null : end + 86400;
-  const invalid = start === null || endExclusive === null || endExclusive <= start;
-
-  const typeLabel = useMemo(
-    () => EXCEPTION_TYPES.find((t) => t.value === type)?.label ?? '',
-    [type],
-  );
-
-  return (
-    <div className="card card-pad">
-      <h2 style={{ fontSize: 16, fontWeight: 700, color: 'var(--text)', marginBottom: 12 }}>
-        مرخصی و سرویس
-      </h2>
-
-      {exceptions.length === 0 ? (
-        <p style={{ fontSize: 13, color: 'var(--text-3)', margin: '0 0 14px' }}>
-          استثنایی ثبت نشده است.
-        </p>
-      ) : (
-        <div style={{ display: 'grid', gap: 8, marginBottom: 16 }}>
-          {exceptions.map((e) => (
-            <div
-              key={e.uuid}
-              style={{
-                display: 'flex', alignItems: 'center', gap: 8, fontSize: 13,
-                padding: '8px 10px', borderRadius: 'var(--r-sm)', background: 'var(--surface-2)',
-              }}
-            >
-              <span className="badge amber" style={{ fontSize: 11 }}>{e.type_label}</span>
-              <span style={{ flex: 1, color: 'var(--text-2)', minWidth: 0 }}>
-                {formatDate(e.starts_at)} تا {formatDate(e.ends_at)}
-                {e.reason ? ` · ${e.reason}` : ''}
-              </span>
-              {canUpdate && (
-                <button
-                  type="button"
-                  className="mini-btn danger"
-                  onClick={() => onDelete(e)}
-                  aria-label={`حذف ${e.type_label} از ${formatDate(e.starts_at)}`}
-                >
-                  <XMarkIcon style={{ width: 16 }} />
-                </button>
-              )}
-            </div>
-          ))}
-        </div>
-      )}
-
-      {canUpdate ? (
-        <div style={{ display: 'grid', gap: 12 }}>
-          <div className="field-block">
-            <label id={`${uid}-type-label`} htmlFor={`${uid}-type`}>نوع استثنا</label>
-            <SearchableSelect
-              inputId={`${uid}-type`}
-              ariaLabelledBy={`${uid}-type-label`}
-              options={EXCEPTION_TYPES}
-              value={type}
-              onChange={(v) => setType(v ? String(v) : 'leave')}
-              placeholder="نوع استثنا"
-              height={40}
-            />
-          </div>
-
-          {/* تقویم شمسی، نه `input type=date` میلادی: اپراتور تاریخ را شمسی می‌گوید و
-              ترجمهٔ ذهنی همان‌جایی است که استثنا یک روز جابه‌جا ثبت می‌شود. */}
-          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
-            <div className="field-block">
-              <label>از تاریخ</label>
-              <PersianDateInput
-                value={startDate}
-                onChange={setStartDate}
-                placeholder="از تاریخ"
-                ariaLabel={`تاریخ شروع ${typeLabel}`}
-              />
-            </div>
-            <div className="field-block">
-              <label>تا تاریخ</label>
-              <PersianDateInput
-                value={endDate}
-                onChange={setEndDate}
-                placeholder="تا تاریخ"
-                ariaLabel={`تاریخ پایان ${typeLabel}`}
-              />
-            </div>
-          </div>
-
-          <div className="field-block">
-            <label htmlFor={`${uid}-reason`}>توضیح <span className="opt">(اختیاری)</span></label>
-            <label className="field">
-              <input
-                id={`${uid}-reason`}
-                value={reason}
-                onChange={(e) => setReason(e.target.value)}
-                placeholder="مثلاً سرویس سالانهٔ دستگاه"
-              />
-            </label>
-          </div>
-
-          <button
-            type="button"
-            className="btn primary"
-            disabled={saving || invalid}
-            onClick={() => {
-              onCreate({
-                type,
-                starts_at: start!,
-                ends_at: endExclusive!,
-                reason: reason.trim() === '' ? null : reason.trim(),
-              });
-              setStartDate('');
-              setEndDate('');
-              setReason('');
-            }}
-          >
-            {saving ? 'در حال ثبت...' : 'ثبت استثنا'}
-          </button>
-        </div>
-      ) : (
-        <p style={{ fontSize: 12.5, color: 'var(--text-3)', margin: 0 }}>
-          برای ثبت یا حذف استثنا مجوز ویرایش تنظیمات نوبت‌دهی لازم است.
-        </p>
-      )}
-    </div>
-  );
-}