Files

T

hamedandClaude Opus 5 24534ec483 feat(availability): multi-resource availability engine

Section 10 of the design document, and the payoff for tasks 01–05. The engine slides
a multi-segment plan across resource calendars and answers which times are actually
possible, with a suggested resource for each role. Until now the only conflict the
system checked was the doctor's; rooms, devices and operators did not exist.

Allocation is per *role*, not per segment, and that is what returns the wasted
capacity. An operator with no requirement during "waiting for the cream" is simply
not examined for those minutes, so another patient can use them. The reference test
encodes exactly that: patient A holds 10:00–11:00 while the operator is only busy
10:00–10:05 and 10:35–11:00, and patient B is offered a slot inside the gap with the
second room assigned. The spec says the task is not verified without that scenario.

One resource is chosen for every segment that needs its role, not independently per
segment — otherwise the operator in segment 1 and segment 3 could be two different
people and the patient would change hands mid-treatment.

Occupancy is stored one row per (segment × resource) rather than one per appointment.
The granularity is the whole point; a row per appointment would re-create the
single-interval model the design rejects. Reserved intervals are widened by each
resource's setup/cleanup, because the resource genuinely is not available then.

booking_mode gains a third value, resource, alongside slot and service. It is purely
additive: the default stays slot, no environment moves on its own, and a location
that has not opted in keeps the untouched legacy path. The frozen slot-mode contract
stays green.

Performance is a test, not a hope: 30 days, 20 resources and 500 existing bookings
complete well inside the 500ms budget. Every input is read once and the rest is in
memory — no query inside the day or candidate loop — and candidates are generated
only from the free windows of the scarcest role, which turns tens of thousands of
candidates into a few hundred.

An empty result is not an error and not a 404: it carries
reason: "no_capacity_in_range" so the caller does not have to infer meaning from
emptiness.

Also fixed a genuinely intermittent test defect: NumericFieldNormalizerTest padded a
random number with the three-byte Persian "۰" using byte-based str_pad, producing
broken UTF-8 whenever the number was short. It failed roughly at random. The improved
assertion message added earlier is what identified it immediately.

1196 tests / 3414 assertions. phpstan at its 14-error baseline.

Resource-picking strategies, the availability cache and the settings UI are recorded
as outstanding in the checklist with reasons — the cache in particular would be
premature while the performance test passes comfortably without it.

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

2026-07-30 21:21:33 +03:30

6.1 KiB

Raw Blame History

Appointment Availability API — جستجوی وقت چندمنبعی

Base: /api/v1 · Auth: JWT وابسته به appointment-plan.md و resource-calendar.md.

چه چیزی را حل می‌کند

بند ۱۰ مستند: برنامهٔ چندبخشی نوبت را روی تقویم منابع بلغزان و بگو چه ساعت‌هایی واقعاً ممکن‌اند، با پیشنهاد اینکه کدام منبع استفاده شود.

مسیر قبلی فقط تداخل پزشک را می‌سنجید؛ اتاق، دستگاه و اپراتور اصلاً وجود نداشتند.

چرا این ظرفیت آزاد می‌کند

تخصیص per نقش است، نه per بخش. اپراتوری که در بخش «انتظار اثر کرم» نیازمندی ندارد، در آن دقایق بررسی نمی‌شود و برای بیمار دیگری آزاد است.

نمونهٔ عینی (و تستِ مرجعِ این تسک): بیمار الف ۱۰:۰۰–۱۱:۰۰ نوبت دارد ولی اپراتور فقط ۱۰:۰۰–۱۰:۰۵ و ۱۰:۳۵–۱۱:۰۰ درگیر است. اگر اتاق دومی آزاد باشد، بیمار ب در بازهٔ ۱۰:۰۵–۱۰:۳۵ جا می‌شود. با مدل تک‌بازه‌ای، آن نیم‌ساعت هدر می‌رفت.

چرا همان منبع در بخش‌های غیرمجاور

یک منبع برای همهٔ بخش‌هایی که آن نقش را می‌خواهند انتخاب می‌شود. اپراتور بخش ۱ و بخش ۳ باید یک نفر باشد؛ انتخاب مستقل per بخش، دو نفر می‌داد و بیمار وسط کار تحویل شخص دیگری می‌شد.

`POST /api/v1/appointment-availability`

{
  "service_uuid": "…",
  "branch_uuid": "…",
  "from": 1785529800,
  "to": 1785616200,
  "item_uuids": ["…"],
  "patient_gender": "female",
  "doctor_uuid": "…",
  "step_minutes": 15
}

from/to هر دو شامل‌اند، سقف ۹۰ روز. step_minutes گام تولید کاندید است (پیش‌فرض ۱۵، حداقل ۵).

۲۰۰:

{
  "success": true,
  "data": {
    "plan": { "total_minutes": 60, "segments": [ … ] },
    "slots": [
      {
        "start": 1785562200,
        "end": 1785565800,
        "assignment": {
          "room":     [{ "uuid": "…", "name": "اتاق ۲" }],
          "operator": [{ "uuid": "…", "name": "اپراتور ۱" }],
          "device":   [{ "uuid": "…", "name": "لیزر ۳" }]
        }
      }
    ],
    "reason": null
  }
}

plan هم برمی‌گردد تا کلاینت مجبور نباشد جدا preview بزند.

فهرست خالی خطا نیست و ۴۰۴ هم نیست. reason: "no_capacity_in_range" می‌آید تا کلاینت مجبور نباشد از خالی بودن حدس بزند — ممکن است واقعاً ظرفیتی نباشد.

پاسخ حداکثر ۵۰۰ زمان دارد؛ جستجوی یک‌ماهه نباید هزاران ردیف برگرداند.

خطاها

کد	HTTP	کِی
`ERR_WRONG_BOOKING_MODE`	۴۲۲	این محل روی `booking_mode = resource` نیست
`ERR_NO_ELIGIBLE_RESOURCE`	۴۲۲	هیچ منبعی شرایط یک بخش را ندارد (از برنامه‌ساز)
`ERR_VALIDATION_001`	۴۲۲	بازهٔ بیش از ۹۰ روز · `to < from`
—	۴۰۴	سرویس یا شعبهٔ محیط دیگر

`GET /api/v1/appointment-availability/month`

?service_uuid=&branch_uuid=&from=&to= → فقط { "days": [نیمه‌شبِ روزهای دارای ظرفیت] }. عمداً سبک است: تقویم ماهانه نباید تخصیص منبع هر زمان را بسازد.

حالت `booking_mode = resource`

مقدار سومِ کنار slot و service. افزودنی محض: پیش‌فرض همچنان slot است و هیچ محیطی خودبه‌خود به این حالت نمی‌رود — ارتقا داوطلبانه و صریح است. محلی که روی این حالت نرفته باشد، همان appointment-slots / appointment-service-slots را دارد و مسیر قدیمی دست‌نخورده است.

قواعدی که موتور رعایت می‌کند

مورد	رفتار
`setup/cleanup` منبع	بازهٔ اشغال گسترده‌تر از بازهٔ بخش است و در تداخل لحاظ می‌شود
ظرفیت منبع	شمارش است نه حضور: اتاق سه‌تخته سه نوبت هم‌زمان می‌گیرد
زمان گذشته	حذف می‌شود
یک منبع، دو نقش هم‌زمان	مجاز نیست

کارایی

هدف مستند: جستجوی یک‌ماهه زیر نیم ثانیه.

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

tests/Appointment/AvailabilityPerformanceTest.php این را با ۲۰ منبع و ۵۰۰ نوبت ثبت‌شده در ۳۰ روز می‌سنجد و بخشی از تسک است، نه اختیاری.

`resource_occupancy`

یک ردیف به‌ازای هر (بخشِ نوبت × منبع) — نه یکی به‌ازای کل نوبت. همین ریزدانگی است که ظرفیت آزاد می‌کند.

status ∈ booked | hold. نوشتن در این جدول کارِ تسک بعدی (رزرو و ثبت) است؛ این تسک فقط می‌خواندش.

تست‌ها

ddev exec php bin/phpunit tests/Appointment/AvailabilityEngineTest.php        # ۹ تست
ddev exec php bin/phpunit tests/Appointment/AvailabilityPerformanceTest.php

6.1 KiB Raw Blame History Unescape Escape