hamedandClaude Opus 5
4d722830e3
Completes task 03. The resource calendar page edits weekly shifts, records leave and
maintenance, and previews two weeks of availability with a Persian reason for every
empty day — showing the raw server key ("outside_branch_hours") to a user would have
been a meaningless message. The preview is labelled raw on the page itself, because
booked appointments are not subtracted yet and mistaking it for bookable time leads
to overbooking.
The interval algebra moved to src/Shared/Time/TimeInterval.php with twelve unit
tests: tasks 05 and 06 need the same union/intersect/subtract, and a second
implementation is how two subtly different definitions of "overlap" get born. The
half-open [start, end) contract is what makes a shift ending at 13:00 and one
starting at 13:00 not overlap.
AvailabilityQueryCountTest locks the query count flat: one day and ninety days cost
exactly the same number of queries. Without it the first refactor can put a query
inside the day loop and a 90-day response quietly becomes hundreds of queries —
something only production would reveal.
app:resource:calendar:backfill derives shifts from existing WeeklySchedule sessions,
so the resources created in task 02 are not left with empty calendars. It skips any
resource a user has already configured, which is also what makes it idempotent. The
weekly schedule itself is untouched: this is a copy, not a migration.
Also added --replace to the holiday import. upsert keys on the date, so a row written
with a *wrong* date can never correct itself — re-running just creates the right row
beside the wrong one. That is exactly what happened after fixing the Jalali
conversion bug, and it was caught while capturing real responses for the docs.
Deferred with reasons recorded in the checklist: seasonal shift validity (two
nullable columns can be added later without backfill, so "needed from day one" does
not hold), and a Jalali date picker in the exception form.
1154 tests / 3229 assertions. phpstan at its 14-error baseline, none in touched
files. tsc clean, vitest 622 tests.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
129 lines
5.8 KiB
Markdown
129 lines
5.8 KiB
Markdown
# 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
|
||
|
||
```json
|
||
// 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.
|
||
|
||
```jsonc
|
||
// 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](auth.md) | Authentication — OTP, Login, JWT | 8 |
|
||
| [doctor.md](doctor.md) | Doctor profile & addresses | 11 |
|
||
| [clinic.md](clinic.md) | Clinics | 7 |
|
||
| [clinic-invitation.md](clinic-invitation.md) | Doctor invitations to clinics | 8 |
|
||
| [branch.md](branch.md) | Branches (= addresses), working hours, rooms | 8 |
|
||
| [resource.md](resource.md) | Resources, types, skills, pools | 16 |
|
||
| [resource-calendar.md](resource-calendar.md) | Resource calendars, exceptions, national holidays | 9 |
|
||
| [appointment.md](appointment.md) | Appointments & slot booking | 6 |
|
||
| [appointment-settings.md](appointment-settings.md) | Weekly schedule, date overrides, holidays | 14 |
|
||
| [payment.md](payment.md) | Payments (Mellat / Sep) | 5 |
|
||
| [settlement.md](settlement.md) | Wallet & settlement requests | 7 |
|
||
| [rating.md](rating.md) | Ratings, comments, likes | 9 |
|
||
| [secretary.md](secretary.md) | Doctor secretaries | 5 |
|
||
| [representation.md](representation.md) | Representations (agents) | 6 |
|
||
| [sms.md](sms.md) | SMS send & templates | 10 |
|
||
| [blog.md](blog.md) | Blog posts | 6 |
|
||
| [specialty.md](specialty.md) | Medical specialties | 5 |
|
||
| [insurance.md](insurance.md) | Insurances & doctor-insurance links | 10 |
|
||
| [doctor-service.md](doctor-service.md) | Doctor services | 5 |
|
||
| [tag.md](tag.md) | Blog tags | 5 |
|
||
| [location.md](location.md) | Provinces & cities | 10 |
|
||
| [user-profile.md](user-profile.md) | User medical profile | 4 |
|
||
| [admin.md](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 |
|