گزارش_کامل_پروژه.md

📋 گزارش کامل پروژه: سیستم نوبت دهی کلینیک دندانپزشکی آتیه

🎯 خلاصه اجرایی

این پروژه یک سیستم نوبت دهی هوشمند برای کلینیک دندانپزشکی آتیه است که از الگوریتم AI برای محاسبه اولویت نوبت‌ها بر اساس سه پارامتر اصلی استفاده می‌کند:

1. نوع پرداخت (نقدی یا 20 نوع بیمه)
2. نوع درمان (20 نوع درمان)
3. طول عمر مشتری (مدت زمان عضویت در کلینیک)

---

🏗️ معماری سیستم

تکنولوژی‌های استفاده شده:

• Backend: FastAPI (Python)
• Database: SQLite با SQLAlchemy ORM
• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• الگوریتم AI: الگوریتم امتیازدهی سفارشی

ساختار فایل‌ها:

atieh/
├── app.py                      # API اصلی FastAPI
├── models.py                   # مدل‌های دیتابیس
├── database.py                 # تنظیمات دیتابیس
├── scoring_algorithm.py         # الگوریتم محاسبه امتیاز اولویت
├── appointment_scheduler.py     # سیستم پیشنهاد خودکار نوبت
├── treatment_duration.py        # مدت زمان هر نوع درمان
├── add_sample_data.py           # اسکریپت افزودن داده نمونه
├── migrate_database.py          # اسکریپت مایگریشن دیتابیس
├── static/
│   ├── index.html              # رابط کاربری اصلی
│   ├── script.js               # منطق فرانت‌اند
│   └── style.css               # استایل‌ها
└── atieh_clinic.db             # دیتابیس SQLite

---

📊 مدل‌های دیتابیس

1. Patient (بیمار)

• id: شناسه یکتا
• name: نام و نام خانوادگی
• phone: شماره تلفن (یکتا)
• national_id: کد ملی (یکتا، اختیاری)
• payment_type: نوع پرداخت پیش‌فرض (Enum: CASH یا INSURANCE_1 تا INSURANCE_20)
• first_visit_date: تاریخ اولین مراجعه
• created_at, updated_at: زمان‌های ایجاد و به‌روزرسانی

2. Appointment (نوبت)

• id: شناسه یکتا
• patient_id: شناسه بیمار (Foreign Key)
• appointment_date: تاریخ و زمان نوبت
• duration_minutes: مدت زمان نوبت به دقیقه (پیش‌فرض: 30)
• payment_type: نوع پرداخت این نوبت
• treatment_type: نوع درمان (Enum: TREATMENT_1 تا TREATMENT_20)
• priority_score: امتیاز اولویت محاسبه شده توسط AI
• status: وضعیت نوبت (pending, confirmed, completed, cancelled)
• notes: یادداشت‌های اختیاری

3. ClinicSchedule (زمان‌های کاری کلینیک)

• id: شناسه یکتا
• day_of_week: روز هفته (0=دوشنبه، 6=یکشنبه)
• start_time: ساعت شروع کار (مثلاً "09:00")
• end_time: ساعت پایان کار (مثلاً "18:00")
• is_active: فعال/غیرفعال بودن

---

🧮 الگوریتم امتیازدهی AI

پارامترهای محاسبه:

1. نوع پرداخت (وزن: 40%)

• نقدی (CASH): 100 امتیاز - عالی
• بیمه 1-7: 90-60 امتیاز - خیلی خوب
• بیمه 8-14: 50-20 امتیاز - متوسط
• بیمه 15-20: 15-3 امتیاز - بد

2. نوع درمان (وزن: 35%)

• درمان 1-5: 100-80 امتیاز - عالی
• درمان 6-10: 75-50 امتیاز - خیلی خوب
• درمان 11-15: 45-25 امتیاز - متوسط
• درمان 16-20: 20-5 امتیاز - بد

3. طول عمر مشتری (وزن: 25%)

• کمتر از 6 ماه: 50 امتیاز - متوسط
• 6 ماه تا 1 سال: 70 امتیاز - خوب
• 1 سال تا 2 سال: 85 امتیاز - خیلی خوب
• بیش از 2 سال: 100 امتیاز - عالی

فرمول محاسبه:

امتیاز کل = (امتیاز پرداخت × 0.4) + (امتیاز درمان × 0.35) + (امتیاز طول عمر × 0.25)

---

🔌 API Endpoints

بیماران (Patients)

POST /patients

ایجاد بیمار جدید

• Body: {name, phone, national_id?, payment_type?, first_visit_date?}
• Response: اطلاعات بیمار ایجاد شده

GET /patients

لیست تمام بیماران با امکان جستجو

• Query Parameters:
  • search: جستجو بر اساس نام، تلفن یا کد ملی
  • skip, limit: صفحه‌بندی
• Response: لیست بیماران با اطلاعات کامل (payment_category, lifetime_category)

GET /patients/{patient_id}

دریافت اطلاعات یک بیمار خاص

• Response: اطلاعات کامل بیمار شامل:
  • payment_type, payment_category
  • lifetime_months, lifetime_category
  • first_visit_date

نوبت‌ها (Appointments)

POST /appointments

ایجاد نوبت جدید

• Body: {patient_id, treatment_type, appointment_date?, notes?}
• ویژگی‌های هوشمند:
  • اگر appointment_date مشخص نشود، AI به صورت خودکار بهترین زمان را پیشنهاد می‌دهد
  • payment_type به صورت خودکار از اطلاعات بیمار استخراج می‌شود
  • duration_minutes بر اساس treatment_type محاسبه می‌شود
  • priority_score به صورت خودکار محاسبه می‌شود
• Response: اطلاعات نوبت ایجاد شده

GET /appointments

لیست نوبت‌ها

• Query Parameters:
  • skip, limit: صفحه‌بندی
  • status: فیلتر بر اساس وضعیت
  • sort_by_priority: مرتب‌سازی بر اساس اولویت (پیش‌فرض: true)
  • future_only: فقط نوبت‌های آینده (پیش‌فرض: true)
• Response: لیست نوبت‌ها با اطلاعات کامل

GET /appointments/{appointment_id}

دریافت اطلاعات یک نوبت خاص

GET /appointments/suggest-time

دریافت 5 زمان پیشنهادی برای یک نوبت

• Query Parameters:
  • treatment_type: نوع درمان
  • patient_id: شناسه بیمار (اختیاری - برای اولویت‌بندی)
  • days_ahead: تعداد روزهای آینده برای بررسی (پیش‌فرض: 7)
  • max_suggestions: حداکثر تعداد پیشنهادات (پیش‌فرض: 5)
• Response: لیست زمان‌های پیشنهادی با اولویت‌بندی

GET /appointments/next-available

دریافت نوبت‌های پیشنهادی بر اساس اولویت

• Query Parameters: limit (پیش‌فرض: 10)
• Response: لیست نوبت‌های در انتظار مرتب شده بر اساس امتیاز اولویت

GET /appointments/available-slots

دریافت لیست زمان‌های خالی

• Query Parameters:
  • start_date, end_date: بازه زمانی
  • days_ahead: تعداد روزهای آینده
  • duration_minutes: مدت زمان نوبت
• Response: لیست زمان‌های خالی

انواع پرداخت و درمان

GET /payment-types

لیست انواع پرداخت (نقدی + 20 نوع بیمه)

GET /treatment-types

لیست انواع درمان (20 نوع)

---

🎨 رابط کاربری (Frontend)

تب‌های اصلی:

1. تب "بیماران"

• نمایش لیست تمام بیماران
• جستجوی زنده بر اساس نام، تلفن یا کد ملی
• دکمه "بیمار جدید" برای افزودن بیمار
• نمایش اطلاعات:
  • نام، تلفن، کد ملی
  • نوع پرداخت و دسته‌بندی
  • طول عمر مشتری (ماه و دسته‌بندی)
  • تاریخ اولین مراجعه

2. تب "نوبت جدید"

ویژگی‌های هوشمند:

• جستجوی بیمار با Autocomplete:

  • امکان تایپ نام یا شماره تلفن
  • نمایش نتایج به صورت dropdown
  • نمایش اطلاعات کامل بیمار در نتایج جستجو
  • Debounce برای کاهش درخواست‌های API

• انتخاب نوع درمان:

  • Dropdown با 20 نوع درمان
  • نمایش دسته‌بندی هر درمان (عالی، خیلی خوب، متوسط، بد)

• پیشنهادات هوشمند AI:

  • پس از انتخاب بیمار و نوع درمان، AI به صورت خودکار 5 زمان پیشنهادی ارائه می‌دهد
  • زمان‌ها بر اساس اولویت مرتب می‌شوند
  • اولین پیشنهاد به عنوان "بهترین پیشنهاد" علامت‌گذاری می‌شود
  • هر پیشنهاد به صورت یک دکمه نمایش داده می‌شود

• انتخاب زمان:

  • کاربر می‌تواند یکی از 5 زمان پیشنهادی را انتخاب کند
  • زمان انتخاب شده highlight می‌شود
  • یک checkmark (✓) در کنار زمان انتخاب شده نمایش داده می‌شود
  • اطلاعات زمان انتخاب شده در یک باکس نمایش داده می‌شود

• دکمه "ثبت نهایی":

  • در ابتدا غیرفعال است
  • پس از انتخاب یک زمان پیشنهادی، فعال می‌شود
  • پس از ثبت موفق، فرم پاک می‌شود و کاربر به تب "نوبت‌های ثبت شده" منتقل می‌شود

• پیش‌نمایش امتیاز اولویت:

  • نمایش دسته‌بندی نوع پرداخت
  • نمایش دسته‌بندی نوع درمان
  • نمایش دسته‌بندی طول عمر مشتری
  • نمایش امتیاز کل اولویت

3. تب "نوبت‌های ثبت شده"

• فقط نوبت‌های جدید: فقط نوبت‌هایی که از تب "نوبت جدید" ثبت شده‌اند نمایش داده می‌شوند
• نمایش ساده: فقط نام بیمار و تاریخ/زمان نوبت نمایش داده می‌شود
• مرتب‌سازی: نوبت‌ها بر اساس زمان (زودترین اول) مرتب می‌شوند
• فیلتر آینده: فقط نوبت‌های آینده نمایش داده می‌شوند

4. تب "اولویت‌ها"

• نمایش نوبت‌های در انتظار بر اساس امتیاز اولویت
• هر نوبت با رتبه‌بندی نمایش داده می‌شود
• نمایش اطلاعات کامل هر نوبت

ویژگی‌های UI/UX:

• طراحی Responsive و مدرن
• استفاده از فونت فارسی Vazir
• رنگ‌بندی بر اساس اولویت (سبز برای اولویت بالا)
• انیمیشن‌های نرم برای تعاملات
• پیام‌های خطای واضح و کاربرپسند
• Loading states برای عملیات‌های async

---

🤖 سیستم پیشنهاد خودکار نوبت

الگوریتم پیشنهاد زمان:

1. یافتن زمان‌های خالی:

   • بررسی ساعات کاری کلینیک (9 صبح تا 6 عصر)
   • حذف زمان ناهار (1 تا 2 بعدازظهر)
   • بررسی روزهای کاری (دوشنبه تا جمعه)
   • بررسی تداخل با نوبت‌های موجود

2. اولویت‌بندی زمان‌ها:

   • اگر patient_id مشخص باشد:
     • اولویت با امتیاز اولویت بیمار
     • نزدیکی به زمان فعلی
     • زمان روز (صبح بهتر از عصر)
   • اگر patient_id مشخص نباشد:
     • فقط بر اساس نزدیکی به زمان فعلی

3. انتخاب 5 زمان برتر:

   • حذف زمان‌های تکراری
   • انتخاب بهترین زمان‌ها بر اساس اولویت
   • بازگشت لیست مرتب شده

مدت زمان درمان:

هر نوع درمان مدت زمان مشخصی دارد:

• درمان 1-5: 20-90 دقیقه
• درمان 6-10: 30-90 دقیقه
• درمان 11-15: 60-120 دقیقه
• درمان 16-20: 90-240 دقیقه

---

🔧 اسکریپت‌های کمکی

add_sample_data.py

• افزودن 20 بیمار نمونه به دیتابیس
• افزودن نوبت‌های نمونه
• پشتیبانی از encoding UTF-8 برای Windows

migrate_database.py

• افزودن ستون payment_type به جدول patients
• افزودن ستون duration_minutes به جدول appointments
• پشتیبانی از encoding UTF-8 برای Windows

---

🐛 رفع خطاها و بهبودها

خطاهای برطرف شده:

1. خطای Encoding در Windows:

   • افزودن sys.stdout و sys.stderr با encoding UTF-8

2. خطای دیتابیس:

   • افزودن ستون‌های جدید با migration script
   • مدیریت timezone-aware datetimes

3. خطای API 500:

   • مدیریت خطا برای payment_type که ممکن است None باشد
   • مدیریت خطا در محاسبه lifetime_category
   • Try-except blocks جامع در تمام endpoints

4. خطای Frontend:

   • بهبود نمایش پیام‌های خطا
   • مدیریت خطا در autocomplete
   • مدیریت خطا در پیشنهادات AI

5. مشکل Routing در FastAPI:

   • تغییر ترتیب routes برای جلوگیری از تفسیر اشتباه path parameters

6. مشکل Timezone:

   • استفاده از datetime.now(timezone.utc) به جای datetime.utcnow()
   • تبدیل timezone-naive به timezone-aware

---

📈 ویژگی‌های کلیدی سیستم

✅ پیاده‌سازی شده:

1. مدیریت بیماران:

   • ✅ افزودن بیمار جدید
   • ✅ جستجوی بیماران
   • ✅ نمایش لیست بیماران
   • ✅ ذخیره نوع پرداخت پیش‌فرض برای هر بیمار

2. سیستم نوبت دهی:

   • ✅ ثبت نوبت جدید
   • ✅ پیشنهاد خودکار زمان توسط AI
   • ✅ محاسبه خودکار امتیاز اولویت
   • ✅ استخراج خودکار نوع پرداخت از اطلاعات بیمار
   • ✅ محاسبه خودکار مدت زمان بر اساس نوع درمان

3. الگوریتم AI:

   • ✅ محاسبه امتیاز بر اساس 3 پارامتر
   • ✅ اولویت‌بندی نوبت‌ها
   • ✅ پیشنهاد 5 زمان برتر

4. رابط کاربری:

   • ✅ طراحی مدرن و Responsive
   • ✅ Autocomplete برای جستجوی بیمار
   • ✅ نمایش پیشنهادات AI به صورت دکمه‌های قابل انتخاب
   • ✅ Highlight زمان انتخاب شده
   • ✅ نمایش لیست نوبت‌های ثبت شده

5. مدیریت خطا:

   • ✅ Try-except blocks جامع
   • ✅ پیام‌های خطای واضح
   • ✅ مدیریت timezone
   • ✅ مدیریت مقادیر None

---

🚀 نحوه استفاده

راه‌اندازی:

1. نصب وابستگی‌ها:

   pip install -r requirements.txt

2. راه‌اندازی دیتابیس:

   python migrate_database.py

3. افزودن داده نمونه (اختیاری):

   python add_sample_data.py

4. اجرای سرور:

   python run.py

   یا

   uvicorn app:app --reload

5. دسترسی به سیستم:

   • باز کردن مرورگر و رفتن به: http://localhost:8000

---

📝 نکات مهم

1. دیتابیس: سیستم از SQLite استفاده می‌کند که فایل atieh_clinic.db را ایجاد می‌کند.

2. Timezone: تمام زمان‌ها در UTC ذخیره می‌شوند و در frontend به timezone محلی تبدیل می‌شوند.

3. اولویت‌بندی: نوبت‌ها بر اساس امتیاز اولویت (priority_score) مرتب می‌شوند که توسط الگوریتم AI محاسبه می‌شود.

4. پیشنهادات AI: سیستم به صورت خودکار 5 زمان برتر را پیشنهاد می‌دهد که کاربر می‌تواند یکی را انتخاب کند.

5. نوبت‌های ثبت شده: فقط نوبت‌هایی که از تب "نوبت جدید" ثبت شده‌اند در تب "نوبت‌های ثبت شده" نمایش داده می‌شوند.

---

🎯 نتیجه‌گیری

این سیستم یک راه‌حل کامل و هوشمند برای مدیریت نوبت‌های کلینیک دندانپزشکی است که:

• از الگوریتم AI برای اولویت‌بندی استفاده می‌کند
• رابط کاربری ساده و کاربرپسند دارد
• به صورت خودکار زمان‌های مناسب را پیشنهاد می‌دهد
• مدیریت خطاهای جامعی دارد
• قابلیت جستجو و فیلتر دارد

سیستم آماده استفاده است و می‌تواند به راحتی گسترش یابد.

---

تاریخ گزارش: 2024 نسخه سیستم: 1.0.0 وضعیت: ✅ آماده استفاده