hamedandClaude Opus 5
e2e3e6b43b
A protocol says a course of a service runs over several sessions, when each
falls due, which doctor supervises it and which staff may perform it. The row
existing IS the "طول درمان" switch, so there is no separate boolean that could
disagree with the step list.
Each step's offset is measured from the previous session rather than from the
start of the course: laser spacing is a clinical requirement — hair regrows
relative to the last treatment — so a late patient shifts the rest of their
course instead of getting the next session early. That also lets one course use
uneven gaps, which a single min/ideal/max triple cannot express: a botox course
is session 1, then +15 days, then monthly.
Steps and staff are cleared and rewritten in two flushes inside a transaction.
A single flush sends inserts before deletes and the replacement row collides
with the unique (protocol, step_number) index — caught by the replace test.
Removes docs/api/course.md and the task-12 folder. They documented src/Course/,
a module deleted in 65d5831c whose commit message only mentions removing two
test files; that design is superseded by this one.
ServiceItem::$sessionCount is marked deprecated. It never had logic behind it
and session count now comes from the protocol; the column stays in payloads so
existing clients keep working.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
134 lines
6.3 KiB
Markdown
134 lines
6.3 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 |
|
||
| [practice-domain.md](practice-domain.md) | Practice domains — a clinic's field of practice | 3 |
|
||
| [treatment.md](treatment.md) | Treatment protocols — multi-session courses on a service | 3 |
|
||
| [clinic-invitation.md](clinic-invitation.md) | Doctor invitations to clinics | 8 |
|
||
| [resource.md](resource.md) | Resources, types, skills, pools | 16 |
|
||
| [resource-calendar.md](resource-calendar.md) | Resource calendars, exceptions, national holidays | 9 |
|
||
| [appointment-plan.md](appointment-plan.md) | Appointment segments and plan preview | 3 |
|
||
| [appointment-availability.md](appointment-availability.md) | Multi-resource availability search | 2 |
|
||
| [appointment-booking.md](appointment-booking.md) | Holds, confirmation and multi-resource occupancy | 4 |
|
||
| [pricing.md](pricing.md) | Date-ranged price lists and appointment invoices | 8 |
|
||
| [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 |
|