Doctors Module

إدارة الأطباء - Profiles, Schedules, Leaves & Certifications

Ready Core Module 29 Endpoints

Table of Contents

نظرة عامة

Doctors Module يوفر نظام شامل لإدارة الأطباء والموظفين الطبيين:

  • Doctor Management: إدارة كاملة للأطباء مع بياناتهم الشخصية والمهنية
  • Schedule Management: إدارة جداول الأطباء والمناوبات اليومية
  • Leave Management: إدارة إجازات الأطباء مع نظام الموافقات
  • Education & Certifications: إدارة المؤهلات العلمية والشهادات
  • Advanced Filtering: بحث وتصفية متقدمة حسب التخصص والخبرة
  • Ratings System: نظام تقييم الأطباء والمراجعات
ملاحظة: يتكامل مع Care Module للمواعيد و Patients Module لسجلات المرضى.

Entities (6 Entities)

Doctor

Main Entity

الجدول الرئيسي لبيانات الأطباء

الحقول الرئيسية:

Field Type Description Required
user_id integer ربط مع جدول المستخدمين ✅
license_number string رقم الترخيص الطبي (unique) ✅
specialization_id integer التخصص الطبي ✅
department_id integer القسم التابع له ✅
consultation_fee decimal رسوم الكشف ❌
experience_years integer سنوات الخبرة ❌
bio text نبذة تعريفية عن الطبيب ❌
verified boolean حالة التحقق من الطبيب ❌
accepts_new_patients boolean يقبل مرضى جدد ❌

Relations:

  • user() → User (belongsTo)
  • specialization() → Specialization (belongsTo)
  • department() → Department (belongsTo)
  • schedules() → DoctorSchedule (hasMany)
  • leaves() → DoctorLeave (hasMany)
  • educations() → DoctorEducation (hasMany)
  • certifications() → DoctorCertification (hasMany)

DoctorSchedule

Working Hours

جدول أوقات عمل الأطباء الأسبوعي

الحقول:

Field Type Description Required
doctor_id integer معرف الطبيب ✅
day_of_week integer يوم الأسبوع (0=Sunday, 6=Saturday) ✅
start_time time وقت البدء (HH:MM:SS) ❌
end_time time وقت الانتهاء (HH:MM:SS) ❌
is_off boolean يوم إجازة أسبوعية ❌

DoctorLeave

Approval Flow

طلبات الإجازات للأطباء مع نظام الموافقات

الحقول:

Field Type Description Required
doctor_id integer معرف الطبيب ✅
leave_type_id integer نوع الإجازة (annual, sick, emergency) ✅
start_date date تاريخ البدء ✅
end_date date تاريخ الانتهاء ✅
reason text سبب الإجازة ❌
status_id integer الحالة (pending, approved, rejected, cancelled) ✅
is_half_day boolean إجازة نصف يوم ❌
rejection_reason text سبب الرفض (إن وجد) ❌
cancellation_reason text سبب الإلغاء (إن وجد) ❌

Other Entities

Additional
  • DoctorEducation: المؤهلات العلمية والدرجات الأكاديمية (degree, institution, graduation_year)
  • DoctorCertification: الشهادات المهنية والتراخيص (name, issuing_organization, issue_date, expiry_date)
  • DoctorRating: تقييمات ومراجعات المرضى (patient_id, rating, review, created_at)

API Endpoints (29 endpoints)

جميع endpoints تتطلب Authentication عبر Bearer Token و middleware: auth:sanctum

Doctor CRUD APIs (5 endpoints)

GET
/api/doctors
قائمة الأطباء مع بحث وفلترة متقدمة
📖 عرض التفاصيل الكاملة
Query Parameters:
Parameter Type Description Example
q string بحث في الاسم q=أحمد
department_id integer فلترة حسب القسم department_id=5
specialization_id integer فلترة حسب التخصص specialization_id=3
verified boolean الأطباء المعتمدون فقط verified=1
min_rating float الحد الأدنى للتقييم min_rating=4.0
accepts_new_patients boolean يقبل مرضى جدد accepts_new_patients=1
per_page integer عدد النتائج في الصفحة per_page=20
Response Example (200 OK):
{
  "status": true,
  "data": [
    {
      "id": 1,
      "user_id": 10,
      "license_number": "MED-12345",
      "specialization_id": 3,
      "specialization": {
        "id": 3,
        "name": "Cardiology"
      },
      "department_id": 5,
      "department": {
        "id": 5,
        "name": "Emergency Department"
      },
      "consultation_fee": 150.00,
      "experience_years": 8,
      "bio": "متخصص في أمراض القلب",
      "verified": true,
      "accepts_new_patients": true,
      "average_rating": 4.5,
      "created_at": "2024-01-15T10:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 50
  }
}
cURL Example:
curl -X GET "https://api.hms.com/api/doctors?department_id=5&verified=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
GET
/api/doctors/{id}
تفاصيل طبيب محدد مع جميع العلاقات
📖 عرض التفاصيل الكاملة
Path Parameters:
  • id - معرف الطبيب (integer, required)
Response Example (200 OK):
{
  "status": true,
  "data": {
    "id": 1,
    "user": {
      "id": 10,
      "name": "د. أحمد محمد",
      "email": "doctor@example.com"
    },
    "license_number": "MED-12345",
    "specialization": {
      "id": 3,
      "name": "Cardiology"
    },
    "department": {
      "id": 5,
      "name": "Emergency Department"
    },
    "consultation_fee": 150.00,
    "experience_years": 8,
    "bio": "متخصص في أمراض القلب مع خبرة 8 سنوات",
    "verified": true,
    "accepts_new_patients": true,
    "average_rating": 4.5,
    "total_reviews": 120,
    "schedules": [...],
    "educations": [...],
    "certifications": [...]
  }
}
POST
/api/doctors
إضافة طبيب جديد
📖 عرض التفاصيل الكاملة
Request Body:
{
  "user_id": 10,
  "license_number": "MED-12345",
  "specialization_id": 3,
  "department_id": 5,
  "consultation_fee": 150.00,
  "experience_years": 8,
  "bio": "متخصص في أمراض القلب",
  "verified": false,
  "accepts_new_patients": true
}
Validation Rules:
  • user_id - required, integer, exists in users table, unique
  • license_number - required, string, unique, max:50
  • specialization_id - required, integer, exists in specializations
  • department_id - required, integer, exists in departments
  • consultation_fee - nullable, numeric, min:0
  • experience_years - nullable, integer, min:0, max:70
  • bio - nullable, string, max:1000
  • verified - nullable, boolean
  • accepts_new_patients - nullable, boolean
Success Response (201 Created):
{
  "status": true,
  "message": "Doctor created successfully",
  "data": {
    "id": 1,
    "user_id": 10,
    "license_number": "MED-12345",
    ...
  }
}
Error Response (422 Unprocessable Entity):
{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "license_number": ["The license number has already been taken."]
  }
}
PUT
/api/doctors/{id}
تحديث بيانات طبيب
📖 عرض التفاصيل الكاملة
Path Parameters:
  • id - معرف الطبيب (integer, required)
Request Body:
{
  "consultation_fee": 200.00,
  "experience_years": 9,
  "bio": "متخصص في أمراض القلب - تحديث",
  "accepts_new_patients": false
}
Response (200 OK):
{
  "status": true,
  "message": "Doctor updated successfully",
  "data": {...}
}
DELETE
/api/doctors/{id}
حذف طبيب (soft delete)
📖 عرض التفاصيل الكاملة
Path Parameters:
  • id - معرف الطبيب (integer, required)
Response (200 OK):
{
  "status": true,
  "message": "Doctor deleted successfully"
}
ملاحظة: Soft delete - لا يتم حذف البيانات نهائياً بل يتم تعليمها كمحذوفة

Helper Endpoints (6 endpoints)

GET
/api/doctors/helpers/doctors
قائمة مختصرة للأطباء (للاستخدام في dropdowns)
📖 عرض التفاصيل الكاملة
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "د. أحمد محمد",
      "specialization": "Cardiology"
    },
    {
      "id": 2,
      "name": "د. فاطمة علي",
      "specialization": "Pediatrics"
    }
  ]
}
GET
/api/doctors/helpers/doctors/department/{departmentId}
أطباء قسم معين
📖 عرض التفاصيل الكاملة
Path Parameters:
  • departmentId - معرف القسم (integer, required)
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "د. أحمد محمد",
      "department_id": 5,
      "department_name": "Emergency Department"
    }
  ]
}
GET
/api/doctors/helpers/doctors/specialization/{specializationId}
أطباء تخصص معين
📖 عرض التفاصيل الكاملة
Path Parameters:
  • specializationId - معرف التخصص (integer, required)
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "د. أحمد محمد",
      "specialization_id": 3,
      "specialization_name": "Cardiology",
      "consultation_fee": 150.00
    }
  ]
}
GET
/api/doctors/helpers/doctors/available-now
الأطباء المتاحين الآن
📖 عرض التفاصيل الكاملة

يعرض الأطباء المتاحين للعمل في الوقت الحالي بناءً على جداولهم وإجازاتهم

Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "د. أحمد محمد",
      "specialization": "Cardiology",
      "current_schedule": {
        "start_time": "09:00:00",
        "end_time": "17:00:00"
      }
    }
  ],
  "meta": {
    "current_time": "2024-03-15T14:30:00Z"
  }
}
GET
/api/doctors/helpers/doctors/available-for-emergency
أطباء الطوارئ المتاحين
📖 عرض التفاصيل الكاملة

يعرض الأطباء المتاحين في قسم الطوارئ

Response Example:
{
  "status": true,
  "data": [
    {
      "id": 2,
      "name": "د. فاطمة علي",
      "specialization": "Emergency Medicine",
      "department": "Emergency Department",
      "available_until": "22:00:00"
    }
  ]
}
GET
/api/doctors/helpers/doctors/highly-rated
الأطباء ذوي التقييم العالي
📖 عرض التفاصيل الكاملة

يعرض الأطباء الذين لديهم تقييم 4.5 أو أعلى

Query Parameters:
Parameter Type Description Default
min_rating float الحد الأدنى للتقييم 4.5
limit integer عدد النتائج 10
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "د. أحمد محمد",
      "specialization": "Cardiology",
      "average_rating": 4.8,
      "total_reviews": 150
    }
  ]
}

Schedule Management (10 endpoints)

GET
/api/schedules
قائمة جميع الجداول
📖 عرض التفاصيل الكاملة
Query Parameters:
Parameter Type Description
doctor_id integer فلترة حسب الطبيب
day_of_week integer فلترة حسب اليوم (0-6)
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "doctor_id": 1,
      "day_of_week": 1,
      "day_name": "Monday",
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_off": false
    }
  ]
}
GET
/api/schedules/{id}
تفاصيل جدول محدد
POST
/api/schedules
إضافة جدول جديد
📖 عرض التفاصيل الكاملة
Request Body:
{
  "doctor_id": 1,
  "day_of_week": 1,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "is_off": false
}
Validation Rules:
  • doctor_id - required, integer, exists in doctors
  • day_of_week - required, integer, between:0,6
  • start_time - required_if:is_off,false, time format (HH:MM:SS)
  • end_time - required_if:is_off,false, time format, after:start_time
  • is_off - nullable, boolean
Success Response (201 Created):
{
  "status": true,
  "message": "Schedule created successfully",
  "data": {...}
}
PUT
/api/schedules/{id}
تحديث جدول
DELETE
/api/schedules/{id}
حذف جدول
GET
/api/doctors/{doctor}/schedules
جدول طبيب معين (جميع الأيام)
📖 عرض التفاصيل الكاملة
Path Parameters:
  • doctor - معرف الطبيب (integer, required)
Response Example:
{
  "status": true,
  "data": [
    {
      "day_of_week": 0,
      "day_name": "Sunday",
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_off": false
    },
    {
      "day_of_week": 5,
      "day_name": "Friday",
      "is_off": true
    }
  ]
}
GET
/api/doctors/{doctor}/schedules/working-days
أيام العمل فقط (استثناء أيام الإجازة)
📖 عرض التفاصيل الكاملة
Response Example:
{
  "status": true,
  "data": [
    {
      "day_of_week": 0,
      "day_name": "Sunday",
      "start_time": "09:00:00",
      "end_time": "17:00:00"
    }
  ]
}
GET
/api/doctors/{doctor}/schedules/days-off
أيام الإجازة الأسبوعية
📖 عرض التفاصيل الكاملة
Response Example:
{
  "status": true,
  "data": [
    {
      "day_of_week": 5,
      "day_name": "Friday"
    },
    {
      "day_of_week": 6,
      "day_name": "Saturday"
    }
  ]
}
POST
/api/doctors/{doctor}/schedules/bulk
تحديث الجدول الكامل (bulk upsert)
📖 عرض التفاصيل الكاملة

يسمح بتحديث جميع أيام الأسبوع دفعة واحدة

Request Body:
{
  "schedules": [
    {
      "day_of_week": 0,
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_off": false
    },
    {
      "day_of_week": 1,
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_off": false
    },
    {
      "day_of_week": 5,
      "is_off": true
    }
  ]
}
Success Response (200 OK):
{
  "status": true,
  "message": "Schedules updated successfully",
  "data": {
    "created": 5,
    "updated": 2
  }
}
POST
/api/doctors/{doctor}/schedules/set-day-off/{dayOfWeek}
تحديد يوم كإجازة أسبوعية
📖 عرض التفاصيل الكاملة
Path Parameters:
  • doctor - معرف الطبيب (integer, required)
  • dayOfWeek - رقم اليوم (0=Sunday, 6=Saturday)
Success Response:
{
  "status": true,
  "message": "Day off set successfully"
}

Leave Management (9 endpoints)

GET
/api/leaves
قائمة جميع الإجازات
📖 عرض التفاصيل الكاملة
Query Parameters:
Parameter Type Description
doctor_id integer فلترة حسب الطبيب
status_id integer فلترة حسب الحالة
leave_type_id integer فلترة حسب نوع الإجازة
start_date date من تاريخ
end_date date إلى تاريخ
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "doctor_id": 1,
      "doctor_name": "د. أحمد محمد",
      "leave_type": "Annual Leave",
      "start_date": "2024-03-01",
      "end_date": "2024-03-05",
      "status": "approved",
      "reason": "عطلة سنوية",
      "is_half_day": false
    }
  ]
}
GET
/api/leaves/pending
الإجازات المعلقة (تحتاج موافقة)
📖 عرض التفاصيل الكاملة

يعرض جميع طلبات الإجازات التي تحتاج إلى موافقة

Response Example:
{
  "status": true,
  "data": [
    {
      "id": 2,
      "doctor_id": 3,
      "doctor_name": "د. فاطمة علي",
      "leave_type": "Sick Leave",
      "start_date": "2024-03-10",
      "end_date": "2024-03-12",
      "status": "pending",
      "requested_at": "2024-03-05T10:00:00Z"
    }
  ]
}
GET
/api/leaves/active
الإجازات النشطة حالياً
📖 عرض التفاصيل الكاملة

يعرض الإجازات المعتمدة والجارية في الوقت الحالي

Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "doctor_id": 1,
      "doctor_name": "د. أحمد محمد",
      "leave_type": "Annual Leave",
      "start_date": "2024-03-01",
      "end_date": "2024-03-05",
      "days_remaining": 2
    }
  ],
  "meta": {
    "current_date": "2024-03-03"
  }
}
GET
/api/leaves/upcoming
الإجازات القادمة
📖 عرض التفاصيل الكاملة

يعرض الإجازات المعتمدة التي ستبدأ في المستقبل

Response Example:
{
  "status": true,
  "data": [
    {
      "id": 3,
      "doctor_id": 2,
      "doctor_name": "د. محمد خالد",
      "leave_type": "Annual Leave",
      "start_date": "2024-04-01",
      "end_date": "2024-04-10",
      "days_until_start": 25
    }
  ]
}
GET
/api/doctors/{doctor}/leaves
إجازات طبيب معين
📖 عرض التفاصيل الكاملة
Path Parameters:
  • doctor - معرف الطبيب (integer, required)
Response Example:
{
  "status": true,
  "data": [
    {
      "id": 1,
      "leave_type": "Annual Leave",
      "start_date": "2024-03-01",
      "end_date": "2024-03-05",
      "status": "approved",
      "total_days": 5
    }
  ]
}
POST
/api/leaves
طلب إجازة جديدة
📖 عرض التفاصيل الكاملة
Request Body:
{
  "doctor_id": 1,
  "leave_type_id": 2,
  "start_date": "2024-03-01",
  "end_date": "2024-03-05",
  "reason": "عطلة سنوية",
  "is_half_day": false
}
Validation Rules:
  • doctor_id - required, integer, exists in doctors
  • leave_type_id - required, integer, exists in leave_types
  • start_date - required, date, after_or_equal:today
  • end_date - required, date, after_or_equal:start_date
  • reason - nullable, string, max:500
  • is_half_day - nullable, boolean
Success Response (201 Created):
{
  "status": true,
  "message": "Leave request submitted successfully",
  "data": {
    "id": 1,
    "status": "pending",
    "total_days": 5
  }
}
Error Response (422):
{
  "status": false,
  "message": "Leave dates overlap with existing approved leave",
  "errors": {
    "start_date": ["Conflicting leave exists"]
  }
}
PUT
/api/leaves/{id}
تحديث طلب إجازة
PATCH
/api/leaves/{leave}/status
الموافقة/رفض إجازة
📖 عرض التفاصيل الكاملة
Path Parameters:
  • leave - معرف الإجازة (integer, required)
Request Body:
{
  "action": "approve",
  "rejection_reason": "optional - required if action is reject"
}
Validation Rules:
  • action - required, in:approve,reject
  • rejection_reason - required_if:action,reject, string, max:500
Success Response (200 OK):
{
  "status": true,
  "message": "Leave approved successfully",
  "data": {
    "id": 1,
    "status": "approved"
  }
}
PATCH
/api/leaves/{leave}/cancel
إلغاء إجازة
📖 عرض التفاصيل الكاملة
Path Parameters:
  • leave - معرف الإجازة (integer, required)
Request Body:
{
  "cancellation_reason": "سبب الإلغاء"
}
Success Response:
{
  "status": true,
  "message": "Leave cancelled successfully"
}
ملاحظة: يمكن للطبيب إلغاء إجازته فقط إذا كانت في حالة pending أو approved ولم تبدأ بعد

Integration

التكامل مع Modules الأخرى

1. Care Module (Appointments)

// عرض مواعيد طبيب معين
$doctor = Doctor::find(1);
$appointments = $doctor->appointments;

// إنشاء موعد مع طبيب
$appointment = Appointment::create([
    'doctor_id' => $doctor->id,
    'patient_id' => $patientId,
    'scheduled_at' => '2024-03-15 10:00:00',
]);

2. Patients Module

// ربط طبيب مع مريض
$doctor->patients()->attach($patientId);

// عرض جميع مرضى الطبيب
$patients = $doctor->patients;

3. Facilities Module

// ربط طبيب بقسم معين
$doctor->department_id = $departmentId;
$doctor->save();

// عرض أطباء قسم معين
$department = Department::find(1);
$doctors = $department->doctors;

4. Check Doctor Availability

// التحقق من توفر طبيب في وقت محدد
use Modules\Doctors\Services\DoctorAvailabilityService;

$service = app(DoctorAvailabilityService::class);
$isAvailable = $service->isAvailable($doctorId, '2024-03-15 10:00:00');

// الحصول على أوقات العمل المتاحة
$availableSlots = $service->getAvailableSlots($doctorId, '2024-03-15');

Best Practices

✅ التوصيات

  • تحقق من الجدول: تأكد من عدم تداخل المواعيد مع الإجازات قبل الحجز
  • استخدم Helper Endpoints: للحصول على قوائم مختصرة في dropdowns
  • Verify Doctors: تحقق من الأطباء قبل منحهم صلاحيات كاملة
  • Track Schedules: راقب جداول الأطباء بانتظام وحدثها عند الحاجة
  • Approval Flow: استخدم workflow للموافقة على الإجازات
  • License Validation: تحقق من صلاحية رقم الترخيص الطبي
  • Conflict Detection: تحقق من عدم تداخل الإجازات مع المواعيد

❌ تجنب

  • إنشاء جداول متداخلة للطبيب نفسه في نفس اليوم
  • الموافقة على إجازات دون مراجعة الجدول والمواعيد القائمة
  • حذف أطباء لديهم مواعيد نشطة أو إجازات قادمة
  • تجاهل رقم الترخيص الطبي - ضروري للتحقق والامتثال القانوني
  • تعديل جداول الأطباء دون إخطارهم

Example: إضافة طبيب مع جدوله

// إضافة طبيب جديد
$doctor = Doctor::create([
    'user_id' => $userId,
    'license_number' => 'MED-12345',
    'specialization_id' => 3,
    'department_id' => 5,
    'consultation_fee' => 150.00,
    'experience_years' => 8,
    'verified' => false, // يحتاج تحقق
    'accepts_new_patients' => true,
]);

// إضافة جدول أسبوعي
$schedules = [
    ['day_of_week' => 0, 'start_time' => '09:00', 'end_time' => '17:00'], // Sunday
    ['day_of_week' => 1, 'start_time' => '09:00', 'end_time' => '17:00'], // Monday
    ['day_of_week' => 2, 'start_time' => '09:00', 'end_time' => '17:00'], // Tuesday
    ['day_of_week' => 3, 'start_time' => '09:00', 'end_time' => '17:00'], // Wednesday
    ['day_of_week' => 4, 'start_time' => '09:00', 'end_time' => '13:00'], // Thursday (half day)
    ['day_of_week' => 5, 'is_off' => true], // Friday off
    ['day_of_week' => 6, 'is_off' => true], // Saturday off
];

foreach ($schedules as $schedule) {
    $schedule['doctor_id'] = $doctor->id;
    DoctorSchedule::create($schedule);
}

Statistics

6
Entities
29
API Endpoints
100%
Authenticated
Ready
Status

Key Features

  • ✅ Complete Doctor Profile Management
  • ✅ Weekly Schedule Management (7 days)
  • ✅ Leave Request & Approval System
  • ✅ Education & Certifications Tracking
  • ✅ Advanced Search & Filtering
  • ✅ Doctor Ratings System
  • ✅ Real-time Availability Checking
  • ✅ Emergency Doctor Roster
  • ✅ Bulk Schedule Updates
  • ✅ Leave Conflict Detection