# نظام تتبع المشاهدات الفريدة (Polymorphic Views System)

## نظرة عامة
نظام عام ومرن لتتبع المشاهدات الفريدة لأي موديل في التطبيق (Gallery, Project، وأي موديل آخر في المستقبل).

## الملفات المضافة/المعدلة

### 1. Migrations
- `2026_01_29_193500_add_views_to_galleries_table.php` - إضافة عمود views لجدول galleries
- `2026_01_29_194100_create_views_table.php` - جدول polymorphic لتتبع المشاهدات الفريدة
- `2026_01_29_194200_add_views_to_projects_table.php` - إضافة عمود views لجدول projects

### 2. Models
- `app/Models/View.php` - موديل polymorphic جديد لتتبع المشاهدات
- `app/Traits/Viewable.php` - Trait قابل لإعادة الاستخدام
- `app/Models/Gallery.php` - إضافة Viewable trait
- `app/Models/Project.php` - إضافة Viewable trait

### 3. Controllers
- `app/Http/Controllers/Front/User/GalleryController.php` - تحديث منطق المشاهدات
- `app/Http/Controllers/Front/FreelancerController.php` - تحديث منطق المشاهدات
- `app/Http/Controllers/Front/ProjectController.php` - تحديث منطق المشاهدات للمشاريع

### 4. Views
- `resources/views/front/project/_project_details_box.blade.php` - إضافة عرض عدد المشاهدات

## كيفية العمل

### البنية Polymorphic:
```
جدول views:
- viewable_id (معرف العنصر)
- viewable_type (نوع العنصر: Gallery, Project، إلخ)
- user_id (للمستخدمين المسجلين)
- ip_address (للزوار)
- viewed_at (وقت المشاهدة)
```

### للمستخدمين المسجلين:
- يتم تسجيل المشاهدة بناءً على `user_id`
- كل مستخدم يُحسب مرة واحدة فقط لكل عنصر

### للزوار (غير مسجلين):
- يتم تسجيل المشاهدة بناءً على `ip_address`
- كل IP يُحسب مرة واحدة فقط لكل عنصر

### آلية العمل:
1. عند زيارة صفحة عنصر (عمل أو مشروع)، يتم استدعاء `$model->recordView()`
2. يتحقق النظام من وجود مشاهدة سابقة من نفس المستخدم/IP
3. إذا لم توجد مشاهدة سابقة:
   - يتم إنشاء سجل جديد في جدول `views`
   - يتم زيادة عداد `views` في جدول الموديل
4. إذا وجدت مشاهدة سابقة:
   - لا يتم فعل شيء (لا تكرار)

## كيفية الاستخدام

### إضافة تتبع المشاهدات لموديل جديد:

#### 1. إضافة عمود views للجدول:
```php
Schema::table('your_table', function (Blueprint $table) {
    $table->unsignedBigInteger('views')->default(0);
});
```

#### 2. إضافة Viewable trait للموديل:
```php
use App\Traits\Viewable;

class YourModel extends Model
{
    use Viewable;
    
    protected $fillable = ['views', /* ... */];
}
```

#### 3. تسجيل المشاهدة في Controller:
```php
$userId = auth()->check() ? auth()->user()->id : null;
$ipAddress = request()->ip();

$viewRecorded = $model->recordView($userId, $ipAddress);

if ($viewRecorded) {
    $model->increment('views');
}
```

### الدوال المتاحة من Viewable Trait:

```php
// تسجيل مشاهدة
$model->recordView($userId, $ipAddress);

// الحصول على عدد المشاهدات
$model->views_count; // أو
$model->views()->count();

// التحقق من مشاهدة سابقة
$model->hasBeenViewedBy($userId, $ipAddress);
```

## الأوامر المطلوبة على السيرفر

```bash
# تنفيذ جميع الـ Migrations
php artisan migrate
```

سيتم تنفيذ 3 migrations:
1. إضافة عمود views لجدول galleries
2. إنشاء جدول views (polymorphic)
3. إضافة عمود views لجدول projects

## المميزات

✅ **نظام عام وقابل لإعادة الاستخدام** - يمكن استخدامه مع أي موديل
✅ **Polymorphic Relations** - جدول واحد لتتبع جميع الموديلات
✅ **منع التكرار** - كل مستخدم/IP يُحسب مرة واحدة فقط
✅ **يدعم المستخدمين المسجلين والزوار**
✅ **سهل الإضافة لموديلات جديدة** - فقط أضف Trait
✅ **أداء محسّن** - Indexes على الحقول المهمة
✅ **Unique Constraints** - حماية من التكرار على مستوى قاعدة البيانات

## أمثلة الاستخدام

### Gallery (معرض الأعمال):
```php
$gallery = Gallery::find($id);
$gallery->recordView($userId, $ipAddress);
echo "المشاهدات: " . $gallery->views;
```

### Project (المشاريع):
```php
$project = Project::find($id);
$project->recordView($userId, $ipAddress);
echo "المشاهدات: " . $project->views;
```

### أي موديل آخر:
```php
// فقط أضف Viewable trait وعمود views
$anyModel->recordView($userId, $ipAddress);
```

## ملاحظات
- الأخطاء المعروضة في IDE (intelephense) هي أخطاء عادية ولا تؤثر على التشغيل
- النظام يدعم IPv4 و IPv6 (حقل ip_address بطول 45 حرف)
- يوجد unique constraint على (viewable_id, viewable_type, user_id) لمنع التكرار
- النظام يستخدم Polymorphic Relations من Laravel بشكل كامل