hamedandClaude Opus 4.8
7921407f33
Three related fixes, all rooted in the same flaw: authorization and scoping
decided by the caller's role instead of by the environment the data belongs to.
1. Single-appointment access (clinic operations were entirely broken)
AppointmentController::canView/canManage only knew the patient, the owning
doctor and admin -- appointment.clinic was never consulted. A clinic user could
create an appointment through /my/appointment but got 403 on detail, edit,
move, reserve transfer/replace and status change, so nearly every appointment
operation failed in clinic mode.
AppointmentAccessChecker now decides from appointment.clinic: clinic owner,
member doctor (via ClinicDoctorPermissionChecker) and assigned secretary (via
active context + DoctorSecretary) are recognised. Actions reuse the existing
permission vocabulary, so active=false remains the single source of truth for
"collaboration ended". Cancellation is gated separately and an inline status on
PATCH /appointment/{uuid} cannot bypass that gate. The patient is narrowed to
view + cancel.
Also fixed alongside: listByDoctor now serves a clinic manager but scoped to
that clinic; todayStats gained an admin branch and no longer passes an array of
doctor ids as the clinic parameter; PatientController::appointments filters on
appointment.clinic instead of current membership, so deactivating a doctor no
longer erases clinic appointment history from the case file.
The doctor-only active_slot_key was reviewed and deliberately left alone -- a
doctor is one physical person, so adding clinic to the key would permit
double-booking, not fix a bug. Reasoning recorded on the entity.
2. Appointment registration and confirmation
Panel-created appointments are born pending ("ثبت شده") instead of confirmed.
Confirming is now an explicit act: POST /appointment/{uuid}/confirm transitions
the status, files the case file for the appointment's environment (reusing an
existing record or creating one) and registers full or partial payments on the
resulting visit -- all in one transaction.
AppointmentExpiryService would have expired those pending appointments the
moment their slot time passed; findExpiredPending is now limited to online
gateway holds, which are the only pendings carrying a TTL. A pending
appointment still occupies its slot, so the time stays reserved.
The admin panel gets a "قطعی کردن نوبت" modal showing the visit fee, each
selected service, the total, and paid/remaining/status. It is wired inside
AppointmentStatusDropdown, so picking "confirmed" anywhere (timeline, detail,
reserve list, info modal) goes through it and confirmation can never silently
skip the case file and payment.
3. Clinic case-file access
PatientRecordScopeResolver replaces the single-destination role mapping: the
active context decides, so a doctor invited into a clinic finally sees their
patients' records there. A clinic record is per-patient and shared by design,
so "their own patients" is derived from appointments with that doctor in that
clinic rather than from a new column. Clinic secretaries are limited to their
assigned doctors. Read and write share one rule, and out-of-scope records
report 404 so other environments are never disclosed.
Tests: 29 new cases across the three areas (clinic appointment access, confirm
flow, clinic record access). Full suite 466 tests, 2 pre-existing failures
unchanged. API docs updated for all three.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 } }
// Error
{ "success": false, "data": null, "errors": [{ "code": "ERR_XXX_000", "message": "..." }] }
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_KEYSin 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 |
| 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 |