# 🚀 دليل التطويرات الجديدة - نظام إدارة المختبر

## ✅ التطويرات المكتملة 100%

تم تطوير النظام بالكامل بدون أي نقص. جميع التطويرات المطلوبة تم تنفيذها بنجاح.

---

## 📦 الملفات الجديدة

### Core Classes
- `src/Core/CSRFProtection.php` - حماية CSRF
- `src/Core/RateLimiter.php` - Rate Limiting
- `src/Core/FileUploadValidator.php` - التحقق من الملفات
- `src/Core/Logger.php` - نظام التسجيل
- `src/Core/ErrorHandler.php` - معالج الأخطاء
- `src/Core/Validator.php` - فئة التحقق
- `src/Core/Cache.php` - نظام التخزين المؤقت
- `src/Core/MigrationRunner.php` - تشغيل migrations

### Helper Files
- `src/helpers.php` - دوال مساعدة

### Scripts
- `scripts/run_migrations.php` - تشغيل migrations

---

## 🔧 الإعداد الأولي

### 1. تشغيل Migrations

```bash
php scripts/run_migrations.php
```

هذا سيقوم بتشغيل جميع migrations المعلقة مرة واحدة فقط.

### 2. إنشاء المجلدات المطلوبة

سيتم إنشاء المجلدات التالية تلقائياً:
- `cache/` - للتخزين المؤقت
- `logs/` - لملفات السجل

---

## 📖 دليل الاستخدام

### 1. CSRF Protection

#### في النماذج (Forms)
```php
<form method="post">
    <?php echo csrf_field(); ?>
    <!-- باقي الحقول -->
</form>
```

#### التحقق في POST Requests
```php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!csrf_validate()) {
        // خطأ - طلب غير صالح
        header('Location: page.php');
        exit;
    }
    // معالجة النموذج
}
```

#### للاستخدام في AJAX
```php
// جلب token
$token = csrf_token();

// إرساله في header أو data
fetch('/api/endpoint', {
    method: 'POST',
    headers: {
        'X-CSRF-Token': '<?php echo csrf_token(); ?>'
    },
    body: JSON.stringify(data)
});
```

---

### 2. Rate Limiting

#### في Login
```php
$rateLimiter = new \App\Core\RateLimiter($db);
$clientIp = \App\Core\RateLimiter::getClientIp();

$check = $rateLimiter->check(
    $clientIp,
    'login',
    5,      // الحد الأقصى للمحاولات
    900     // نافذة الوقت (15 دقيقة)
);

if (!$check['allowed']) {
    // حظر - تجاوز الحد
    echo 'تم تجاوز عدد المحاولات المسموح';
    exit;
}

// تسجيل محاولة
$rateLimiter->record($clientIp, 'login', 900);
```

#### في API Endpoints
```php
$rateLimiter = new \App\Core\RateLimiter($db);
$clientIp = \App\Core\RateLimiter::getClientIp();

$check = $rateLimiter->check(
    $clientIp,
    'api_call',
    100,    // 100 طلب
    3600    // في الساعة
);

if (!$check['allowed']) {
    json_response(['error' => 'Rate limit exceeded'], 429);
}
```

---

### 3. File Upload Security

#### التحقق من الملفات
```php
require_once __DIR__ . '/src/Core/FileUploadValidator.php';

$allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
$maxSize = 2 * 1024 * 1024; // 2MB

$validation = \App\Core\FileUploadValidator::validate(
    $_FILES['photo'],
    $allowedTypes,
    $maxSize
);

if (!$validation['valid']) {
    $errors = $validation['errors'];
    // عرض الأخطاء
} else {
    // الملف صالح
    $safeFileName = \App\Core\FileUploadValidator::generateSafeFileName(
        $_FILES['photo']['name'],
        $userId
    );
    
    // رفع الملف
    move_uploaded_file(
        $_FILES['photo']['tmp_name'],
        $uploadDir . $safeFileName
    );
}
```

---

### 4. Logger

#### الاستخدام الأساسي
```php
$logger = new \App\Core\Logger();

// معلومات
$logger->info('User logged in', ['user_id' => 123]);

// تحذير
$logger->warning('Low stock', ['item_id' => 456, 'quantity' => 5]);

// خطأ
$logger->error('Database error', ['error' => $e->getMessage()]);

// خطأ حرج
$logger->critical('System failure', ['component' => 'payment']);

// استثناء
try {
    // code
} catch (\Exception $e) {
    $logger->exception($e);
}

// طلب HTTP
$logger->request('POST', '/api/endpoint', ['data' => $data]);
```

---

### 5. Error Handler

تم تسجيله تلقائياً في `index.php` و `doctor.php`.

#### في بيئة التطوير
```php
// في config.php
'debug' => true
```

#### في بيئة الإنتاج
```php
// في config.php
'debug' => false
```

---

### 6. Validator

#### الاستخدام الأساسي
```php
use App\Core\Validator;

$data = [
    'email' => $_POST['email'],
    'password' => $_POST['password'],
    'age' => $_POST['age']
];

$rules = [
    'email' => 'required|email',
    'password' => 'required|min:8',
    'age' => 'required|integer|min:18|max:100'
];

$validator = Validator::make($data, $rules);

if ($validator->fails()) {
    $errors = $validator->errors();
    // عرض الأخطاء
} else {
    // البيانات صحيحة
}
```

#### القواعد المتاحة
- `required` - مطلوب
- `email` - بريد إلكتروني
- `phone` - رقم هاتف
- `numeric` - رقم
- `integer` - عدد صحيح
- `min:value` - الحد الأدنى
- `max:value` - الحد الأقصى
- `date` - تاريخ
- `date_format:format` - صيغة تاريخ
- `in:value1,value2` - قيم محددة
- `regex:pattern` - نمط regex
- `url` - رابط
- `same:field` - مطابقة حقل آخر

---

### 7. Cache

#### الاستخدام الأساسي
```php
$cache = new \App\Core\Cache();

// حفظ
$cache->set('key', $value, 3600); // TTL: ساعة واحدة

// جلب
$value = $cache->get('key');

// التحقق من الوجود
if ($cache->has('key')) {
    // موجود
}

// Remember Pattern (جلب أو حفظ)
$value = $cache->remember('key', function() {
    // عملية مكلفة
    return expensiveOperation();
}, 3600);

// حذف
$cache->delete('key');

// مسح الكل
$cache->clear();
```

#### مثال: Cache للـ Roles
```php
$roles = $cache->remember('roles_list', function() use ($db) {
    $stmt = $db->query('SELECT * FROM roles');
    return $stmt->fetchAll();
}, 7200); // ساعتان
```

---

### 8. Helper Functions

#### HTML Escape
```php
echo e($userInput); // بدلاً من htmlspecialchars
```

#### CSRF
```php
csrf_field();    // hidden input
csrf_token();    // token value
csrf_validate(); // validate
```

#### Formatting
```php
format_currency(1000, 'IQD'); // 1,000.00 د.ع
format_date('2024-01-01');    // 2024-01-01
format_datetime('2024-01-01 10:00:00'); // 2024-01-01 10:00
time_ago('2024-01-01 10:00:00'); // منذ ساعة
```

#### Conditions
```php
$tenantCond = tenant_condition($tenantId, 'o');
$doctorCond = doctor_condition($doctorId, 'o');
```

#### Responses
```php
json_response(['success' => true], 200);
redirect('page.php', 302);
```

---

## ⚙️ الإعدادات

### config/config.php

```php
'session' => [
    'cookie_secure' => true,
    'cookie_httponly' => true,
    'cookie_samesite' => 'Strict',
    'regenerate_id' => true,
    'lifetime' => 1800
],
'rate_limiting' => [
    'enabled' => true,
    'login_max_attempts' => 5,
    'login_window_seconds' => 900,
    'login_block_duration' => 3600
],
'cache' => [
    'enabled' => true,
    'default_ttl' => 3600
],
'logging' => [
    'enabled' => true,
    'level' => 'info'
],
'debug' => false
```

---

## 🔍 الاختبار

### 1. اختبار CSRF
- حاول إرسال POST request بدون token → يجب أن يفشل
- أرسل POST request مع token صحيح → يجب أن ينجح

### 2. اختبار Rate Limiting
- حاول تسجيل الدخول 6 مرات متتالية → يجب أن يُحظر
- انتظر 15 دقيقة → يجب أن يُسمح بالدخول

### 3. اختبار File Upload
- ارفع ملف صورة → يجب أن ينجح
- ارفع ملف PHP → يجب أن يفشل
- ارفع ملف كبير جداً → يجب أن يفشل

### 4. اختبار Migrations
- شغّل `scripts/run_migrations.php` → يجب أن تعمل migrations مرة واحدة فقط
- شغّلها مرة أخرى → يجب أن تتخطى migrations المنفذة

---

## 📝 ملاحظات مهمة

1. **Migrations:** يجب تشغيلها مرة واحدة فقط بعد التحديث
2. **Cache:** سيتم تنظيفه تلقائياً
3. **Logs:** سيتم تدويرها تلقائياً (أقصى 5 ملفات)
4. **Session:** تأكد من تفعيل HTTPS في الإنتاج
5. **Rate Limiting:** الإعدادات في `config/config.php`

---

## 🎉 الخلاصة

جميع التطويرات مكتملة 100%:
- ✅ CSRF Protection
- ✅ Rate Limiting
- ✅ File Upload Security
- ✅ Session Security
- ✅ Error Handling
- ✅ Logging
- ✅ Validation
- ✅ Cache
- ✅ Migrations System
- ✅ Helper Functions

النظام الآن **أكثر أماناً، أسرع، وأسهل في الصيانة**.

---

**تاريخ التطوير:** <?php echo date('Y-m-d H:i:s'); ?>
