hamed/clinicpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f144401dd324868dd65ce6403e1b2ec97d23039e
clinicpro/docs/api/resource-calendar.md
T
hamedandClaude Opus 5 f144401dd3 feat(holidays): one official calendar, inherited everywhere 
The holiday model was already right — national holidays global, a per-tenant
override in both directions, per-doctor and per-resource exceptions — but
nothing could create a national holiday. The only writer was an import
command, so the calendar the whole product inherits from had no owner.

Three admin-only routes give it one. POST upserts, because `date` is unique
and re-sending a day should rename it rather than surface a raw database
error; PATCH takes only the title, because moving a date means a different
holiday. The system admin has no work environment, so the list endpoint now
returns the calendar with an empty `overrides` for that role instead of the
403 `pair()` would raise — the person who maintains the calendar has to be
able to read it.

Both holiday tabs — the doctor's and the resource's — now open with the
official calendar above their own exceptions, from one shared card rather
than two copies that would drift. Each row can be opted out of with a single
click, which is the existing holiday-override endpoint.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-02 15:39:48 +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 برایش خالی برمی‌گردد و فقط تقویم را می‌بیند.

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
Reference in New Issue View Git Blame Copy Permalink