hamedandClaude Opus 5
4d722830e3
Completes task 03. The resource calendar page edits weekly shifts, records leave and
maintenance, and previews two weeks of availability with a Persian reason for every
empty day — showing the raw server key ("outside_branch_hours") to a user would have
been a meaningless message. The preview is labelled raw on the page itself, because
booked appointments are not subtracted yet and mistaking it for bookable time leads
to overbooking.
The interval algebra moved to src/Shared/Time/TimeInterval.php with twelve unit
tests: tasks 05 and 06 need the same union/intersect/subtract, and a second
implementation is how two subtly different definitions of "overlap" get born. The
half-open [start, end) contract is what makes a shift ending at 13:00 and one
starting at 13:00 not overlap.
AvailabilityQueryCountTest locks the query count flat: one day and ninety days cost
exactly the same number of queries. Without it the first refactor can put a query
inside the day loop and a 90-day response quietly becomes hundreds of queries —
something only production would reveal.
app:resource:calendar:backfill derives shifts from existing WeeklySchedule sessions,
so the resources created in task 02 are not left with empty calendars. It skips any
resource a user has already configured, which is also what makes it idempotent. The
weekly schedule itself is untouched: this is a copy, not a migration.
Also added --replace to the holiday import. upsert keys on the date, so a row written
with a *wrong* date can never correct itself — re-running just creates the right row
beside the wrong one. That is exactly what happened after fixing the Jalali
conversion bug, and it was caught while capturing real responses for the docs.
Deferred with reasons recorded in the checklist: seasonal shift validity (two
nullable columns can be added later without backfill, so "needed from day one" does
not hold), and a Jalali date picker in the exception form.
1154 tests / 3229 assertions. phpstan at its 14-error baseline, none in touched
files. tsc clean, vitest 622 tests.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
247 lines
10 KiB
Markdown
247 lines
10 KiB
Markdown
# Resource Calendar API — تقویم منبع، استثنا و تعطیلات
|
||
|
||
> **Base:** `/api/v1` · **Auth:** JWT · **مجوز:** `appointment_settings`
|
||
> مکمل [resource.md](resource.md) — منبع آنجا ساخته میشود، تقویمش اینجا.
|
||
|
||
---
|
||
|
||
## کسرِ لایهها
|
||
|
||
بند ۹ مستند ساعت آزاد را از کسر هفت لایه میسازد. آنچه این بخش میدهد **چهار لایهٔ اول** است:
|
||
|
||
```
|
||
ساعت کاری شعبه ∩ شیفت منبع − تعطیلات رسمی − استثناهای منبع
|
||
```
|
||
|
||
**نوبتهای ثبتشده و رزروهای موقت اینجا کسر نمیشوند.** خروجی این اندپوینت «وقت قابل
|
||
رزرو» **نیست**؛ تقاطع چند منبع و کسر اشغال کارِ تسکهای بعدی است. متد داخلیاش عمداً
|
||
`rawAvailability()` نام دارد.
|
||
|
||
مسیر اسلاتیِ موجود (`SlotCalculatorService`، `WeeklySchedule`، `DateOverride`، `Holiday`)
|
||
در این فاز **دستنخورده** است؛ این یک مسیر موازی روی منبع است.
|
||
|
||
---
|
||
|
||
## `GET /api/v1/resource/{uuid}/calendar`
|
||
|
||
```json
|
||
{
|
||
"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](branch.md)): دقیقه از نیمهشب `0..1440`، `end > start`، بدون
|
||
همپوشانی در یک روز، `sequence` را سرور میدهد، و **اعتبارسنجی کامل پیش از هر حذفی**.
|
||
|
||
```json
|
||
{ "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`
|
||
|
||
**۲۰۱** (خروجی واقعی):
|
||
|
||
```json
|
||
{
|
||
"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اند و هر دو روز **شامل**اند. سقف بازه ۹۲ روز است.
|
||
|
||
**۲۰۰** (خروجی واقعی برای دو روز):
|
||
|
||
```json
|
||
{
|
||
"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` · بازهٔ بیش از ۹۲ روز (خروجی واقعی):
|
||
|
||
```json
|
||
{"success":false,"data":null,"errors":[{"code":"ERR_VALIDATION_001","message":"بازهٔ درخواستی حداکثر 92 روز است","field":"to"}]}
|
||
```
|
||
|
||
### دو قرارداد مهم
|
||
|
||
**شعبهٔ بدون ساعت کاری = «تعریفنشده»، نه «بسته».** شیفت منبع بیقید اعمال میشود تا
|
||
دادهٔ موجود دقیقاً مثل امروز کار کند. این با `branch_closed` — که یعنی ساعت تعریف شده
|
||
ولی آن روز خالی است — فرق دارد.
|
||
|
||
**شیفت بیرون از ساعت شعبه رد نمیشود، تقاطع گرفته میشود.** شیفت ۹–۱۷ روی شعبهای که
|
||
۱۰–۱۲ باز است، ۱۲۰ دقیقه میدهد.
|
||
|
||
---
|
||
|
||
## تعطیلات رسمی
|
||
|
||
### `GET /api/v1/national-holidays?year=1405`
|
||
|
||
تعطیلات **سراسری**اند و به محیط تعلق ندارند؛ امروز هر پزشک باید ۱۳ فروردین را دستی
|
||
ثبت کند، که هم تکرار است و هم منبع خطا.
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
```bash
|
||
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` — کشوری است، نه محیطی |
|
||
|
||
---
|
||
|
||
## تستها
|
||
|
||
```bash
|
||
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
|
||
```
|