Files

T

hamedandClaude Opus 5 bd4347f9c5 feat(admin): a page for the official holiday calendar

The three admin endpoints shipped without anywhere to call them from, so the
person who is supposed to maintain the national calendar could only do it
with curl or a console command. That is not "the director can register the
year's holidays".

/admin/national-holidays is ROLE_ADMIN only and sits under the System group
in the admin nav. The year lives in the query string, so back and refresh
return to the year being edited.

Editing takes only the title: `date` is the unique key, so moving a holiday
is really deleting one and creating another, and the form says so rather than
silently creating a duplicate. The date field is the shared Jalali picker,
which speaks Gregorian, so the page converts before POSTing the jalali_date
the API expects — and shows the converted value under the field so the user
can see what will be stored.

Deleting warns that the day leaves every clinic's calendar, because it does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-02 17:14:23 +03:30

12 KiB

Raw Blame History

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

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

پنل: این اندپوینت‌ها در تب‌های «ساعات کاری» و «تعطیلات و استثنا»ی صفحهٔ /admin/resources/{uuid} مصرف می‌شوند. مسیر قدیمی /admin/resources/{uuid}/calendar با redirect به ?tab=hours می‌رود.

کسرِ لایه‌ها

بند ۹ مستند ساعت آزاد را از کسر هفت لایه می‌سازد. آنچه این بخش می‌دهد سه لایهٔ اول است (لایهٔ «ساعت کاری شعبه» با حذف دامنهٔ شعبه برداشته شد — تنها مرجع ساعت، شیفت خودِ منبع است):

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

نوبت‌های ثبت‌شده و رزروهای موقت اینجا کسر نمی‌شوند. خروجی این اندپوینت «وقت قابل رزرو» نیست؛ تقاطع چند منبع و کسر اشغال کارِ تسک‌های بعدی است. متد داخلی‌اش عمداً 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`

جایگزینی کامل هفت روز — روزی که نفرستید خالی می‌شود. قواعد و خطاها دقیقاً مثل ساعت کاری: دقیقه از نیمه‌شب 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`	منبع آن روز شیفتی ندارد
`national_holiday`	تعطیل رسمی کشور
`tenant_holiday`	این محیط آن روز را تعطیل اعلام کرده
`exception`	مرخصی/غیبت/سرویس بخشی یا تمام روز را بریده
`resource_inactive` / `address_inactive`	منبع یا محل نوبت‌دهی غیرفعال است

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

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

یک قرارداد مهم

تنها مرجع ساعت کاری، شیفت خودِ منبع است. تا پیش از حذف دامنهٔ شعبه، این شیفت با ساعت کاری شعبه تقاطع می‌گرفت و دلیل‌های branch_closed و outside_branch_hours را می‌ساخت؛ آن لایه و آن دو دلیل دیگر وجود ندارند.

تعطیلات رسمی

`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 یعنی آن روز باز است.

مدیر سیستم — ساخت و ویرایش تقویم رسمی

ROLE_ADMIN فقط. تعطیل رسمی به هیچ محیطی تعلق ندارد، پس ساختنش هم کارِ هیچ کلینیکی نیست؛ کلینیکی که آن روز باز است با holiday-overrides استثنا می‌زند.

متد	مسیر	بدنه
POST	`/api/v1/admin/national-holidays`	`{ "jalali_date": "1405-01-13", "title": "سیزده‌بدر" }`
PATCH	`/api/v1/admin/national-holiday/{uuid}`	`{ "title": "…" }`
DELETE	`/api/v1/admin/national-holiday/{uuid}`	—

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

{
  "success": true,
  "data": {
    "uuid": "…", "date": 1774472400, "jalali_date": "1405-01-13",
    "jalali_year": 1405, "title": "سیزده‌بدر"
  }
}

POST روی روزی که از قبل هست upsert است و عنوان را عوض می‌کند — date کلید یکتا دارد و خطای خام دیتابیس رفتار درستی نیست. PATCH فقط عنوان را می‌گیرد: جابه‌جا کردن تاریخ یعنی یک تعطیلِ دیگر، پس حذف و ثبت دوباره.

۴۰۳: هر نقشی جز ادمین (تأیید زنده: کاربر کلینیک روی همین مسیر ۴۰۳ گرفت). ۴۲۲: jalali_date بدقالب · نبودِ title. ۴۰۴: uuid ناشناخته.

GET /api/v1/national-holidays برای ادمین هم کار می‌کند: او محیط کاری ندارد، پس بخش overrides برایش خالی برمی‌گردد و فقط تقویم را می‌بیند.

پنل: صفحهٔ /admin/national-holidays (منو ← سیستم ← تعطیلات رسمی) تنها جای ساخت و حذف است و فقط ROLE_ADMIN می‌بیندش. /admin/holidays مالِ محیط است و آنجا فقط استثنا زده می‌شود، نه خودِ تعطیلی.

`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

12 KiB Raw Blame History Unescape Escape

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

کسرِ لایه‌ها

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

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

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

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

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

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

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

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