hamedandClaude Opus 5
fba1555f22
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>
3.5 KiB
Waitlist — لیست انتظار
اندپوینتهای src/Waitlist/*. «اگر وقتی در این بازه آزاد شد، خبرم کن» — توسعهٔ همان
ایدهٔ Appointment.is_reserve موجود، ولی با بازهٔ صریح و وضعیت.
چرا broadcast و نه صف انحصاری
ظرفیت آزادشده به حداکثر ده نفر خبر داده میشود و اولین رزروکننده میبرد.
صف انحصاری («فقط نفر اول ۳۰ دقیقه فرصت دارد») روی کاغذ عادلانهتر است، ولی در عمل یعنی وقتی که کسی جوابش را نمیدهد نیم ساعت قفل بماند و بعد به نفر دوم برسد — و ظرفیتی که دو ساعت مانده به نوبت آزاد شده، نیم ساعت وقتِ تلفکردنی ندارد.
در عوض متن پیامک اجباراً این را میگوید:
«یک وقت برای «X» در تاریخ Y آزاد شد. اولین نفری که رزرو کند آن را میگیرد.»
هر درخواست حداکثر سه بار خبر میگیرد؛ بدون سقف، یک بازهٔ پرلغو به منبع اسپم تبدیل میشود.
GET /api/v1/waitlist
| Query | Type | Description |
|---|---|---|
status |
string | waiting | notified | converted | expired |
{
"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
تستها
ddev exec php bin/phpunit tests/Waitlist # ۹ تست