clinicpro/docs/api/resource-calendar.md

Resource Calendar API — تقویم منبع، استثنا و تعطیلات

Base: /api/v1 · Auth: JWT · مجوز: appointment_settings مکمل resource.md — منبع آنجا ساخته می‌شود، تقویمش اینجا.

---

کسرِ لایه‌ها

بند ۹ مستند ساعت آزاد را از کسر هفت لایه می‌سازد. آنچه این بخش می‌دهد چهار لایهٔ اول است:

ساعت کاری شعبه  ∩  شیفت منبع  −  تعطیلات رسمی  −  استثناهای منبع

نوبت‌های ثبت‌شده و رزروهای موقت اینجا کسر نمی‌شوند. خروجی این اندپوینت «وقت قابل رزرو» نیست؛ تقاطع چند منبع و کسر اشغال کارِ تسک‌های بعدی است. متد داخلی‌اش عمداً rawAvailability() نام دارد.

مسیر اسلاتیِ موجود (SlotCalculatorService، WeeklySchedule، DateOverride، Holiday) در این فاز دست‌نخورده است؛ این یک مسیر موازی روی منبع است.

---

GET /api/v1/resource/{uuid}/calendar

{
  "success": true,
  "data": {
    "resource_uuid": "38bdd1e9-d982-4cef-9419-3d42ee6b85f2",
    "timezone": "Asia/Tehran",
    "defined": true,
    "days": {
      "0": [{ "sequence": 0, "start_minute": 540, "end_minute": 1020, "start_time": "09:00", "end_time": "17:00", "active": true }],
      "1": [{ "sequence": 0, "start_minute": 540, "end_minute": 1020, "start_time": "09:00", "end_time": "17:00", "active": true }],
      "2": [], "3": [], "4": [], "5": [], "6": []
    }
  }
}

days همیشه شیء با هر هفت کلید "0".."6" است؛ ۰ = شنبه. timezone از شعبهٔ منبع می‌آید و مبنای «روز» در محاسبهٔ ساعت آزاد است.

PUT /api/v1/resource/{uuid}/calendar

جایگزینی کامل هفت روز — روزی که نفرستید خالی می‌شود. قواعد و خطاها دقیقاً مثل ساعت کاری شعبه (branch.md): دقیقه از نیمه‌شب 0..1440، end > start، بدون هم‌پوشانی در یک روز، sequence را سرور می‌دهد، و اعتبارسنجی کامل پیش از هر حذفی.

{ "days": { "0": [{ "start_minute": 540, "end_minute": 1020 }] } }

---

استثناها — مرخصی، غیبت، سرویس، تعطیلی موردی

چهار نوع، یک جدول: هر چهار «یک بازهٔ کسرشونده از تقویم منبع»اند و جدا کردنشان یعنی چهار کوئری در هر محاسبه به‌جای یکی.

type	برچسب
leave	مرخصی
absence	غیبت
maintenance	سرویس دوره‌ای
closure	تعطیلی موردی

زمان‌ها timestamp مطلقاند، نه دقیقه‌از-نیمه‌شب: یک مرخصی می‌تواند چندروزه باشد.

GET /api/v1/resource/{uuid}/exceptions?from&to

بازه اختیاری است؛ استثناهایی که با آن تداخل دارند برمی‌گردند، نه فقط آن‌هایی که کاملاً درونش‌اند — وگرنه مرخصیِ سه‌روزه‌ای که وسطش این بازه است دیده نمی‌شد.

POST /api/v1/resource/{uuid}/exception

۲۰۱ (خروجی واقعی):

{
  "success": true,
  "data": {
    "uuid": "b387529b-c27c-4c6c-ab6c-047167ae51da",
    "resource_uuid": "38bdd1e9-d982-4cef-9419-3d42ee6b85f2",
    "resource_name": "لیزر آلکساندرایت ۱",
    "type": "maintenance",
    "type_label": "سرویس دوره‌ای",
    "starts_at": 1785509280,
    "ends_at": 1785512880,
    "reason": "سرویس دوره‌ای",
    "created_at": 1785422880,
    "updated_at": 1785422880
  }
}

۴۲۲: ends_at <= starts_at (field ends_at) · نوع ناشناخته (field type) · نبودِ starts_at/ends_at. ۴۰۴: منبع یا استثنای محیط دیگر.

PATCH / DELETE /api/v1/resource-exception/{uuid}

دو استثنای هم‌پوشان مجازند و در محاسبه اتحادشان گرفته می‌شود؛ خطا نیست.

---

GET /api/v1/resource/{uuid}/availability?from&to

from و to هر دو timestamp‌اند و هر دو روز شاملاند. سقف بازه ۹۲ روز است.

۲۰۰ (خروجی واقعی برای دو روز):

{
  "success": true,
  "data": {
    "resource_uuid": "38bdd1e9-d982-4cef-9419-3d42ee6b85f2",
    "timezone": "Asia/Tehran",
    "days": [
      { "date": 1785529800, "day_of_week": 0, "intervals": [{ "start": 1785562200, "end": 1785591000 }], "total_minutes": 480, "reasons": [] },
      { "date": 1785616200, "day_of_week": 1, "intervals": [{ "start": 1785648600, "end": 1785677400 }], "total_minutes": 480, "reasons": [] }
    ]
  }
}

reasons — چرا روز خالی است

بدون این، پاسخِ خالی از یک باگ قابل تشخیص نیست.

کد	یعنی
no_shift	منبع آن روز شیفتی ندارد
branch_closed	شعبه آن روز ساعت کاری ندارد
outside_branch_hours	شیفت هست ولی تقاطعش با ساعت شعبه خالی شد
national_holiday	تعطیل رسمی کشور
tenant_holiday	این محیط آن روز را تعطیل اعلام کرده
exception	مرخصی/غیبت/سرویس بخشی یا تمام روز را بریده
resource_inactive / branch_inactive	منبع یا شعبه غیرفعال است

۴۲۲: نبودِ from/to · to < from · بازهٔ بیش از ۹۲ روز (خروجی واقعی):

{"success":false,"data":null,"errors":[{"code":"ERR_VALIDATION_001","message":"بازهٔ درخواستی حداکثر 92 روز است","field":"to"}]}

دو قرارداد مهم

شعبهٔ بدون ساعت کاری = «تعریف‌نشده»، نه «بسته». شیفت منبع بی‌قید اعمال می‌شود تا دادهٔ موجود دقیقاً مثل امروز کار کند. این با branch_closed — که یعنی ساعت تعریف شده ولی آن روز خالی است — فرق دارد.

شیفت بیرون از ساعت شعبه رد نمی‌شود، تقاطع گرفته می‌شود. شیفت ۹–۱۷ روی شعبه‌ای که ۱۰–۱۲ باز است، ۱۲۰ دقیقه می‌دهد.

---

تعطیلات رسمی

GET /api/v1/national-holidays?year=1405

تعطیلات سراسریاند و به محیط تعلق ندارند؛ امروز هر پزشک باید ۱۳ فروردین را دستی ثبت کند، که هم تکرار است و هم منبع خطا.

{
  "success": true,
  "data": {
    "year": 1405,
    "holidays": [
      { "uuid": "f1af4e18-…", "date": 1774040400, "jalali_date": "1405-01-01", "jalali_year": 1405, "title": "نوروز", "overridden_working": null }
    ],
    "overrides": []
  }
}

overridden_working کنار خودِ تعطیلی می‌آید تا UI مجبور نباشد دو فهرست را تطبیق دهد: null یعنی این محیط استثنایی ندارد، true یعنی آن روز باز است.

POST /api/v1/holiday-overrides

فیلد	نوع	توضیح
date	int	هر لحظه از آن روز؛ سرور به نیمه‌شب تهران گرد می‌کند
is_working	bool	جهت استثنا
note	string|null

دو جهت دارد و هر دو لازم‌اند:

• true → کلینیکی که آن روزِ تعطیلِ رسمی باز است
• false → روزی که رسمی نیست ولی این محیط بسته است

جهت دوم با «استثنای منبع» فرق دارد: آن روی یک منبع است و این روی کل محیط.

فرستادن دوباره روی همان تاریخ، همان ردیف را عوض می‌کند (کلید یکتا per محیط و تاریخ).

DELETE /api/v1/holiday-override/{uuid}

---

app:holiday:import

ddev exec php bin/console app:holiday:import --year=1405                 # dry-run
ddev exec php bin/console app:holiday:import --year=1405 --force
ddev exec php bin/console app:holiday:import --year=1405 --force --replace
ddev exec php bin/console app:holiday:import --year=1405 --force --extra=10/12/عید فطر

مناسبت‌های ثابتِ شمسی درون خودِ دستورند چون هر سال تکرار می‌شوند. مناسبت‌های قمری (عید فطر، عاشورا، …) هر سال جابه‌جا می‌شوند و عمداً نیامده‌اند: حدس زدنشان بدتر از نداشتنشان است — با --extra یا از پنل اضافه می‌شوند.

⚠️ --replace کِی لازم است: ثبت روی date کلید می‌خورد، پس ردیفی که با تاریخ غلط نوشته شده هرگز خودش را تصحیح نمی‌کند؛ اجرای دوباره ردیف درست را کنارش می‌سازد و غلط سرِ جایش می‌ماند. دقیقاً همین پس از اصلاح باگ تبدیل شمسی پیش آمد.

باگ تبدیل شمسی: JalaliDateService::gregorianToJalali() غلط بود و برای ۲۰۲۶-۰۷-۳۰ مقدار [3006, 7, 3] می‌داد به‌جای [1405, 5, 8]. jalaliYear()، jalaliMonthRange() و jalaliYearRange() — که گزارش‌های نمایندگی رویشان ساخته شده‌اند — همه همین را به ارث می‌بردند. حالا هر دو تبدیل از IntlDateFormatter می‌آیند (همان چیزی که formatDateTime() همین کلاس از قبل درست استفاده می‌کرد) و tests/Representation/JalaliDateServiceTest.php قفلش می‌کند.

---

طبقه‌بندی محیط

جدول	وضعیت
resource_calendars	AGGREGATE_CHILDREN — ریشه ClinicResource
resource_exceptions	جفت محیط (uuidش از request می‌آید)
tenant_holiday_overrides	جفت محیط
national_holidays	GlobalTables::ENTITIES — کشوری است، نه محیطی

---

تست‌ها

ddev exec php bin/phpunit tests/Resource/ResourceAvailabilityTest.php   # ۱۳ تست
ddev exec php bin/phpunit tests/Representation/JalaliDateServiceTest.php
npx vitest run assets/admin/pages/ResourceCalendarPage.test.tsx