feat: implement cancellation policy, no-show tracking, and waitlist management

- Add implementation notes for cancellation and waitlist features. - Create task documentation outlining goals, current status, and acceptance criteria for cancellation policy and resource utilization reporting. - Establish architecture for domain events and outbox pattern to ensure reliable event publishing. - Define database schema for domain events and necessary queries for resource utilization and plan accuracy reports. - Implement detailed implementation notes covering edge cases, testing strategies, and documentation requirements.
2026-07-30 11:43:58 +03:30
parent 1d338503c8
commit 021d0eb6b2
62 changed files with 8098 additions and 0 deletions
@@ -0,0 +1,93 @@
+# تسک‌های موتور نوبت‌دهی چندمنبعی Clinic Pro
+
+پیاده‌سازی تدریجی [clinic-pro-mostanad-sade.md](../clinic-pro-mostanad-sade.md) روی کد موجود.
+گزارش وضعیت فعلی و تحلیل شکاف: [00-current-state-report.md](00-current-state-report.md)
+
+> **پیش‌فرض کلیدی:** بازنویسی نداریم. نوبت‌دهی اسلاتی (`booking_mode=slot`) و نوبت‌دهی
+> سرویسیِ فعلی (`booking_mode=service`) تا آخر این مسیر بدون تغییر رفتار کار می‌کنند.
+> حالت جدید `booking_mode=resource` کنارشان اضافه می‌شود.
+
+---
+
+## لیست تسک‌ها
+
+| تسک | ماژول | Endpoint جدید | وابستگی | زمان |
+|-----|-------|--------------|---------|------|
+| [۰۱](task-01-branch-room/) | شعبه و اتاق | ۸ | — | ۱۰-۱۲h |
+| [۰۲](task-02-resource-model/) | منبع، نوع منبع، مهارت، استخر | ۱۴ | ۰۱ | ۱۴-۱۸h |
+| [۰۳](task-03-resource-calendar/) | تقویم منبع، مرخصی، تعطیلات ملی | ۹ | ۰۱، ۰۲ | ۱۲-۱۴h |
+| [۰۴](task-04-service-catalog-v2/) | کاتالوگ خدمات v2 (گروه آیتم، دو نوع زمان) | ۱۰ | ۰۱ | ۱۴-۱۶h |
+| [۰۵](task-05-appointment-plan/) | بخش‌های نوبت و سازندهٔ برنامه | ۳ | ۰۲، ۰۴ | ۱۶-۲۰h |
+| [۰۶](task-06-availability-engine/) | موتور جستجوی وقت چندمنبعی | ۲ | ۰۳، ۰۵ | ۲۰-۲۴h |
+| [۰۷](task-07-hold-and-book/) | رزرو موقت و ثبت نهایی چندمنبعی | ۴ | ۰۶ | ۱۶-۲۰h |
+| [۰۸](task-08-pricing-snapshot/) | لیست قیمت بازه‌دار و snapshot فاکتور | ۷ | ۰۴، ۰۷ | ۱۲-۱۴h |
+| [۰۹](task-09-policy-engine/) | موتور قوانین شش‌دسته‌ای | ۶ | ۰۵، ۰۶، ۰۸ | ۲۰-۲۴h |
+| [۱۰](task-10-policy-admin-sandbox/) | فرم ساخت قانون + محیط آزمایش | ۲ | ۰۹ | ۱۰-۱۲h |
+| [۱۱](task-11-package-credit-ledger/) | پکیج و دفتر اعتبار جلسات | ۸ | ۰۸ | ۱۰-۱۲h |
+| [۱۲](task-12-treatment-course/) | دوره درمان | ۹ | ۰۷، ۱۱ | ۱۶-۲۰h |
+| [۱۳](task-13-cancellation-waitlist/) | سیاست لغو، عدم حضور، لیست انتظار | ۷ | ۰۷ | ۱۰-۱۲h |
+| [۱۴](task-14-events-utilization/) | رویدادهای دامنه و گزارش بهره‌وری | ۳ | ۰۷ | ۸-۱۰h |
+
+**مجموع endpoint جدید: ~۹۲ · مجموع زمان: ۱۹۰ تا ۲۲۸ ساعت**
+
+---
+
+## ساختار هر تسک
+
+```
+task-XX-name/
+├── task.md                 ← شرح، دامنه، endpoint ها، معیار پذیرش، زمان
+├── architecture.md         ← فایل‌ها، entity ها، سرویس‌ها، لایه‌ها
+├── database.md             ← جداول، ستون‌ها، ایندکس‌ها، migration
+├── implementation_notes.md ← نکات فنی، edge case، سازگاری عقب‌رو، تست
+└── user_flow.md            ← (تسک‌های پیچیده) جریان کاربری
+```
+
+---
+
+## ترتیب پیشنهادی اجرا
+
+```
+۰۱ ─┬─ ۰۲ ── ۰۳ ─┐
+    └─ ۰۴ ── ۰۵ ─┴─ ۰۶ ── ۰۷ ─┬─ ۰۸ ─┬─ ۰۹ ── ۱۰
+                              │      └─ ۱۱ ── ۱۲
+                              ├─ ۱۳
+                              └─ ۱۴
+```
+
+فاز اول (هستهٔ قابل عرضه): ۰۱ تا ۰۸ — بعد از آن یک کلینیک زیبایی با اتاق، دستگاه و
+اپراتور می‌تواند واقعاً نوبت بگیرد.
+
+---
+
+## قواعد مشترک همهٔ تسک‌ها
+
+قواعد پروژه در [CLAUDE.md](../../../CLAUDE.md) و
+[docs/architecture/tenancy.md](../../architecture/tenancy.md) بر همهٔ این تسک‌ها حاکم‌اند.
+مواردی که در هر تسک باید رعایت شوند:
+
+1. هر entity جدید یا `TenantOwnedTrait` می‌گیرد یا در `GlobalTables` با دلیل ثبت می‌شود؛
+   `TenantSchemaCoverageTest` را اجرا کن.
+2. `entity_type, entity_id` ستون‌های **اول** هر ایندکس ترکیبی لیست.
+3. هر uuid که از request می‌آید باید با `TenantOwnershipChecker` سنجیده شود؛
+   `TenantLookupInventoryTest` شمارنده دارد.
+4. timestamp ها `int` (Unix)، نه `DateTime`. نمایش شمسی فقط در UI.
+5. کنترلر نازک، `extends BaseController`، پاسخ با `success()/paginated()/error()`.
+6. هر endpoint جدید یا تغییر یافته → به‌روزرسانی `docs/api/*.md` در همان نشست.
+7. تست موفق + خطا + مرزی برای هر تسک، وگرنه تسک تمام نیست.
+8. رشته‌های UI فارسی، کد و کامیت انگلیسی.
+9. سازگاری عقب‌رو: `nobat724_front` و `clinic-pro-tauri` مصرف‌کنندهٔ همین APIها هستند
+   و در build خطا نمی‌دهند — هر تغییر قرارداد باید دستی بررسی شود.
+
+---
+
+## سازگاری با نوبت‌دهی فعلی
+
+| حالت | منبع تنظیم | چه زمانی |
+|---|---|---|
+| `slot` | `WeeklySchedule.meta.booking_mode` | اسلات ثابت `duration_per_patient` — رفتار پیش‌فرض امروز |
+| `service` | همان | طول = جمع مدت سرویس‌ها + buffer — پیاده‌شده، تک‌منبعی |
+| `resource` | همان | **جدید** — برنامهٔ چندبخشی + چند منبع (تسک ۰۵ به بعد) |
+
+`booking_mode` پس از اولین ثبت قفل می‌شود (`WeeklySchedule::getStoredBookingMode()`).
+تسک ۰۶ باید مسیر ارتقای داوطلبانهٔ `service → resource` را باز کند، بدون اجبار.