# استراتيجية السجلات وتتبع الأخطاء — Logging & Error Tracking

---

## القسم الأول: تسجيل العمليات (Application Logging)

### الأساس: Laravel Log Facade

يتم استخدام **Laravel Log facade** المدمج لتسجيل العمليات الحرجة في النظام دون الاعتماد على حزم خارجية.

---

### العمليات التي تُسجل

| العملية | مستوى السجل | التفاصيل المسجلة |
|---------|:---------:|------------------|
| تسجيل دخول ناجح | `info` | user_id, ip, time |
| تسجيل دخول فاشل | `warning` | email, ip, reason |
| إنشاء طالب | `info` | student_id, created_by |
| تعديل طالب | `info` | student_id, changed_fields |
| حذف طالب | `warning` | student_id, deleted_by |
| تسجيل حضور | `info` | student_id, status, date |
| تسجيل دفعة | `info` | student_id, amount, method |
| تغيير صلاحية/دور | `warning` | role, changed_by |
| خطأ في النظام (exception) | `error` | exception message, stack trace |

---

### استخدام Log Facade

```php
use Illuminate\Support\Facades\Log;

// تسجيل عملية ناجحة
Log::info('Student created', [
    'student_id' => $student->id,
    'created_by' => auth()->id(),
]);

// تسجيل محاولة فاشلة
Log::warning('Login failed', [
    'email' => $request->email,
    'ip' => $request->ip(),
]);

// تسجيل خطأ
Log::error('Payment processing failed', [
    'student_id' => $studentId,
    'exception' => $e->getMessage(),
]);
```

---

## القسم الثاني: تتبع الأخطاء (Error Tracking)

### الأساس: Laravel Daily Logs

الاعتماد على **سجلات Laravel اليومية** فقط لتتبع الأخطاء في الإصدار الأول.

> **Sentry** قيد الدراسة كخيار اختياري مستقبلي (TBD / optional for v1).

---

### Log Channels (Laravel)

```php
// config/logging.php
'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily'],
        'ignore_exceptions' => false,
    ],
    'daily' => [
        'driver' => 'daily',
        'path' => storage_path('logs/laravel.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 30,
    ],
],
```

---

### آلية الإبلاغ عن الأخطاء

```
Exception يحدث
  → Laravel Exception Handler
    → يُسجل في log file (Laravel daily log)
    → للمطورين: مراجعة السجلات يدويًا عند الحاجة
```

---

## خلاصة: مكدس المراقبة (v1)

| الطبقة | الأداة | الغرض |
|--------|--------|-------|
| Error Logging | Laravel Daily Logs | سجلات محلية للأخطاء |
| Failed Jobs | Laravel failed_jobs table | تخزين الـ Jobs الفاشلة |

---

## نقاط مهمة

1. **لا تُسجل البيانات الحساسة** — كلمات المرور، tokens، أرقام بطاقات الدفع لا تظهر في الـ logs أبدًا.
2. **سجلات الأداء متوسطة المستوى** — في بيئة الإنتاج log level = `warning` فأعلى، debug فقط للتطوير.