Files

T

hamedandClaude Opus 5 22c89fbae4 feat(plan): multi-segment appointments with per-segment resource requirements

Section 7 of the design document, and the reason the whole resource layer exists.
A laser session is not one block: numbing cream (5 min, room + operator), waiting for
it to work (30 min, room only), the laser itself (20 min, room + operator + device),
aftercare (5 min, room + operator). Under the single-interval model the operator is
locked for all 60 minutes while actually working 30 — half the capacity thrown away.

AppointmentPlanBuilder turns (service, selected items, branch, patient) into a plan:
segments with offsets, durations and resource requirements. It deliberately assigns
no absolute time and no specific resource — that is the next task. This only produces
the *shape* of the appointment.

Segment duration comes from one of two sources. A fixed segment carries its own
number; an item-driven one gets its duration from task 04's DurationCalculator, so
"the laser itself" grows with two treated areas while "waiting for the cream" does
not. One number could not have expressed that.

Three contracts worth stating:

- A service with no segment templates falls back to a single continuous segment
  requiring the doctor resource — exactly today's behaviour. Without it every
  existing service would have become unplannable overnight.
- A segment with no requirements is valid: "waiting at home" consumes time but
  occupies nothing.
- same_gender_as_patient with an unknown patient gender is a 422, not a silently
  dropped requirement. Dropping it quietly would route the patient to a resource the
  clinic said must not serve them.

When no resource qualifies, the error names the role, the skill and the branch —
"no female operator with the skill «Alexandrite laser» is available at «Central»" —
rather than an empty result the caller has to interpret (section 10).

occupancy_offset carries each requirement's setup/cleanup minutes for the availability
engine. It is taken as the maximum across candidates, because the builder does not yet
know which resource will be picked and under-reserving means the next appointment
lands on top of the cleanup.

11 tests covering the document's reference example (offsets 0/5/35/55, total 60),
item-driven scaling, the no-template fallback, all three gender-constraint outcomes,
merging and both caps. 1186 tests overall. phpstan back at its 14-error baseline;
slot-mode frozen contract green.

The admin segments page is not built; the checklist records it with a target. The
backend and preview endpoint are complete and consumable without it.

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

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

5.9 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.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

5.9 KiB Raw Blame History Unescape Escape