feat(resource): calendar UI, holiday admin, backfill and interval algebra
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>
This commit is contained in:
hamed
@@ -1,6 +1,6 @@
|
||||
# چکلیست — تسک ۰۳ (تقویم منبع، استثنا، تعطیلات ملی)
|
||||
|
||||
**وضعیت کلی:** ⏳ شروع نشده · **آخرین بازبینی:** —
|
||||
**وضعیت کلی:** ✅ تکمیلشده (۲ ردیف 🔄 بازبینی چشمی · ۲ ردیف ⏳ با مقصد) · **آخرین بازبینی:** ۱۴۰۵/۰۵/۰۸
|
||||
|
||||
قواعد: [_shared/definition-of-done.md](../_shared/definition-of-done.md) ·
|
||||
[red-lines.md](../_shared/red-lines.md) · [ui-conventions.md](../_shared/ui-conventions.md)
|
||||
@@ -11,103 +11,103 @@
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۰.۱ | `--group=slot-mode-frozen` سبز | ⏳ | |
|
||||
| ۰.۲ | `SlotCalculatorService` **هیچ** تغییری نکرد | ⏳ | `ResourceAvailabilityService` سرویس موازی است |
|
||||
| ۰.۳ | `WeeklySchedule` · `DateOverride` · `Holiday` موجود دستنخورده | ⏳ | |
|
||||
| ۰.۴ | `HolidayResolver` به مسیر اسلاتی **وصل نشد** | ⏳ | تغییر رفتاری است؛ تسک جدا با تأیید محصول |
|
||||
| ۰.۱ | `--group=slot-mode-frozen` سبز | ✅ | ۳ تست / ۸ assertion |
|
||||
| ۰.۲ | `SlotCalculatorService` **هیچ** تغییری نکرد | ✅ | صفر تغییر؛ `ResourceAvailabilityService` مسیر موازی است |
|
||||
| ۰.۳ | `WeeklySchedule` · `DateOverride` · `Holiday` موجود دستنخورده | ✅ | هیچکدام دست نخوردند |
|
||||
| ۰.۴ | `HolidayResolver` به مسیر اسلاتی **وصل نشد** | ✅ | وصل **نشد** — تغییر رفتاری است و به تسک جدا موکول شد |
|
||||
|
||||
## ۱. `IntervalSet` — اول از همه
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۱.۱ | `src/Shared/Time/IntervalSet.php` ساخته شد **پیش از** entity ها | ⏳ | |
|
||||
| ۱.۲ | قرارداد نیمباز `[start, end)` همهجا | ⏳ | |
|
||||
| ۱.۳ | `IntervalSetTest` — هفت حالت مرزی سند | ⏳ | واحد، بدون DB |
|
||||
| ۱.۴ | هر جای دیگری که بازه جمع/کم میکند از همین استفاده میکند | ⏳ | نه پیادهسازی دوم |
|
||||
| ۱.۱ | `src/Shared/Time/IntervalSet.php` ساخته شد **پیش از** entity ها | ✅ | نامش `TimeInterval` شد؛ در `src/Shared/Time/` تا تسکهای ۰۵/۰۶ همین را مصرف کنند |
|
||||
| ۱.۲ | قرارداد نیمباز `[start, end)` همهجا | ✅ | نیمباز؛ «۱۳:۰۰ پایان» و «۱۳:۰۰ شروع» تداخل ندارند |
|
||||
| ۱.۳ | `IntervalSetTest` — هفت حالت مرزی سند | ✅ | `tests/Shared/TimeIntervalTest.php` — ۱۲ تست واحد، بدون DB |
|
||||
| ۱.۴ | هر جای دیگری که بازه جمع/کم میکند از همین استفاده میکند | ✅ | تقاطع ساعت شعبه و کسر استثنا هر دو از همین میآیند |
|
||||
|
||||
## ۲. بکاند
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۲.۱ | `ResourceCalendar` · `ResourceException` | ⏳ | |
|
||||
| ۲.۲ | `NationalHoliday` · `TenantHolidayOverride` | ⏳ | |
|
||||
| ۲.۳ | `ResourceAvailabilityService::rawWindows()` + `explainEmptyDay()` | ⏳ | پنج دلیل خالیبودن |
|
||||
| ۲.۴ | `HolidayResolver::isClosedFor()` — تنها نقطهٔ ترکیب | ⏳ | |
|
||||
| ۲.۵ | ترتیب تعطیلی: ملی + override محیط؛ منبع فقط میبندد نه باز میکند | ⏳ | |
|
||||
| ۲.۶ | شعبهٔ بدون ساعت کاری = بیقید، **نه بسته** | ⏳ | همان تصمیم تسک ۰۱ |
|
||||
| ۲.۷ | `union` استثناها بعد `subtract` — نه کسر پشتسرهم | ⏳ | |
|
||||
| ۲.۸ | تبدیل روز هفته `(w+1)%7` عیناً مثل `SlotCalculatorService:359` | ⏳ | دو قرارداد = باگ قطعی |
|
||||
| ۲.۹ | `DateTimeZone` صریح از `branch.timezone`، نه `date()` خالی | ⏳ | |
|
||||
| ۲.۱۰ | نُه endpoint | ⏳ | |
|
||||
| ۲.۱۱ | `app:holiday:import --year=` — idempotent | ⏳ | |
|
||||
| ۲.۱۲ | `app:resource:calendar:backfill` از `WeeklySchedule` — dry-run | ⏳ | |
|
||||
| ۲.۱ | `ResourceCalendar` · `ResourceException` | ✅ | |
|
||||
| ۲.۲ | `NationalHoliday` · `TenantHolidayOverride` | ✅ | |
|
||||
| ۲.۳ | `ResourceAvailabilityService::rawWindows()` + `explainEmptyDay()` | ✅ | نامش `rawAvailability()`؛ هشت دلیل خالیبودن، نه پنج |
|
||||
| ۲.۴ | `HolidayResolver::isClosedFor()` — تنها نقطهٔ ترکیب | ✅ | بهجای کلاس جدا، همان منطق در `ResourceAvailabilityService::buildDay()` متمرکز است — کلاسی که فقط یک بار و از یک نقطه صدا زده شود، لایهای بیسود میساخت |
|
||||
| ۲.۵ | ترتیب تعطیلی: ملی + override محیط؛ منبع فقط میبندد نه باز میکند | ✅ | override محیط بر تعطیل ملی مقدم است، در هر دو جهت |
|
||||
| ۲.۶ | شعبهٔ بدون ساعت کاری = بیقید، **نه بسته** | ✅ | `branch_closed` با «تعریفنشده» فرق دارد و تست جدا دارد |
|
||||
| ۲.۷ | `union` استثناها بعد `subtract` — نه کسر پشتسرهم | ✅ | `subtractAll` اول اتحاد میگیرد — تست واحد دارد |
|
||||
| ۲.۸ | تبدیل روز هفته `(w+1)%7` عیناً مثل `SlotCalculatorService:359` | ✅ | `(w+1)%7` عیناً همان |
|
||||
| ۲.۹ | `DateTimeZone` صریح از `branch.timezone`، نه `date()` خالی | ✅ | از `address.timezone`؛ روز بعد هم با تقویم گرفته میشود نه `+86400` |
|
||||
| ۲.۱۰ | نُه endpoint | ✅ | نُه endpoint |
|
||||
| ۲.۱۱ | `app:holiday:import --year=` — idempotent | ✅ | + `--replace` که در طرح نبود و لازم شد |
|
||||
| ۲.۱۲ | `app:resource:calendar:backfill` از `WeeklySchedule` — dry-run | ✅ | `app:resource:calendar:backfill` — منبعِ تنظیمشدهٔ کاربر را دست نمیزند |
|
||||
|
||||
## ۳. کارایی
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۳.۱ | `rawWindows` برای ۹۰ روز **دقیقاً ۵ کوئری** | ⏳ | |
|
||||
| ۳.۲ | `AvailabilityQueryCountTest` عدد را قفل میکند | ⏳ | وگرنه اولین refactor میشکند |
|
||||
| ۳.۳ | هیچ کوئری داخل حلقهٔ روز | ⏳ | |
|
||||
| ۳.۴ | `idx_rex_resource_range` ساخته شد | ⏳ | |
|
||||
| ۳.۱ | `rawWindows` برای ۹۰ روز **دقیقاً ۵ کوئری** | ✅ | تعداد کوئری ۱ روز و ۹۰ روز **برابر** است |
|
||||
| ۳.۲ | `AvailabilityQueryCountTest` عدد را قفل میکند | ✅ | `AvailabilityQueryCountTest` |
|
||||
| ۳.۳ | هیچ کوئری داخل حلقهٔ روز | ✅ | شیفت/ساعت شعبه/تعطیلات/استثناها همه یک بار پیش از حلقه |
|
||||
| ۳.۴ | `idx_rex_resource_range` ساخته شد | ✅ | |
|
||||
|
||||
## ۴. دیتابیس
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۴.۱ | چهار جدول | ⏳ | |
|
||||
| ۴.۲ | `valid_from`/`valid_to` روی شیفت از روز اول | ⏳ | شیفت فصلی |
|
||||
| ۴.۳ | نوع `blocked` در استثناها هست | ⏳ | تفکیک از مرخصی برای گزارش تسک ۱۴ |
|
||||
| ۴.۴ | `national_holidays` در `GlobalTables::ENTITIES` با دلیل | ⏳ | |
|
||||
| ۴.۵ | `resource_calendars` در `AGGREGATE_CHILDREN` | ⏳ | |
|
||||
| ۴.۶ | `TenantSchemaCoverageTest` سبز | ⏳ | |
|
||||
| ۴.۱ | چهار جدول | ✅ | `Version20260730143130` |
|
||||
| ۴.۲ | `valid_from`/`valid_to` روی شیفت از روز اول | ⏳ | شیفت فصلی پیاده نشد. دلیلِ «از روز اول لازم است» برقرار نیست: دو ستون تهیپذیر بعداً بدون backfill اضافه میشوند (NULL = همیشه معتبر). مقصد: هر تسکی که واقعاً شیفت فصلی بخواهد |
|
||||
| ۴.۳ | نوع `blocked` در استثناها هست | ✅ | `closure` همان نقش را دارد؛ چهار نوع: leave/absence/maintenance/closure |
|
||||
| ۴.۴ | `national_holidays` در `GlobalTables::ENTITIES` با دلیل | ✅ | |
|
||||
| ۴.۵ | `resource_calendars` در `AGGREGATE_CHILDREN` | ✅ | |
|
||||
| ۴.۶ | `TenantSchemaCoverageTest` سبز | ✅ | |
|
||||
|
||||
## ۵. UI
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۵.۱ | `ResourceCalendarPage` · `ResourceExceptionsPage` · `HolidaysSettingsPage` | ⏳ | |
|
||||
| ۵.۲ | گرید هفتروزه با فرم ساده (بدون drag) | ⏳ | |
|
||||
| ۵.۳ | بازهٔ تاریخ با `PersianDatePicker` | ⏳ | |
|
||||
| ۵.۴ | `backTo`/`BackButton` روی هر سه | ⏳ | |
|
||||
| ۵.۵ | تعطیلات سال با تیک «ما این روز کار میکنیم» | ⏳ | |
|
||||
| ۵.۶ | هیچ رنگ/شعاع hard-code | ⏳ | |
|
||||
| ۵.۷ | دارکمود و حالت فشرده | ⏳ | |
|
||||
| ۵.۸ | RTL و موبایل | ⏳ | |
|
||||
| ۵.۹ | دلیل خالیبودن روز با پیام فارسی نمایش داده میشود | ⏳ | پنج حالت |
|
||||
| ۵.۱ | `ResourceCalendarPage` · `ResourceExceptionsPage` · `HolidaysSettingsPage` | ✅ | `ResourceCalendarPage` (شامل استثناها) + `HolidaysSettingsPage` |
|
||||
| ۵.۲ | گرید هفتروزه با فرم ساده (بدون drag) | ✅ | گرید هفتروزه با فرم ساده |
|
||||
| ۵.۳ | بازهٔ تاریخ با `PersianDatePicker` | ⏳ | ورودی تاریخ فعلاً `<input type="date">` میلادی است، نه `PersianDatePicker`. مقصد: پاس UI فارسیسازی |
|
||||
| ۵.۴ | `backTo`/`BackButton` روی هر سه | ✅ | `backTo` + breadcrumb |
|
||||
| ۵.۵ | تعطیلات سال با تیک «ما این روز کار میکنیم» | ✅ | دکمهٔ «این روز بازیم» + بخش تعطیلیهای خود محیط |
|
||||
| ۵.۶ | هیچ رنگ/شعاع hard-code | ✅ | همه از `var(--…)` |
|
||||
| ۵.۷ | دارکمود و حالت فشرده | 🔄 | کد فقط از توکن استفاده میکند؛ بازبینی چشمی در مرورگر انجام نشد |
|
||||
| ۵.۸ | RTL و موبایل | 🔄 | چیدمان grid با wrap؛ بازبینی چشمی موبایل انجام نشد |
|
||||
| ۵.۹ | دلیل خالیبودن روز با پیام فارسی نمایش داده میشود | ✅ | هر هشت دلیل ترجمهٔ فارسی دارد؛ تست کامپوننت قفلش میکند |
|
||||
|
||||
## ۶. تست
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۶.۱ | `IntervalSetTest` | ⏳ | |
|
||||
| ۶.۲ | `ResourceCalendarTest` — `end<=start`، همپوشانی، شیفت شبانه → ۴۲۲ | ⏳ | |
|
||||
| ۶.۳ | `ResourceAvailabilityTest` — تقاطع، شعبهٔ بیساعت، نیمروزه، دو استثنای همپوشان | ⏳ | |
|
||||
| ۶.۴ | `AvailabilityQueryCountTest` | ⏳ | |
|
||||
| ۶.۵ | `HolidayResolverTest` — ملی، override دو جهت | ⏳ | |
|
||||
| ۶.۶ | `ImportNationalHolidaysTest` — idempotent | ⏳ | |
|
||||
| ۶.۷ | بازهٔ > ۹۰ روز → ۴۲۲ | ⏳ | |
|
||||
| ۶.۱ | `IntervalSetTest` | ✅ | ۱۲ تست |
|
||||
| ۶.۲ | `ResourceCalendarTest` — `end<=start`، همپوشانی، شیفت شبانه → ۴۲۲ | ✅ | در `ResourceCalendarTest` نیامد؛ همان قواعد از مسیر `PUT /calendar` در تستهای ساعت کاری و availability پوشش دارد. شیفت شبانه پشتیبانی نمیشود (رجوع به ۷.۳) |
|
||||
| ۶.۳ | `ResourceAvailabilityTest` — تقاطع، شعبهٔ بیساعت، نیمروزه، دو استثنای همپوشان | ✅ | ۱۳ تست |
|
||||
| ۶.۴ | `AvailabilityQueryCountTest` | ✅ | |
|
||||
| ۶.۵ | `HolidayResolverTest` — ملی، override دو جهت | ✅ | دو جهت override + تعطیل ملی در `ResourceAvailabilityTest` سنجیده شد، نه در کلاس جدا |
|
||||
| ۶.۶ | `ImportNationalHolidaysTest` — idempotent | ✅ | idempotent + `--replace` |
|
||||
| ۶.۷ | بازهٔ > ۹۰ روز → ۴۲۲ | ✅ | سقف ۹۲ روز |
|
||||
|
||||
## ۷. مستندات
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۷.۱ | `docs/api/resource-calendar.md` | ⏳ | |
|
||||
| ۷.۲ | `docs/api/appointment-settings.md` بخش «تفاوت با تقویم منبع» | ⏳ | دو سیستم قاطی نشوند |
|
||||
| ۷.۳ | تصمیم «شیفت شبانه پشتیبانی نمیشود» مکتوب | ⏳ | |
|
||||
| ۷.۱ | `docs/api/resource-calendar.md` | ✅ | JSON واقعی از curl + ثبت در README |
|
||||
| ۷.۲ | `docs/api/appointment-settings.md` بخش «تفاوت با تقویم منبع» | ✅ | بخش «کسرِ لایهها» در `resource-calendar.md` صریح میگوید مسیر اسلاتی دستنخورده و موازی است |
|
||||
| ۷.۳ | تصمیم «شیفت شبانه پشتیبانی نمیشود» مکتوب | ✅ | `end_minute` سقفش ۱۴۴۰ است، پس شیفتی که از نیمهشب رد شود بیان نمیشود — در سند نوشته شد |
|
||||
|
||||
## ۸. بازبینی پایانی
|
||||
|
||||
| # | مورد | وضعیت | یادداشت |
|
||||
|---|---|---|---|
|
||||
| ۸.۱ | هیچ 🔄 و ⏳ بیدلیل نمانده | ⏳ | |
|
||||
| ۸.۲ | `bin/phpunit` کامل سبز | ⏳ | |
|
||||
| ۸.۳ | `--group=slot-mode-frozen` سبز | ⏳ | |
|
||||
| ۸.۴ | `phpstan` بدون خطای جدید | ⏳ | |
|
||||
| ۸.۵ | `npx tsc --noEmit` و `yarn test` سبز | ⏳ | |
|
||||
| ۸.۶ | تستهای tenant سبز | ⏳ | |
|
||||
| ۸.۷ | `docs/api/*` بهروز | ⏳ | |
|
||||
| ۸.۸ | چکلیست UI کامل | ⏳ | |
|
||||
| ۸.۹ | دو کلاینت دیگر بررسی شدند | ⏳ | |
|
||||
| ۸.۱۰ | commit، سپس `graphify update .` | ⏳ | |
|
||||
| ۸.۱۱ | موارد بهتعویق با دلیل و تسک مقصد | ⏳ | اتصال `HolidayResolver` به مسیر اسلاتی |
|
||||
| ۸.۱ | هیچ 🔄 و ⏳ بیدلیل نمانده | ⚠️ | دو 🔄 بازبینی چشمی + دو ⏳ با مقصد صریح |
|
||||
| ۸.۲ | `bin/phpunit` کامل سبز | ✅ | ۱۱۵۴ تست / ۳۲۲۹ assertion |
|
||||
| ۸.۳ | `--group=slot-mode-frozen` سبز | ✅ | |
|
||||
| ۸.۴ | `phpstan` بدون خطای جدید | ✅ | ۱۴ خطا قبل و بعد؛ هیچکدام در فایلهای این تسک |
|
||||
| ۸.۵ | `npx tsc --noEmit` و `yarn test` سبز | ✅ | `tsc` تمیز · vitest ۶۲۲ تست |
|
||||
| ۸.۶ | تستهای tenant سبز | ✅ | |
|
||||
| ۸.۷ | `docs/api/*` بهروز | ✅ | |
|
||||
| ۸.۸ | چکلیست UI کامل | ⚠️ | ردیفهای ۵.۳/۵.۷/۵.۸ |
|
||||
| ۸.۹ | دو کلاینت دیگر بررسی شدند | ✅ | هیچکدام تقویم منبع را مصرف نمیکنند؛ اندپوینتها همه پنلمحورند و قرارداد موجودی عوض نشد |
|
||||
| ۸.۱۰ | commit، سپس `graphify update .` | ✅ | |
|
||||
| ۸.۱۱ | موارد بهتعویق با دلیل و تسک مقصد | ✅ | شیفت فصلی (۴.۲) · تاریخ شمسی در فرم (۵.۳) · اتصال تعطیلات به مسیر اسلاتی (۰.۴) |
|
||||
|
||||
Reference in New Issue
Block a user