TROUBLESHOOTING.md

# دليل استكشاف الأخطاء وإصلاحها | Troubleshooting Guide

## 🚨 الأخطاء الشائعة | Common Errors

### 1. خطأ الاستيراد | Import Error
```
NameError: name 'Request' is not defined
```

**الحل | Solution:**
```bash
# تأكد من أن جميع الاستيرادات موجودة
# Make sure all imports are present
python fix_imports.py
```

**السبب | Cause:** استيراد مفقود في ملف app.py

### 2. خطأ الذاكرة | Memory Error
```
RuntimeError: [enforce fail at alloc_cpu.cpp:75] 
```

**الحل | Solution:**
```bash
# قلل حجم الدفعة
# Reduce batch size
export BATCH_SIZE=2

# استخدم التحميل بالقطع
# Use chunk loading
export ENABLE_CHUNK_LOADING=true
```

### 3. خطأ الرموز المميزة | Token Error
```
HTTPError: 401 Client Error: Unauthorized
```

**الحل | Solution:**
1. تحقق من صحة الرمز المميز
2. أضف الرمز في إعدادات البيئة
3. استخدم واجهة إدارة الرموز

### 4. خطأ DICOM | DICOM Error
```
ImportError: No module named 'pydicom'
```

**الحل | Solution:**
```bash
# تثبيت مكتبات DICOM
pip install pydicom SimpleITK
```

## 🔧 خطوات الإصلاح السريع | Quick Fix Steps

### الخطوة 1: فحص النظام | Step 1: System Check
```bash
python fix_imports.py
```

### الخطوة 2: تشغيل النسخة المبسطة | Step 2: Run Minimal Version
```bash
python app_minimal.py
```

### الخطوة 3: فحص الصحة | Step 3: Health Check
```bash
curl http://localhost:8000/health
```

### الخطوة 4: فحص التصحيح | Step 4: Debug Check
```bash
curl http://localhost:8000/debug
```

## 🐛 تصحيح الأخطاء المتقدم | Advanced Debugging

### تفعيل وضع التصحيح | Enable Debug Mode
```bash
export DEBUG=true
export LOG_LEVEL=DEBUG
python app.py
```

### مراقبة الذاكرة | Memory Monitoring
```bash
# مراقبة استهلاك الذاكرة
watch -n 1 'free -h'

# مراقبة العمليات
htop
```

### فحص السجلات | Check Logs
```bash
# عرض السجلات الحديثة
tail -f logs/app.log

# البحث في السجلات
grep "ERROR" logs/app.log
```

## 🔍 تشخيص المشاكل | Problem Diagnosis

### مشكلة بطء الأداء | Performance Issues

**الأعراض | Symptoms:**
- بطء في التحميل
- استهلاك عالي للذاكرة
- توقف التطبيق

**الحلول | Solutions:**
1. تقليل حجم الدفعة
2. استخدام التحميل بالقطع
3. تفعيل تحسينات CPU
4. مراقبة الذاكرة

### مشكلة الاتصال | Connection Issues

**الأعراض | Symptoms:**
- خطأ 500 في الخادم
- عدم الاستجابة
- انقطاع الاتصال

**الحلول | Solutions:**
1. فحص المنفذ
2. تحقق من الجدار الناري
3. إعادة تشغيل الخادم

### مشكلة النماذج | Model Issues

**الأعراض | Symptoms:**
- فشل تحميل النموذج
- خطأ في التنسيق
- نفاد الذاكرة

**الحلول | Solutions:**
1. تحقق من تنسيق النموذج
2. استخدم التحميل بالقطع
3. قلل حجم النموذج

## 🛠️ أدوات الإصلاح | Repair Tools

### 1. أداة فحص الاستيرادات | Import Checker
```bash
python fix_imports.py
```

### 2. النسخة المبسطة | Minimal Version
```bash
python app_minimal.py
```

### 3. سكريبت البدء السريع | Quick Start Script
```bash
./start.sh --check-only
```

### 4. تنظيف الذاكرة | Memory Cleanup
```bash
# تنظيف يدوي للذاكرة
curl -X POST http://localhost:8000/api/system/cleanup
```

## 📊 مراقبة الأداء | Performance Monitoring

### مقاييس النظام | System Metrics
```bash
# معلومات الذاكرة
curl http://localhost:8000/api/system/memory

# معلومات الأداء
curl http://localhost:8000/api/system/performance
```

### مراقبة الموارد | Resource Monitoring
```bash
# استهلاك المعالج
top -p $(pgrep -f "python.*app")

# استهلاك الذاكرة
ps aux | grep python | grep app
```

## 🔐 مشاكل الأمان | Security Issues

### مشكلة الرموز المميزة | Token Issues

**المشكلة | Problem:** رمز غير صحيح
**الحل | Solution:**
1. تحقق من صحة الرمز
2. أنشئ رمز جديد
3. استخدم النوع الصحيح للرمز

### مشكلة التشفير | Encryption Issues

**المشكلة | Problem:** فشل التشفير
**الحل | Solution:**
1. احذف ملف `.token_key`
2. أعد تشغيل التطبيق
3. أعد إنشاء الرموز

## 🐳 مشاكل Docker | Docker Issues

### مشكلة البناء | Build Issues
```bash
# بناء الصورة مع التفاصيل
docker build -f Dockerfile.optimized -t ai-distillation . --no-cache

# فحص السجلات
docker logs container_name
```

### مشكلة التشغيل | Runtime Issues
```bash
# تشغيل مع متغيرات البيئة
docker run -p 8000:8000 --env-file .env ai-distillation

# دخول الحاوية للتصحيح
docker exec -it container_name /bin/bash
```

## 📞 الحصول على المساعدة | Getting Help

### معلومات النظام | System Information
```bash
# جمع معلومات التصحيح
curl http://localhost:8000/debug > debug_info.json
```

### تقرير الخطأ | Error Report
عند الإبلاغ عن خطأ، يرجى تضمين:

1. **معلومات النظام | System Info:**
   - نظام التشغيل
   - إصدار Python
   - حجم الذاكرة

2. **رسالة الخطأ | Error Message:**
   - النص الكامل للخطأ
   - السجلات ذات الصلة

3. **خطوات الإعادة | Reproduction Steps:**
   - الخطوات لإعادة إنتاج الخطأ
   - الإعدادات المستخدمة

### الموارد المفيدة | Helpful Resources

- **التوثيق الرسمي | Official Documentation:** README.md
- **دليل الميزات | Features Guide:** FEATURES.md
- **ملف التكوين | Configuration File:** config.yaml
- **متغيرات البيئة | Environment Variables:** .env.example

## ✅ قائمة التحقق | Checklist

قبل الإبلاغ عن مشكلة، تأكد من:

- [ ] تشغيل `python fix_imports.py`
- [ ] فحص السجلات في `logs/app.log`
- [ ] تجربة النسخة المبسطة `app_minimal.py`
- [ ] التحقق من متغيرات البيئة
- [ ] فحص مساحة القرص والذاكرة
- [ ] تحديث التبعيات `pip install -r requirements.txt`

---

💡 **نصيحة:** استخدم النسخة المبسطة `app_minimal.py` لتشخيص المشاكل بسرعة!