hamedandClaude Opus 5
dd284ec622
Branches and rooms are not part of the resource-first product: a room is a
resource like any other, and the only thing the branch pages still managed —
opening hours — duplicated the resource's own shift.
What could not go is the address. Every appointment carries address_id (75 of
75 rows), the public booking site reads /clinic-pro/doctor-address/{id}, and a
resource derives its tenant pair from the address it belongs to. So
DoctorAddress stays as an invisible anchor with no page and no menu entry, and
GET /api/v1/addresses replaces GET /api/v1/branches for the forms that still
need to say "where".
BranchResolver was likewise not a branch feature. doctor_addresses is a global
table, so TenantFilter does not cover it and eight callers across booking,
availability, pricing and the catalog went through this resolver to avoid
leaking another clinic's address. It moved to Doctor\Service\AddressResolver
rather than dying with the domain.
The availability engine loses one layer: a resource's real hours were the
branch hours intersected with its shift, and are now the shift alone. That is
the single behavioural change, and the three tests that asserted the old
contract are replaced by one that states the new one.
Rooms already had a resource row each; the migration drops only the bridge
back to `rooms`, and drops it before the table — that foreign key is ON DELETE
CASCADE and the other order would take the resources, and their appointments,
with it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
11 KiB
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 یعنی آن روز باز است.
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