Files

T

hamedandClaude Opus 5 4395eea56e feat(booking): multi-resource holds and confirmation with a database-level guarantee

Section 11 and the third closing rule of the design document: preventing a double
booking is the database's job, not the code's. Any "is it free?" check in PHP has a
race window between the read and the write — two concurrent requests both see free
and both write.

MariaDB has no range EXCLUDE constraint, so every occupied interval is broken into
fixed five-minute buckets under UNIQUE(resource_id, bucket_at, seat). The code only
INSERTs; a rejection from the database *is* the answer. `seat` carries capacity: a
three-bed room has seats 0..2, allocation walks upward on each collision, and the
fourth concurrent hold finds nowhere to sit. Counting capacity in PHP would have
rebuilt the very race this removes.

Buckets are written through DBAL rather than the ORM on purpose: a unique violation
raised inside flush() closes the EntityManager, and the next seat attempt would then
fail with "EntityManager is closed", hiding the real outcome.

Occupancy is one row per (segment × resource). The reference test asserts the payoff
directly: for a 55-minute appointment of numbing / waiting / laser, the room gets
three rows and the operator only two — the operator holds nothing during the wait and
stays bookable for someone else.

A partial hold never survives. If the second resource has no room, the first is
released and the hold itself removed; otherwise a resource stays locked for an
appointment that will never exist.

Confirming does not re-reserve anything — the seats were taken at hold time and only
the label changes. Re-reserving on confirm would reopen the race the hold closed.
Cancelling marks rows `released` instead of deleting them, because the history of
which resource was busy when is the input to the utilisation reports; the uniqueness
buckets *are* deleted, or that interval would stay locked forever.

Expired holds are released by the existing scheduler rather than a new one. That
exposed a bug in my own change: the flush guard used $count, which now includes
released holds, so reset([]) could pass false to save(). It is guarded on $expired.

The appointment itself is still built with the existing constructor, so
active_slot_key, events and the payment path behave exactly as before — the
multi-resource occupancy sits beside them, not instead of them.

12 tests. Two matter most: the second hold on the same resource and interval getting
409, and a test that writes a duplicate bucket row over a *separate connection* and
expects the unique-key violation — if that one ever passes silently, the guarantee
had moved back into the code.

1208 tests / 3495 assertions. phpstan at its 14-error baseline. Frozen slot contract
green.

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

2026-07-31 09:28:55 +03:30

6.1 KiB

Raw Blame History

ClinicPro — API Documentation Index

Base URL: https://clinic-pro.ddev.site
API Prefix: /api/v1
Swagger UI: https://clinic-pro.ddev.site/api/doc — user: admin / pass: clinic123

Authentication

All protected endpoints require:

Authorization: Bearer <JWT_TOKEN>

Role	Description
`PUBLIC`	No token required
`AUTH`	Any valid JWT
`ROLE_ADMIN`	Admin user
`ROLE_DOCTOR`	Doctor user
`ROLE_CLINIC`	Clinic owner
`ROLE_SECRETARY`	Secretary

Standard Response Envelope

// Success
{ "success": true, "data": { ... } }

// Paginated
{ "success": true, "data": [...], "meta": { "totalRecords": 100, "totalPages": 5, "currentPage": 1, "limit": 20 } }

// Error
{ "success": false, "data": null, "errors": [{ "code": "ERR_XXX_000", "message": "..." }] }

meta.limit اندازهٔ صفحهٔ واقعاً اعمال‌شده است. ریپازیتوری‌ها limit درخواستی را به سقف خودشان کاهش می‌دهند (مثلاً لیست پزشکان: سقف ۵۰)، پس برای پیمایش کامل به meta.totalPages تکیه کن — نه به این فرض که «تعداد آیتم کمتر از limit درخواستی یعنی صفحهٔ آخر».

Persian digit normalization (global)

Persian (۰-۹) and Arabic (٠-٩) digits sent in numeric request fields are translated to Latin server-side, before the controller runs — src/Shared/EventSubscriber/NumericFieldNormalizerSubscriber.php. Every client benefits: the React admin panel, nobat724_front, and clinic-pro-tauri.

Applies to POST / PUT / PATCH requests under /api/v1/ with a JSON body, recursively through nested arrays.

Normalized keys:

mobile, mobile_number, telephone, phone, notification_mobile,
national_code, postal_code,
card_number, account_number, sheba, shaba, iban,
price_rials, amount_rials, amount, free_visit_price_rials,
insurance_price_rials, patient_share_rials, visit_price_rials,
duration_minutes, duration, commission_percent, coverage,
coverage_percent, franchise, ceiling, tax_percent,
base_insurance_discount_percent, supplementary_discount_percent

Only digits are translated — no characters are stripped, so IR in a sheba and - in a landline survive. Non-string values (int, bool, null) and keys outside the list are untouched, so a name like منشی شماره ۲ keeps its Persian digit.

// request
{ "mobile_number": "۰۹۱۲۳۴۵۶۷۸۹", "national_code": "۰۰۱۲۳۴۵۶۷۸", "name": "منشی شماره ۲" }

// what the controller sees
{ "mobile_number": "09123456789", "national_code": "0012345678", "name": "منشی شماره ۲" }

Adding a new numeric field to any endpoint? Add its key to NUMERIC_KEYS in the subscriber, otherwise Persian digits reach the database.

Modules

File	Domain	Endpoints
auth.md	Authentication — OTP, Login, JWT	8
doctor.md	Doctor profile & addresses	11
clinic.md	Clinics	7
clinic-invitation.md	Doctor invitations to clinics	8
branch.md	Branches (= addresses), working hours, rooms	8
resource.md	Resources, types, skills, pools	16
resource-calendar.md	Resource calendars, exceptions, national holidays	9
appointment-plan.md	Appointment segments and plan preview	3
appointment-availability.md	Multi-resource availability search	2
appointment-booking.md	Holds, confirmation and multi-resource occupancy	4
appointment.md	Appointments & slot booking	6
appointment-settings.md	Weekly schedule, date overrides, holidays	14
payment.md	Payments (Mellat / Sep)	5
settlement.md	Wallet & settlement requests	7
rating.md	Ratings, comments, likes	9
secretary.md	Doctor secretaries	5
representation.md	Representations (agents)	6
sms.md	SMS send & templates	10
blog.md	Blog posts	6
specialty.md	Medical specialties	5
insurance.md	Insurances & doctor-insurance links	10
doctor-service.md	Doctor services	5
tag.md	Blog tags	5
location.md	Provinces & cities	10
user-profile.md	User medical profile	4
admin.md	Admin dashboard & management	25+

Error Code Reference

Code	Message (FA)	HTTP
`ERR_AUTH_001`	توکن JWT منقضی یا نامعتبر	401
`ERR_AUTH_002`	کد OTP نامعتبر	401
`ERR_AUTH_003`	کد OTP منقضی شده	401
`ERR_AUTH_004`	تعداد تلاش‌های OTP به حد مجاز رسیده	429
`ERR_AUTH_005`	نام کاربری یا رمز عبور اشتباه	401
`ERR_AUTH_006`	دسترسی ممنوع	403
`ERR_VALIDATION_001`	ورودی نامعتبر	422
`ERR_VALIDATION_002`	فیلد الزامی وارد نشده	422
`ERR_NOT_FOUND_001`	منبع درخواستی یافت نشد	404
`ERR_CONFLICT_001`	تداخل: منبع در حال استفاده	409
`ERR_FORBIDDEN_001`	دسترسی به این منبع مجاز نیست	403
`ERR_PAYMENT_001`	درگاه پرداخت در دسترس نیست	503
`ERR_PAYMENT_002`	مبلغ پرداخت نامعتبر	422
`ERR_PAYMENT_003`	وضعیت نوبت برای پرداخت مناسب نیست	422
`ERR_FILE_001`	فرمت فایل مجاز نیست	422
`ERR_SMS_003`	تمپلیت قبلاً ارسال شده	422
`ERR_SECRETARY_001`	پلن فعلی اجازه منشی بیشتر نمی‌دهد	422
`ERR_RATE_LIMIT_001`	درخواست‌های زیاد، بعداً تلاش کنید	429

6.1 KiB Raw Blame History Unescape Escape