feat(cancellation): cancellation policy, no-show tracking and a waitlist
Cancelling worked but had no policy behind it: no window, no penalty, nothing happened to the deposit, and the no_show status had no effect at all. Two rules that are expensive to get wrong, and both are load-bearing: - The clinic cancelling its own appointment is never charged. That check is the first line of the calculation, not somewhere in the middle, so a later refactor cannot reorder it into charging patients for the clinic's decision. - A penalty never exceeds what was actually paid. Anything above that is a debt, and debt belongs to billing, not to cancellation. An unpaid appointment is charged nothing and the response says why. The default is no penalty at all — a penalising default would have made every patient with a near appointment liable the moment this deployed. No-shows are rows, not a counter on the patient: a counter loses which appointment and when, which makes the 12-month window impossible. Crossing the threshold adds an existing TenantTag; it never blocks the patient, because blocking is an eligibility policy (task 09) written on top of that same tag. Waitlist notifies up to ten matching people and the first to book wins. An exclusive queue reads fairer but means a freed slot sits locked for half an hour while someone ignores their phone — so the SMS says so explicitly instead. Insufficient wallet balance does not fail the cancellation: the slot is freed either way. A slot should not be held hostage to money. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
hamed
@@ -0,0 +1,176 @@
|
||||
# Cancellation — سیاست لغو، جریمه و عدم حضور
|
||||
|
||||
اندپوینتهای `src/Cancellation/*`. مستند بند ۱۱: «هر کلینیک تنظیم میکند تا چند ساعت قبل
|
||||
لغو رایگان است، جریمه چقدر است، بیعانه برمیگردد یا نه، و بعد از چند بار عدم حضور بیمار
|
||||
پرریسک علامت بخورد.»
|
||||
|
||||
همهٔ مسیرها `IS_AUTHENTICATED_FULLY` میخواهند و به محیط جاری محدودند (`404` برای محیط دیگر).
|
||||
|
||||
---
|
||||
|
||||
## دو قاعدهای که شکستنشان گران است
|
||||
|
||||
۱. **لغو توسط کلینیک هرگز جریمه ندارد.** این شرط اولین خط محاسبه است، نه جایی وسط آن —
|
||||
اگر بعد از بررسی پنجرهٔ زمانی میآمد، یک refactor میتوانست ترتیب را عوض کند و کلینیک
|
||||
از بیمار برای لغو خودش جریمه بگیرد.
|
||||
۲. **جریمه هرگز از مبلغ پرداختی بیشتر نمیشود.** جریمهٔ بیشتر یعنی بدهی، و بدهی مسئلهٔ
|
||||
صورتحساب است نه لغو. برای نوبت نقدی (پرداختی صفر) جریمه صفر میشود و پاسخ توضیحش را
|
||||
در `notes` میدهد.
|
||||
|
||||
**پیشفرض بدون جریمه است.** اگر پیشفرض جریمهدار بود، لحظهٔ deploy همهٔ بیماران با نوبت
|
||||
نزدیک مشمول جریمه میشدند و کلینیک خبر نداشت. فعالکردن جریمه یک تصمیم کسبوکاری صریح است.
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/cancellation-policy`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"default": {
|
||||
"uuid": "…",
|
||||
"service_uuid": null,
|
||||
"free_window_hours": 24,
|
||||
"penalty_mode": "percent",
|
||||
"penalty_value": 50,
|
||||
"deposit_refundable": false,
|
||||
"credit_refundable": true,
|
||||
"no_show_threshold": 3,
|
||||
"risk_tag_uuid": null,
|
||||
"active": true,
|
||||
"created_at": 1785486000
|
||||
},
|
||||
"overrides": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## PUT `/api/v1/cancellation-policy` · PUT `/api/v1/service-item/{uuid}/cancellation-policy`
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `free_window_hours` | int | تا چند ساعت قبل، لغو رایگان است |
|
||||
| `penalty_mode` | string | `none` \| `percent` \| `fixed` |
|
||||
| `penalty_value` | int | درصد ۰..۱۰۰ یا مبلغ ریالی |
|
||||
| `deposit_refundable` | bool | پس از پنجرهٔ رایگان |
|
||||
| `credit_refundable` | bool | اعتبار پکیج (تسک ۱۱) |
|
||||
| `no_show_threshold` | int | بعد از چند بار عدم حضور، برچسب پرریسک |
|
||||
| `risk_tag_uuid` | string\|null | برچسبی از `tenant_tags` |
|
||||
| `active` | bool | |
|
||||
|
||||
سیاستِ سرویس و سیاستِ محیط **ترکیب نمیشوند**: اگر سرویس سیاست فعال دارد، همان کامل
|
||||
برنده است. «۲۴ ساعت از محیط ولی ۵۰٪ از سرویس» چیزی است که هیچ اپراتوری نمیتواند در
|
||||
ذهنش شبیهسازی کند.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|---|---|---|
|
||||
| `ERR_VALIDATION_001` | 422 | درصد بیرون بازهٔ ۰..۱۰۰ یا حالت جریمهٔ ناشناخته |
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/appointment/{uuid}/cancellation-preview`
|
||||
|
||||
| Query | Type | Description |
|
||||
|---|---|---|
|
||||
| `by` | string | `doctor` برای لغو از سمت کلینیک؛ پیشفرض بیمار |
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"penalty_rials": 2000000,
|
||||
"deposit_refundable": false,
|
||||
"credit_refundable": true,
|
||||
"within_free_window": false,
|
||||
"notes": [],
|
||||
"paid_rials": 4000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
همان محاسبهای که خودِ لغو انجام میدهد — بیمار نباید عددی ببیند که با آنچه کسر میشود
|
||||
فرق دارد.
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/appointment/{uuid}/cancel`
|
||||
|
||||
```json
|
||||
{ "by": "doctor" }
|
||||
```
|
||||
|
||||
`by` اختیاری است؛ نبودنش یعنی لغو از سمت بیمار.
|
||||
|
||||
### Response `200`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"appointment_uuid": "…",
|
||||
"status": "cancelled_by_user",
|
||||
"released_resources": 3,
|
||||
"waitlist_notified": 2,
|
||||
"penalty_charged": true,
|
||||
"penalty_rials": 1000000,
|
||||
"deposit_refundable": false,
|
||||
"credit_refundable": true,
|
||||
"within_free_window": false,
|
||||
"notes": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ترتیب کارها: اعتبارسنجی → آزادسازی ظرفیت و بازگشت اعتبار → کسر جریمه → اطلاع به لیست
|
||||
انتظار. اگر اطلاعرسانی اول بود، ده نفر برای ظرفیتی خبر میشدند که هنوز آزاد نشده.
|
||||
|
||||
**موجودی ناکافی لغو را شکست نمیدهد:** `penalty_charged: false` برمیگردد ولی نوبت آزاد
|
||||
میشود. نوبت نباید گروگان پول بماند.
|
||||
|
||||
سیاستی که `credit_refundable: false` دارد، اعتبارِ برگشتهٔ پکیج را با یک ردیف
|
||||
`adjustment` منفی پس میگیرد — ردیف `refund` حذف نمیشود، چون دفتر append-only است.
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|---|---|---|
|
||||
| `ERR_SLOT_TAKEN` | 409 | نوبت قبلاً لغو شده |
|
||||
| `ERR_VALIDATION_001` | 422 | نوبت گذشته — برای گذشته `no_show` یا `completed` معنا دارد |
|
||||
|
||||
---
|
||||
|
||||
## POST `/api/v1/appointment/{uuid}/no-show`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { "recorded": true, "count": 3, "threshold": 3, "tagged": true }
|
||||
}
|
||||
```
|
||||
|
||||
هر عدم حضور یک **ردیف** است نه یک شمارنده: شمارنده «چه زمانی و کدام نوبت» را از دست
|
||||
میدهد و پنجرهٔ ۱۲ ماهه را غیرقابل محاسبه میکند. بیماری که سه سال پیش سه بار نیامده،
|
||||
امروز پرریسک نیست.
|
||||
|
||||
ثبت دوباره روی همان نوبت `recorded: false` میدهد و شمارش را بالا نمیبرد.
|
||||
|
||||
⚠️ **برچسب پرریسک مسدود نمیکند.** مسدودسازی یک قانون `eligibility` (تسک ۰۹) روی همین
|
||||
برچسب است. تفکیکش عمدی است: کلینیکی که میخواهد بیمار پرریسک را ببیند ولی بیعانه بگیرد،
|
||||
نباید مجبور شود برچسب را خاموش کند.
|
||||
|
||||
---
|
||||
|
||||
## طبقهبندی محیط
|
||||
|
||||
| جدول | وضعیت |
|
||||
|---|---|
|
||||
| `cancellation_policies` · `no_show_records` | جفت محیط |
|
||||
|
||||
تراکنش جریمه در کیف پول با `entity_type`/`entity_id` نوبت ثبت میشود، وگرنه کلینیک الف
|
||||
جریمهٔ ثبتشده در کلینیک ب را میدید.
|
||||
|
||||
## تستها
|
||||
|
||||
```bash
|
||||
ddev exec php bin/phpunit tests/Cancellation # ۱۴ تست
|
||||
```
|
||||
@@ -0,0 +1,97 @@
|
||||
# Waitlist — لیست انتظار
|
||||
|
||||
اندپوینتهای `src/Waitlist/*`. «اگر وقتی در این بازه آزاد شد، خبرم کن» — توسعهٔ همان
|
||||
ایدهٔ `Appointment.is_reserve` موجود، ولی با بازهٔ صریح و وضعیت.
|
||||
|
||||
---
|
||||
|
||||
## چرا broadcast و نه صف انحصاری
|
||||
|
||||
ظرفیت آزادشده به **حداکثر ده نفر** خبر داده میشود و اولین رزروکننده میبرد.
|
||||
|
||||
صف انحصاری («فقط نفر اول ۳۰ دقیقه فرصت دارد») روی کاغذ عادلانهتر است، ولی در عمل یعنی
|
||||
وقتی که کسی جوابش را نمیدهد نیم ساعت قفل بماند و بعد به نفر دوم برسد — و ظرفیتی که دو
|
||||
ساعت مانده به نوبت آزاد شده، نیم ساعت وقتِ تلفکردنی ندارد.
|
||||
|
||||
در عوض متن پیامک **اجباراً** این را میگوید:
|
||||
|
||||
> «یک وقت برای «X» در تاریخ Y آزاد شد. اولین نفری که رزرو کند آن را میگیرد.»
|
||||
|
||||
هر درخواست حداکثر **سه بار** خبر میگیرد؛ بدون سقف، یک بازهٔ پرلغو به منبع اسپم تبدیل
|
||||
میشود.
|
||||
|
||||
---
|
||||
|
||||
## GET `/api/v1/waitlist`
|
||||
|
||||
| Query | Type | Description |
|
||||
|---|---|---|
|
||||
| `status` | string | `waiting` \| `notified` \| `converted` \| `expired` |
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"uuid": "…",
|
||||
"patient_uuid": "…",
|
||||
"service_uuid": "…",
|
||||
"service_name": "لیزر",
|
||||
"branch_id": 12,
|
||||
"desired_from": 1785600000,
|
||||
"desired_to": 1785859200,
|
||||
"preferred_day_parts": ["evening"],
|
||||
"priority": 0,
|
||||
"status": "waiting",
|
||||
"notified_at": null,
|
||||
"notify_count": 0,
|
||||
"created_at": 1785486000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## POST `/api/v1/waitlist`
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `patient_uuid` | string | ✅ | |
|
||||
| `service_uuid` | string | ✅ | |
|
||||
| `desired_from` / `desired_to` | int | ✅ | Unix؛ بازه باید در آینده باشد |
|
||||
| `branch_uuid` | string | — | نبودنش یعنی «هر شعبه» |
|
||||
| `preferred_day_parts` | string[] | — | `["morning","evening"]` |
|
||||
| `priority` | int | — | بزرگتر زودتر خبر میشود |
|
||||
|
||||
### Errors
|
||||
| Code | HTTP | Description |
|
||||
|---|---|---|
|
||||
| `ERR_VALIDATION_001` | 422 | بازهٔ گذشته یا پایانِ قبل از شروع |
|
||||
| `ERR_VALIDATION_002` | 422 | فیلد الزامی غایب |
|
||||
| `ERR_NOT_FOUND_001` | 404 | بیمار یا سرویس خارج از محیط جاری |
|
||||
|
||||
## DELETE `/api/v1/waitlist/{uuid}`
|
||||
|
||||
## GET `/api/v1/waitlist/matches`
|
||||
|
||||
| Query | Type | Required |
|
||||
|---|---|---|
|
||||
| `service_uuid` | string | ✅ |
|
||||
| `start` | int | ✅ |
|
||||
| `branch_uuid` | string | — |
|
||||
|
||||
چه کسانی منتظر این سرویس در این لحظهاند؟ مرتب بر اساس اولویت، بعد قدمت. درخواستی که
|
||||
شعبهٔ دیگری خواسته در نتیجه نمیآید؛ درخواست بیشعبه همیشه میآید.
|
||||
|
||||
---
|
||||
|
||||
## اطلاع خودکار هنگام لغو
|
||||
|
||||
`POST /api/v1/appointment/{uuid}/cancel` بعد از آزادسازی ظرفیت، لیست انتظار را خبر
|
||||
میکند و تعدادش را در `waitlist_notified` برمیگرداند. جزئیات لغو:
|
||||
[cancellation.md](cancellation.md)
|
||||
|
||||
## تستها
|
||||
|
||||
```bash
|
||||
ddev exec php bin/phpunit tests/Waitlist # ۹ تست
|
||||
```
|
||||
Reference in New Issue
Block a user