hamed/clinicpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b659b84a7f44ae67e7c7612d46a5c564843a4302
clinicpro/docs/api/appointment-settings.md
T
hamedandClaude Opus 4.8 c103c393f3 feat(appointment-settings): let clinics manage each member doctor's booking 
The API and React components were already parameterized by doctor uuid, but 14
copy-pasted identity checks limited every endpoint to "the doctor themselves or
an admin", so a clinic owner could not touch a member doctor's booking setup.

- Replaces those 14 checks with one denyDoctorAccess() that also admits the
  owner of a clinic the doctor belongs to, and a member doctor holding the
  clinic's appointment_settings permission (view for GET, update for writes).
  A doctor's own settings short-circuit before any permission lookup.
- Moves ScheduleSection and its tabs out of DoctorDetailPage into
  components/schedule/ScheduleSection.tsx so the doctor panel and the new
  clinic page render the same module instead of one page importing another.
  Pure relocation — no logic changed.
- Adds ClinicAppointmentSettingsPage: one tab per clinic doctor, each rendering
  that same section. The tab wrapper is keyed by doctor uuid so in-progress
  schedule edits cannot leak onto the wrong doctor.
- insurance-pricing accepts an optional doctor_uuid (query on GET, body on PUT)
  under the same access rule, so the visit-price card works inside the clinic
  tabs. Fixes saveInsurancePricing calling getInsurancePricing with the wrong
  argument by extracting the shared pricingPayload().

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-18 10:02:27 +03:30

19 KiB
Raw Blame History

Appointment Settings API

Prefix: /api/v1/appointment-settings
Permission: every endpoint requires AUTH and resolves access through one shared rule (below)

Doctors configure their availability via three resources: weekly schedule, date overrides, and holidays.

Access rule

All 14 endpoints in this file share a single check. Given the target doctor (resolved from the path/body uuid, or from the parent schedule/override/holiday), access is granted when the caller is:

  1. ROLE_ADMIN, or
  2. the doctor themselves, or
  3. the owner of a clinic the doctor belongs to, or
  4. a doctor member of that clinic holding the appointment_settings permission — view for GET, update for POST/PATCH/DELETE (see docs/api/clinic.md → Clinic Doctor Permissions)

Anything else → 403 ERR_AUTH_006. This is what lets the clinic panel manage every member doctor's booking settings from تنظیمات → نوبت‌دهی, one tab per doctor, using the same endpoints the doctor's own panel calls.

A doctor's own settings are never affected by clinic permissions — rule 2 short-circuits before any permission lookup.

Weekly Schedule

Each doctor has one weekly schedule (upsert). The schedule is keyed by day index (0=Saturday ... 6=Friday), each day containing a sessions array.

Day Index Convention

Index Day (EN) Day (FA)
"0" Saturday شنبه
"1" Sunday یکشنبه
"2" Monday دوشنبه
"3" Tuesday سه‌شنبه
"4" Wednesday چهارشنبه
"5" Thursday پنجشنبه
"6" Friday جمعه

POST /api/v1/appointment-settings/weekly-schedule

Create or update the weekly schedule for a doctor (upsert).

Permission: AUTH — see Access rule

الزام آدرس: هر session با active=true باید location_id (آدرس مطب/کلینیک) داشته باشد. در غیر این صورت 422 ERR_VALIDATION_001 («برای هر شیفت فعال باید آدرس انتخاب شود»). این آدرس هنگام رزرو خودکار روی نوبت ذخیره می‌شود.

Request Body (application/json)

{
  "doctor_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "schedule": {
    "0": {
      "sessions": [
        {
          "active": true,
          "location_id": 1973,
          "start_time": "09:00",
          "end_time": "13:00",
          "duration_per_patient": 20,
          "has_rest": true,
          "rest_interval": 60,
          "time_to_rest": 10,
          "patient_limit": null
        },
        {
          "active": true,
          "location_id": 1973,
          "start_time": "15:00",
          "end_time": "18:00",
          "duration_per_patient": 20,
          "has_rest": false,
          "rest_interval": 0,
          "time_to_rest": 0,
          "patient_limit": 5
        }
      ]
    },
    "1": { "sessions": [] },
    "2": { "sessions": [] },
    "3": { "sessions": [] },
    "4": { "sessions": [] },
    "5": { "sessions": [] },
    "6": { "sessions": [] }
  }
}
Field Type Required Description
doctor_uuid string (UUID) ✅ Doctor UUID
schedule object ✅ Keys "0" through "6" (day indices)
schedule.{n}.sessions array ✅ Array of session config objects
meta object ❌ Online-booking settings (see below)

Online-booking meta object:

{
  "meta": {
    "online_booking_enabled": true,
    "booking_window_value": 2,
    "booking_window_unit": "month",
    "booking_mode": "service",
    "buffer_minutes": 5
  }
}
Field Type Required Description
online_booking_enabled boolean ❌ false = no online booking; the public slot/month endpoints return no availability
booking_window_value integer ❌ How far ahead patients may book (≥ 1)
booking_window_unit string ❌ "week" or "month"
booking_mode string ❌ "slot" (پیش‌فرض) = نوبت‌دهی اسلاتی با مدت ثابت (duration_per_patient). "service" = مدت هر نوبت از duration_minutes سرویسِ انتخاب‌شده؛ زمان‌ها با GET /api/v1/appointment-service-slots گرفته می‌شوند. مقدار نامعتبر نادیده گرفته می‌شود
buffer_minutes integer ❌ فقط حالت سرویسی: فاصلهٔ بین نوبت‌ها (دقیقه، ≥ 0). در slot_end ذخیره نمی‌شود؛ فقط فاصلهٔ بین زمان‌های پیشنهادی

Defaults when meta is absent: { online_booking_enabled: true, booking_window_value: 1, booking_window_unit: "month", booking_mode: "slot", buffer_minutes: 0 }. meta is stored inside the schedule setting JSON (no DB migration) and is preserved when only schedule is sent. SlotCalculatorService rejects any date in the past, beyond today + value unit, or when online booking is disabled — for the weekly schedule, date overrides, and appointment-slots alike.

اجبار حالت سرویسی: اگر booking_mode = service ذخیره شود ولی پزشک هیچ سرویسِ «نمایش در نوبت‌دهی» (bookable = true) نداشته باشد، POST/PATCH برنامهٔ هفتگی با 422 (ERR_VALIDATION_001, field booking_mode) رد می‌شود.

غیرقابل‌تغییر پس از ثبت: booking_mode فقط تا اولین ثبت قابل‌انتخاب است. پس از آنکه یک‌بار به‌صورت صریح ذخیره شد (در setting.meta.booking_mode نوشته شد)، هر POST/PATCH که آن را تغییر دهد با 422 («نوع نوبت‌دهی پس از ثبت قابل تغییر نیست»، field booking_mode) رد می‌شود. پاسخِ toArray فیلد boolean booking_mode_locked را برمی‌گرداند (true = قفل‌شده) تا پنل توگل را غیرفعال کند. رکوردهای قدیمی که هنوز mode صریح ندارند، booking_mode_locked=false و یک‌بار قابل‌انتخاب‌اند.

Session Config Object:

Field Type Required Description
active boolean ✅ Whether this session is active
location_id integer|null ❌ Doctor address/location ID
start_time string ✅ Session start "HH:MM"
end_time string ✅ Session end "HH:MM"
duration_per_patient integer ✅ Minutes per appointment slot
has_rest boolean ❌ Whether to insert rest breaks
rest_interval integer ❌ Work minutes before taking a rest break
time_to_rest integer ❌ Duration of each rest break (minutes)
patient_limit integer|null ❌ Max patients per session (null = unlimited)

Multiple sessions per day are supported (e.g., morning + afternoon). Sessions are sorted by start_time and overlapping ones are skipped.

Response 201

{
  "success": true,
  "data": {
    "data": {
      "uuid": "sched-uuid-...",
      "doctor_uuid": "550e8400-...",
      "schedule": {
        "0": { "sessions": [ { "active": true, "start_time": "09:00", ... } ] },
        "1": { "sessions": [] },
        "2": { "sessions": [] },
        "3": { "sessions": [] },
        "4": { "sessions": [] },
        "5": { "sessions": [] },
        "6": { "sessions": [] }
      },
      "meta": {
        "online_booking_enabled": true,
        "booking_window_value": 1,
        "booking_window_unit": "month",
        "booking_mode": "slot",
        "buffer_minutes": 0
      },
      "booking_mode_locked": true,
      "created_at": 1717000000,
      "updated_at": 1717000000
    }
  }
}

⚠️ Double-nested: Frontend extracts with data?.data?.data
This is an upsert — if a schedule already exists for the doctor, it is overwritten.

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_VALIDATION_002 404 Doctor not found
ERR_AUTH_006 403 Not the doctor owner

GET /api/v1/appointment-settings/weekly-schedule/{uuid}

Get weekly schedule. {uuid} can be either the schedule UUID or the doctor UUID — the controller tries both.

Permission: AUTH (class-level IS_AUTHENTICATED_FULLY)

Response 200

Same structure as POST response.

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_VALIDATION_002 404 Schedule not found

PATCH /api/v1/appointment-settings/weekly-schedule/{uuid}

Update weekly schedule. {uuid} can be schedule UUID or doctor UUID.

Permission: AUTH — see Access rule

Request Body

{
  "schedule": {
    "0": {
      "sessions": [
        {
          "active": true,
          "location_id": 1973,
          "start_time": "10:00",
          "end_time": "14:00",
          "duration_per_patient": 30,
          "has_rest": false,
          "rest_interval": 0,
          "time_to_rest": 0,
          "patient_limit": null
        }
      ]
    }
  }
}

Replaces the entire schedule object if provided.

Response 200

Updated schedule object (same structure as POST).

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_AUTH_006 403 Not the doctor owner
ERR_VALIDATION_002 404 Schedule not found

DELETE /api/v1/booking-setting/{uuid}

Delete a weekly schedule.

Permission: AUTH — see Access rule

Note: route is /booking-setting/, not /appointment-settings/

Response 200

{ "success": true, "data": { "message": "برنامه هفتگی با موفقیت حذف شد" } }

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_AUTH_006 403 Not the doctor owner
ERR_VALIDATION_002 404 Schedule not found

Date Overrides

Override a specific date — mark it inactive (day off) or give it custom sessions.

GET /api/v1/appointment-settings/date-override/list/{doctorUuid}

Get all date overrides for a doctor.

Permission: AUTH — see Access rule (403 ERR_AUTH_006 otherwise).

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "uuid": "...",
        "doctor_uuid": "...",
        "date": 1718476800,
        "active": false,
        "reason": "تعطیل خاص",
        "custom_slots": [],
        "created_at": 1717000000
      }
    ]
  }
}

date is a Unix timestamp. active: false = entire day blocked. active: true with custom_slots = custom session schedule.

POST /api/v1/appointment-settings/date-override

Create a date override.

Permission: AUTH — see Access rule

Request Body

{
  "doctor_uuid": "550e8400-...",
  "date": "2024-06-20",
  "active": false,
  "reason": "تعطیل رسمی",
  "custom_slots": null
}
Field Type Required Description
doctor_uuid string (UUID) ✅ Doctor UUID
date string ✅ Date in Y-m-d format (e.g. "2024-06-20")
active boolean ❌ false = full day off (default); true = use custom_slots
reason string ❌ Reason for override
custom_slots array|null ❌ Custom sessions (same SessionConfig format as weekly schedule, see below)

custom_slots format when active: true:

{
  "custom_slots": [
    {
      "start_time": "14:00",
      "end_time": "18:00",
      "duration_per_patient": 20,
      "location_id": 1973,
      "has_rest": false,
      "rest_interval": 0,
      "time_to_rest": 0,
      "patient_limit": null
    }
  ]
}

Legacy format (backward compatible):

{
  "custom_slots": [
    { "start": "14:00", "end": "18:00", "duration": 20 }
  ]
}

Response 201

{
  "success": true,
  "data": {
    "data": {
      "uuid": "override-uuid-...",
      "doctor_uuid": "...",
      "date": 1718476800,
      "active": false,
      "reason": "تعطیل رسمی",
      "custom_slots": [],
      "created_at": 1717000000
    }
  }
}

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_AUTH_006 403 Not the doctor owner
ERR_VALIDATION_002 404 Doctor not found
ERR_VALIDATION_001 422 Invalid date format

GET /api/v1/appointment-settings/date-override/{uuid}

Get a single date override.

Permission: AUTH (class-level)

Response 200

Override object (same structure as above).

PATCH /api/v1/appointment-settings/date-override/{uuid}

Update a date override.

Permission: AUTH — see Access rule

Request Body (all optional)

{
  "active": true,
  "reason": "جبران مرخصی",
  "custom_slots": [
    {
      "start_time": "14:00",
      "end_time": "18:00",
      "duration_per_patient": 20,
      "location_id": 1973,
      "has_rest": false,
      "rest_interval": 0,
      "time_to_rest": 0,
      "patient_limit": null
    }
  ],
  "date": "2024-06-21"
}

Response 200

Updated override object.

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_AUTH_006 403 Not the doctor owner
ERR_VALIDATION_002 404 Override not found

DELETE /api/v1/appointment-settings/date-override/{uuid}

Delete a date override.

Permission: AUTH — see Access rule

Response 200

{ "success": true, "data": { "message": "Override با موفقیت حذف شد" } }

Holidays

Mark a date range as holiday — all slots blocked, no overrides apply.

GET /api/v1/appointment-settings/holidays/list/{doctorUuid}

Get all holidays for a doctor.

Permission: AUTH — see Access rule (403 ERR_AUTH_006 otherwise).

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "uuid": "...",
        "doctor_uuid": "...",
        "start_date": 1719792000,
        "end_date": 1720656000,
        "reason": "تعطیلات تابستانی",
        "active": true,
        "created_at": 1717000000
      }
    ]
  }
}

start_date and end_date are Unix timestamps. Holidays take highest priority — they block the day even if a date override exists.

POST /api/v1/appointment-settings/holidays

Create a holiday range.

Permission: AUTH — see Access rule

Request Body

{
  "doctor_uuid": "550e8400-...",
  "start_date": "2024-07-01",
  "end_date": "2024-07-10",
  "reason": "تعطیلات تابستانی"
}
Field Type Required Description
doctor_uuid string (UUID) ✅ Doctor UUID
start_date string ✅ Start date Y-m-d
end_date string ✅ End date Y-m-d (must be ≥ start_date)
reason string ❌ Holiday reason

Response 201

{
  "success": true,
  "data": {
    "data": {
      "uuid": "holiday-uuid-...",
      "doctor_uuid": "...",
      "start_date": 1719792000,
      "end_date": 1720656000,
      "reason": "تعطیلات تابستانی",
      "active": true,
      "created_at": 1717000000
    }
  }
}

Errors

Code HTTP Description
ERR_AUTH_001 401 Missing token
ERR_AUTH_006 403 Not the doctor owner
ERR_VALIDATION_002 404 Doctor not found
ERR_VALIDATION_001 422 end_date before start_date or invalid format

GET /api/v1/appointment-settings/holidays/{uuid}

Get a single holiday.

Permission: AUTH (class-level)

PATCH /api/v1/appointment-settings/holidays/{uuid}

Update a holiday.

Permission: AUTH — see Access rule

Request Body (all optional)

{
  "start_date": "2024-07-02",
  "end_date": "2024-07-12",
  "reason": "تمدید تعطیلات",
  "active": false
}

Response 200

Updated holiday object.

DELETE /api/v1/appointment-settings/holidays/{uuid}

Delete a holiday.

Permission: AUTH — see Access rule

Response 200

{ "success": true, "data": { "message": "تعطیلات حذف شد" } }

Slot Calculation Logic (Reference)

The SlotCalculatorService calculates available slots in this priority order:

  1. Holiday — if date falls in a holiday range → return empty (no slots)
  2. Date Override — if a date override exists for this date:
    • active: false → return empty
    • active: true → use custom_slots sessions
  3. Weekly Schedule — use the day's sessions array (only active: true sessions, sorted by start_time, overlapping sessions skipped)

Slot output format:

[
  {
    "start": 1718438400,
    "end": 1718439600,
    "start_time": "09:00",
    "end_time": "09:20",
    "location_id": 1973
  }
]

Available Locations

GET /api/v1/appointment-settings/available-locations/{doctorUuid}

Permission: AUTH — see Access rule (403 ERR_AUTH_006 otherwise).

Returns all locations a doctor can assign as location_id in their schedule sessions. Includes both the doctor's personal addresses and the addresses of all clinics they belong to.

Response 200

{
  "success": true,
  "data": [
    {
      "id": "5",
      "uuid": "...",
      "type": "personal",
      "clinic_id": null,
      "clinic_name": null,
      "name": "مطب شخصی",
      "address": "تهران، ...",
      "telephone": "09121234567",
      "map": { "latitude": "35.7", "longitude": "51.4" },
      "city": { "id": "1", "name": "تهران" },
      "province": { "id": "8", "name": "تهران" }
    },
    {
      "id": "12",
      "uuid": "...",
      "type": "clinic",
      "clinic_id": "3",
      "clinic_name": "کلینیک نور",
      "name": "شعبه مرکزی",
      "address": "تهران، خیابان ولیعصر...",
      "telephone": "02112345678",
      "map": { "latitude": "35.699", "longitude": "51.337" },
      "city": { "id": "1", "name": "تهران" },
      "province": { "id": "8", "name": "تهران" }
    }
  ]
}
Field Description
type personal = doctor's own address; clinic = clinic address
clinic_id ID of the clinic (only for type=clinic)
clinic_name Name of the clinic (only for type=clinic)

Use id as the location_id value in weekly schedule sessions or date override sessions.

Errors

Code HTTP Description
ERR_VALIDATION_002 404 Doctor not found
Reference in New Issue View Git Blame Copy Permalink