Files

T

hamedandClaude Opus 5 584ea4067f feat(policy): six-category policy engine wired into the booking flow

Rules become data instead of code: a clinic can say "laser under 18 requires
parental consent" without a deploy.

Engine
- Policy / PolicyVersionLog entities, closed field/operator/effect lists per
  category (PolicySchema), condition validation at write time
- PolicyResolver: priority -> specificity -> age, combining effects by
  veto / max / sum / union
- A missing fact fails its clause instead of silently passing it
- Policies are drafts until activated, and are versioned rather than edited

Wiring
- selection -> ServiceSelectionValidator
- eligibility + spacing -> BookingPolicyGuard, at hold time not confirm time
- resource + timing -> AppointmentPlanBuilder, including template-less services
- pricing -> PricingEngine, alongside (not replacing) the manual discount

The condition column is named condition_json: `condition` is a MariaDB keyword
and broke every INSERT.

Tests: 17 in tests/Policy including NoPolicyRegressionTest, which pins that a
clinic with no policies sees byte-identical output to task 08.
Docs: docs/api/policy.md (real captured JSON) + docs/architecture/policy-engine.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-31 10:19:19 +03:30

8.1 KiB

Raw Blame History

Appointment Booking API — رزرو موقت و ثبت نهایی چندمنبعی

Base: /api/v1 · Auth: JWT دنبالهٔ appointment-availability.md.

سه مرحله

جستجو  →  رزرو موقت (hold)  →  ثبت نهایی (confirm)

مرحلهٔ میانی لازم است چون بین دیدن یک زمان و ثبتش، فاصله هست: بیمار فرم پر می‌کند، پرداخت می‌کند، مردد می‌شود. بدون رزرو موقت، همان زمان به چند نفر پیشنهاد می‌شود و آخری خطا می‌گیرد.

چرا تضمین در دیتابیس است، نه در کد

قانون سوم جمع‌بندی مستند: «جلوگیری از رزرو تکراری کار دیتابیس است، نه کار کد.»

هر بررسیِ «آیا آزاد است؟» در PHP یک پنجرهٔ مسابقه بین خواندن و نوشتن دارد؛ دو درخواست هم‌زمان هر دو «آزاد» می‌بینند و هر دو می‌نویسند.

MariaDB قید EXCLUDE بازه‌ای ندارد، پس هر بازهٔ اشغال به سطل‌های ثابت پنج‌دقیقه‌ای شکسته می‌شود و کلید یکتای زیر تداخل را غیرممکن می‌کند:

UNIQUE (resource_id, bucket_at, seat)

کد فقط INSERT می‌زند؛ اگر دیتابیس ردش کرد، همان یعنی «گرفته شده».

seat ظرفیت را بیان می‌کند. اتاق سه‌تخته صندلی‌های ۰ تا ۲ دارد؛ تلاش از صندلی ۰ شروع می‌شود و با هر برخورد یکی جلو می‌رود. چهارمین رزروِ هم‌زمان جایی برای نشستن پیدا نمی‌کند و 409 می‌گیرد. شمردن ظرفیت در PHP دقیقاً همان مسابقه‌ای را می‌ساخت که این طراحی حذفش می‌کند.

`POST /api/v1/appointment-hold`

{
  "service_uuid": "…",
  "branch_uuid": "…",
  "start": 1785562200,
  "item_uuids": ["…"],
  "patient_gender": "female",
  "assignment": { "room": ["…"], "operator": ["…"], "device": ["…"] }
}

assignment همان چیزی است که جستجوی وقت پیشنهاد داده. هر نیازمندی باید منبع داشته باشد؛ وگرنه 422 — رزروی که نصف منابع لازم را بگیرد، هنگام حضور بیمار کم می‌آورد.

۲۰۱:

{
  "success": true,
  "data": {
    "hold_uuid": "…",
    "starts_at": 1785562200,
    "ends_at": 1785565800,
    "expires_at": 1785563100,
    "confirmed": false,
    "assignment": { "room": [{ "uuid": "…", "name": "اتاق ۲" }] }
  }
}

مهلت ۹۰۰ ثانیه است — همان مهلتی که پرداخت نوبت دارد؛ دو عدد متفاوت یعنی دو حقیقت متفاوت.

بلافاصله پس از رزرو، POST /appointment-availability آن زمان را دیگر برنمی‌گرداند.

۴۰۹ ERR_SLOT_TAKEN: منبع در آن بازه ظرفیت خالی ندارد. ۴۲۲: نبودِ منبع برای یک نقش · assignment خالی. ۴۰۴: سرویس، شعبه یا منبع محیط دیگر.

رزرو نیمه‌کاره نمی‌ماند. اگر منبع دوم جا نداشت، منبع اول هم آزاد می‌شود و خودِ رزرو حذف — وگرنه منبعی قفل می‌ماند که هرگز نوبتی رویش ثبت نمی‌شود.

`DELETE /api/v1/appointment-hold/{uuid}`

آزادسازی زودهنگام؛ آن زمان بلافاصله دوباره در جستجو ظاهر می‌شود. رزروی که ثبت نهایی شده آزاد نمی‌شود (422).

`POST /api/v1/appointment-confirm`

{ "hold_uuid": "…", "doctor_uuid": "…", "patient_uuid": "…" }

patient_uuid اختیاری است؛ نبودش یعنی خودِ کاربر (منشی می‌تواند برای دیگری ثبت کند).

۲۰۰: appointment_uuid + بازه + تخصیص.

تبدیل hold → booked هیچ منبعی را دوباره نمی‌گیرد: صندلی‌ها از لحظهٔ رزرو موقت گرفته شده‌اند و اینجا فقط برچسبشان عوض می‌شود. اگر ثبت نهایی دوباره رزرو می‌کرد، همان پنجرهٔ مسابقه‌ای که رزرو موقت حذفش کرده بود برمی‌گشت.

۴۰۹ ERR_HOLD_EXPIRED روی رزروِ منقضی · ۴۰۹ ERR_SLOT_TAKEN روی رزروِ قبلاً ثبت‌شده · ۴۰۴ روی رزرو کاربر دیگر (نه ۴۰۳ — وجودش نباید لو برود).

`POST /api/v1/appointment/{uuid}/rebook`

جابه‌جایی: اول رزرو جدید، بعد آزادسازی قدیم. ترتیب عمدی است — اگر رزرو جدید شکست بخورد، نوبت قدیمی دست‌نخورده می‌ماند و بیمار بی‌نوبت نمی‌شود.

اشغال: یک ردیف per (بخش × منبع)

نه یکی per نوبت. همین ریزدانگی ظرفیت آزاد می‌کند.

مثال واقعی (و تستِ مرجع): نوبت ۵۵ دقیقه‌ای با بخش‌های بی‌حسی ۵ · انتظار ۳۰ · لیزر ۲۰:

منبع	تعداد ردیف اشغال
اتاق	۳ — هر سه بخش
اپراتور	۲ — فقط بی‌حسی و لیزر

اپراتور در بازهٔ انتظار هیچ ردیفی ندارد و برای بیمار دیگری آزاد است.

بازهٔ ثبت‌شده گسترده‌تر از بازهٔ بخش است: زمان آماده‌سازی و تمیزکاری منبع هم درونش می‌آید.

`status`

مقدار	یعنی
`hold`	رزرو موقت، تا پایان مهلت
`booked`	نوبت قطعی
`released`	لغو یا منقضی

لغو، ردیف را حذف فیزیکی نمی‌کند. تاریخچهٔ اینکه چه منبعی کِی گرفته شده بود ورودی گزارش بهره‌وری است؛ حذفش یعنی پاک کردن همان چیزی که قرار است اندازه بگیریم. ولی سطل‌های یکتایی حذف می‌شوند، وگرنه آن زمان برای همیشه قفل می‌ماند.

تور ایمنی دوگانه

نوبت با همان سازندهٔ موجود ساخته می‌شود، پس active_slot_key، رویدادها و مسیر پرداخت دقیقاً مثل قبل کار می‌کنند. اشغال چندمنبعی کنار آن می‌نشیند، نه به‌جایش.

تست‌ها

ddev exec php bin/phpunit tests/Appointment/HoldAndBookTest.php   # ۱۲ تست

دو تست از همه مهم‌ترند: رزرو دوم روی همان منبع و بازه که 409 می‌گیرد، و تستی که مستقیم روی یک اتصال جدا ردیف تکراری می‌نویسد و انتظار نقض کلید یکتا دارد — اگر آن یکی بشکند، یعنی تضمین فقط در کد بوده است.

قوانین وابسته به بیمار

POST /api/v1/appointment-hold پیش از گرفتن صندلی دو دسته را اجرا می‌کند:

دسته	خطا	معنی
`eligibility`	`ERR_VALIDATION_001` / `422`	قانونی این بیمار را برای این خدمت رد کرده
`eligibility` (`require_flag`)	`ERR_VALIDATION_002` / `422`	پرچمی مثل `has_parental_consent` در بدنه نیامده
`spacing`	`ERR_VALIDATION_001` / `422`	فاصله تا نوبت قبلیِ همان دستهٔ کاتالوگ کمتر از `min_days_between` است

جای اجرا عمداً لحظهٔ رزرو موقت است نه ثبت نهایی: شنیدن «واجد شرایط نیستید» بعد از ده دقیقه نگه‌داشتن صندلی، هم وقت بیمار را تلف می‌کند هم صندلی را.

جزئیات: policy.md

8.1 KiB Raw Blame History