clinicpro/docs/tasks/task-05-doctor/task.md

تسک ۰۵: ماژول دکتر

توضیح

پیاده‌سازی مدیریت پروفایل دکترها، لیست دکترها با فیلتر، آپلود تصویر پروفایل و مدیریت آدرس‌های مطب.

Endpoint ها (واقعی از Drupal)

متد	مسیر	توضیح	نیاز به Auth
POST	/api/v1/doctor	ایجاد پروفایل دکتر	بله
PATCH	/api/v1/doctor/{uuid}	ویرایش پروفایل دکتر	بله (Owner/Admin)
DELETE	/api/v1/doctor/{uuid}	حذف دکتر	بله (Admin)
GET	/api/v1/doctor/{uuid}	دریافت پروفایل کامل دکتر	خیر
GET	/api/v1/doctors	لیست دکترها با فیلتر	خیر
POST	/file/upload/clinic_pro/doctor/field_image	آپلود تصویر پروفایل دکتر	بله
GET	/api/v1/clinic/doctor-list/{clinic_uuid}	لیست دکترهای یک کلینیک	خیر
POST	/api/v1/clinic-pro/doctor-address	ایجاد آدرس مطب	بله
PATCH	/api/v1/clinic-pro/doctor-address/{id}	ویرایش آدرس	بله
DELETE	/api/v1/clinic-pro/doctor-address/{id}	حذف آدرس	بله
GET	/api/v1/clinic-pro/doctor-address/{id}	دریافت یک آدرس	بله
GET	/api/v1/clinic-pro/doctor-addresses/{doctorId}	لیست آدرس‌های دکتر	خیر

پیش‌نیازها

• تسک ۰۱، ۰۲، ۰۸ (Categories برای تخصص و سرویس‌ها)

زمان تخمینی

۸ تا ۱۰ ساعت

---

نمونه واقعی Response — GET /api/v1/doctor/{uuid}

{
  "id": "29",
  "uuid": "61be915b-595a-42e5-bca5-f80d22f4f14a",
  "name": "single doctor",
  "gender": "woman",
  "experience": 21,
  "activity_time": "1107808200",
  "medical_system_code": "121212121212",
  "detail": "test",
  "degree": "specialist",
  "specialties": [
    {
      "uuid": "d60a269d-f7d7-4589-8eab-451e6f740d40",
      "id": "603",
      "name": "داخلی عمومی",
      "parent": "602"
    }
  ],
  "img": [
    {
      "url": "https://domain.com/sites/default/files/doctors/2025-11/image.png",
      "fid": "98",
      "filename": "image.png",
      "filemime": "image/png",
      "filesize": 173665
    }
  ],
  "expertise": [
    { "uuid": "...", "id": "1601", "name": "معاینه و تشخیص پزشک متخصص" },
    { "uuid": "...", "id": "1602", "name": "ویزیت تخصصی" }
  ],
  "satisfaction": "60",
  "point": "3.5",
  "free_turn": "اولین نوبت آزاد: سه‌شنبه 19 خرداد ساعت 15:00",
  "hours_of_work": "از شنبه تا چهارشنبه از ساعت 08:00 تا 18:00",
  "address": [
    {
      "id": "39",
      "uuid": "7b759d2a-af8a-4730-8eb0-e77dcd3a724e",
      "name": "مطب اصلی",
      "map": { "latitude": "53.121212", "longitude": "57.121212" },
      "address": "آدرس کامل مطب",
      "telephone": "09120671756"
    }
  ],
  "average_rate": { "total_rates": null },
  "state": [{ "uuid": "...", "id": "23", "name": "کهگیلویه و بویراحمد" }],
  "city": [{ "uuid": "...", "id": "123", "name": "یاسوج", "parent": "23" }]
}

توجه فیلدها:

• img (نه image یا images!) — آرایه با url/fid/filename/filemime/filesize
• specialties → تخصص اصلی + والد
• expertise → همان doctor_services
• satisfaction و point به صورت string برگردانده می‌شوند
• free_turn → متن محاسبه‌شده از برنامه هفتگی (مثلاً "نوبت آزادی موجود نیست")
• hours_of_work → متن محاسبه‌شده از برنامه هفتگی
• average_rate.total_rates → می‌تواند null باشد
• experience → محاسبه‌شده از activity_time (Unix timestamp شروع فعالیت)

---

فیلترهای GET /api/v1/doctors

پارامتر	نوع	الزامی	مثال
state	string	بله	31
city	string	بله	62
specialty	string	خیر	503
gender	string	خیر	man یا woman
degree	string	خیر	general, specialist, expert, subspecialistplus
name	string	خیر	علی
active	array	خیر	0 یا 1
page	string	خیر	1
limit	string	خیر	10
sort	string	خیر	ASC یا DESC

نمونه Response لیست دکترها

{
  "data": [
    {
      "id": "29",
      "uuid": "...",
      "name": "single doctor",
      "gender": "woman",
      "degree": "specialist",
      "img": [{ "url": "...", "fid": "98", "filename": "image.png", "filemime": "image/png", "filesize": 173665 }],
      "specialties": [{ "uuid": "...", "id": "603", "name": "داخلی عمومی", "parent": "602" }],
      "satisfaction": "60",
      "point": "3.5",
      "free_turn": "اولین نوبت آزاد: سه‌شنبه 19 خرداد ساعت 15:00",
      "hours_of_work": "از شنبه تا چهارشنبه از ساعت 08:00 تا 18:00",
      "active": true
    }
  ],
  "page": {
    "totalRecords": 7,
    "totalPages": 1,
    "currentPage": 1
  }
}

---

PATCH /api/v1/doctor/{uuid} — فیلدهای قابل ویرایش

{
  "title": "نام دکتر",
  "doctor_services": ["اکوکاردیوگرافی", "ویزیت تخصصی"]
}

---

آپلود تصویر دکتر — POST /file/upload/clinic_pro/doctor/field_image

Headers:
  Content-Type: application/octet-stream
  Content-Disposition: file; filename="doctor.png"
  X-CSRF-Token: {token}
  Authorization: Bearer {token}
Body: binary file content
Response → { fid, uuid, ... } که در PATCH doctor استفاده می‌شود

---

نمونه واقعی Response — GET /api/v1/clinic-pro/doctor-address/{id}

{
  "id": "39",
  "uuid": "7b759d2a-af8a-4730-8eb0-e77dcd3a724e",
  "name": "مطب اصلی",
  "map": {
    "latitude": "53.121212",
    "longitude": "57.121212"
  },
  "address": "آذربايجان غربي، مياندوآب، خيابان ۱۵ خرداد، برج ماندگار",
  "telephone": "09120671756"
}