# دليل استخدام Schema Markup - منصة ربحي

## 📚 جدول المحتويات

1. [Organization Schema](#organization-schema)
2. [WebSite Schema](#website-schema)
3. [HowTo Schema](#howto-schema)
4. [FAQPage Schema](#faqpage-schema)
5. [BreadcrumbList Schema](#breadcrumblist-schema)
6. [Article Schema](#article-schema)
7. [Person Schema](#person-schema)
8. [Review Schema](#review-schema)

---

## Organization Schema

**الاستخدام:** في جميع الصفحات (تلقائي)

```php
// يتم إضافته تلقائياً في master.blade.php
$schemas[] = \App\Services\SchemaService::organization();
```

**مثال مخصص:**
```php
$orgSchema = \App\Services\SchemaService::organization([
    'name' => 'منصة ربحي',
    'url' => 'https://rebhy.com',
    'logo' => asset('logo.png'),
    'description' => 'منصة عربية للعمل الحر',
]);
```

---

## WebSite Schema

**الاستخدام:** في الصفحة الرئيسية (تلقائي)

```php
// يتم إضافته تلقائياً في master.blade.php
$schemas[] = \App\Services\SchemaService::website();
```

**الناتج:**
```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "منصة ربحي",
  "url": "https://rebhy.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://rebhy.com/projects?search={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
```

---

## HowTo Schema

**الاستخدام:** في الصفحة الرئيسية أو صفحات الشرح

### في Controller:

```php
// app/Http/Controllers/Front/HomeController.php

public function index()
{
    $howToSchema = \App\Services\SchemaService::howTo([
        'name' => 'كيفية توظيف مستقل على منصة ربحي',
        'description' => 'دليل خطوة بخطوة لتوظيف أفضل المستقلين على منصة ربحي',
        'totalTime' => 'PT30M', // 30 دقيقة
        'estimatedCost' => [
            'currency' => 'SAR',
            'value' => '0'
        ],
        'step' => [
            [
                'name' => 'أضف المشروع',
                'text' => 'أضف تفاصيل مشروعك والمهارات المطلوبة لإنجازه وابدأ باستقبال عروض المستقلين',
                'url' => route('project.create')
            ],
            [
                'name' => 'اختر العرض المناسب',
                'text' => 'من بين العروض المقدمة لمشروعك، اختر العرض المناسب لمتطلبات المشروع ثم ابدأ مباشرة مرحلة التنفيذ',
                'url' => route('project.list')
            ],
            [
                'name' => 'استلم المشروع',
                'text' => 'سيعمل المستقل الذي اخترته معك حتى انتهاء العمل وتسليم مشروعك بشكل كامل كما أردته',
                'url' => route('home')
            ]
        ]
    ]);
    
    return view('front.main', compact('howToSchema'));
}
```

### في View:

```blade
{{-- resources/views/front/main.blade.php --}}

@section('schemas')
    @if(isset($howToSchema))
        <script type="application/ld+json">
            {!! \App\Services\SchemaService::toJsonLd($howToSchema) !!}
        </script>
    @endif
@endsection
```

---

## FAQPage Schema

**الاستخدام:** في صفحة الأسئلة الشائعة

### في Controller:

```php
// app/Http/Controllers/Front/FaqController.php

public function index()
{
    $faqs = [
        [
            'question' => 'كيف أبدأ العمل كمستقل على منصة ربحي؟',
            'answer' => 'سجل حساب مجاني، أكمل ملفك الشخصي، ثم تصفح المشاريع وقدم عروضك على المشاريع التي تناسب مهاراتك'
        ],
        [
            'question' => 'كيف يمكنني توظيف مستقل؟',
            'answer' => 'أضف مشروعك بالتفاصيل المطلوبة، انتظر استقبال العروض من المستقلين، ثم اختر العرض الأنسب وابدأ العمل'
        ],
        [
            'question' => 'هل المنصة آمنة؟',
            'answer' => 'نعم، منصة ربحي توفر نظام حماية كامل للمدفوعات وضمان حقوق الطرفين'
        ],
        [
            'question' => 'ما هي العمولة التي تأخذها المنصة؟',
            'answer' => 'تأخذ المنصة عمولة بسيطة من كل مشروع مكتمل، يمكنك الاطلاع على التفاصيل في صفحة الأسعار'
        ]
    ];
    
    $faqSchema = \App\Services\SchemaService::faqPage($faqs);
    
    return view('front.faqs', compact('faqs', 'faqSchema'));
}
```

---

## BreadcrumbList Schema

**الاستخدام:** في جميع الصفحات الداخلية

### في Controller:

```php
// مثال: صفحة تفاصيل المشروع

public function show($id)
{
    $project = Project::findOrFail($id);
    
    $breadcrumbs = [
        [
            'name' => 'الرئيسية',
            'url' => route('home')
        ],
        [
            'name' => 'المشاريع',
            'url' => route('project.list')
        ],
        [
            'name' => $project->title,
            'url' => route('project.details', $project->id)
        ]
    ];
    
    $breadcrumbSchema = \App\Services\SchemaService::breadcrumbList($breadcrumbs);
    
    return view('front.project-details', compact('project', 'breadcrumbs', 'breadcrumbSchema'));
}
```

### في View:

```blade
{{-- عرض Breadcrumbs للمستخدم --}}
<nav aria-label="breadcrumb">
  <ol class="breadcrumb" itemscope itemtype="https://schema.org/BreadcrumbList">
    @foreach($breadcrumbs as $index => $item)
    <li class="breadcrumb-item{{ $loop->last ? ' active' : '' }}" 
        itemprop="itemListElement" 
        itemscope 
        itemtype="https://schema.org/ListItem">
      @if(!$loop->last)
      <a itemprop="item" href="{{$item['url']}}">
        <span itemprop="name">{{$item['name']}}</span>
      </a>
      @else
      <span itemprop="name">{{$item['name']}}</span>
      @endif
      <meta itemprop="position" content="{{$index + 1}}" />
    </li>
    @endforeach
  </ol>
</nav>

{{-- Schema Markup (يتم إضافته تلقائياً في master.blade.php) --}}
```

---

## Article Schema

**الاستخدام:** في صفحات المدونة

### في Controller:

```php
// app/Http/Controllers/Front/BlogController.php

public function show($slug)
{
    $blog = Blog::where('slug', $slug)->firstOrFail();
    
    $articleSchema = \App\Services\SchemaService::article([
        'headline' => $blog->title,
        'description' => $blog->excerpt,
        'image' => asset($blog->image),
        'datePublished' => $blog->created_at->toIso8601String(),
        'dateModified' => $blog->updated_at->toIso8601String(),
        'url' => route('blog.show', $blog->slug),
        'articleBody' => strip_tags($blog->content),
        'category' => $blog->category->name ?? 'عام'
    ]);
    
    return view('front.blog-details', compact('blog', 'articleSchema'));
}
```

---

## Person Schema

**الاستخدام:** في صفحات المستقلين

### في Controller:

```php
// app/Http/Controllers/Front/FreelancerController.php

public function show($id)
{
    $freelancer = User::findOrFail($id);
    
    $personSchema = \App\Services\SchemaService::person([
        'name' => $freelancer->name,
        'url' => route('freelancers.show', $freelancer->id),
        'image' => asset($freelancer->image),
        'description' => $freelancer->bio,
        'jobTitle' => $freelancer->title ?? 'مستقل',
        'email' => $freelancer->public_email, // إذا كان متاح
        'address' => [
            'country' => $freelancer->country,
            'city' => $freelancer->city
        ]
    ]);
    
    return view('front.freelancer-profile', compact('freelancer', 'personSchema'));
}
```

---

## Review Schema

**الاستخدام:** في صفحات المستقلين مع التقييمات

### في Controller:

```php
public function show($id)
{
    $freelancer = User::findOrFail($id);
    $reviews = $freelancer->reviews;
    
    $reviewSchemas = [];
    foreach ($reviews as $review) {
        $reviewSchemas[] = \App\Services\SchemaService::review([
            'itemType' => 'Person',
            'itemName' => $freelancer->name,
            'ratingValue' => $review->rating,
            'bestRating' => 5,
            'author' => [
                'name' => $review->author->name
            ],
            'reviewBody' => $review->comment,
            'datePublished' => $review->created_at->toIso8601String()
        ]);
    }
    
    return view('front.freelancer-profile', compact('freelancer', 'reviewSchemas'));
}
```

---

## 🎯 أفضل الممارسات

### 1. **استخدم Schema مناسب لكل صفحة**
- الصفحة الرئيسية: Organization + WebSite + HowTo
- صفحات المشاريع: Service + BreadcrumbList
- صفحات المستقلين: Person + Review + BreadcrumbList
- صفحات المدونة: Article + BreadcrumbList
- صفحة FAQ: FAQPage + BreadcrumbList

### 2. **تحقق من صحة Schema**
استخدم: https://validator.schema.org/

### 3. **اختبر Rich Results**
استخدم: https://search.google.com/test/rich-results

### 4. **لا تبالغ في استخدام Schema**
- استخدم فقط Schema ذات صلة بالمحتوى
- لا تضع معلومات مضللة
- تأكد من تطابق Schema مع المحتوى المرئي

---

## 📊 أمثلة كاملة

### مثال: صفحة مشروع كاملة

```php
// Controller
public function show($id)
{
    $project = Project::with(['owner', 'category'])->findOrFail($id);
    
    // Breadcrumbs
    $breadcrumbs = [
        ['name' => 'الرئيسية', 'url' => route('home')],
        ['name' => 'المشاريع', 'url' => route('project.list')],
        ['name' => $project->title, 'url' => route('project.details', $project->id)]
    ];
    
    // Service Schema
    $serviceSchema = \App\Services\SchemaService::product([
        'name' => $project->title,
        'description' => $project->description,
        'url' => route('project.details', $project->id),
        'image' => asset($project->image),
        'category' => $project->category->name,
        'offers' => [
            'price' => $project->budget,
            'priceCurrency' => 'SAR'
        ],
        'provider' => [
            'name' => $project->owner->name,
            'url' => route('user.profile', $project->owner->id)
        ]
    ]);
    
    return view('front.project-details', compact('project', 'breadcrumbs', 'serviceSchema'));
}
```

---

## 🔧 استكشاف الأخطاء

### المشكلة: Schema لا يظهر في نتائج البحث
**الحل:**
1. تحقق من صحة Schema في validator.schema.org
2. انتظر بضعة أيام (Google يحتاج وقت للفهرسة)
3. تأكد من أن الصفحة مفهرسة في Search Console

### المشكلة: أخطاء في Schema Validator
**الحل:**
1. تأكد من وجود جميع الحقول المطلوبة
2. تحقق من صحة التواريخ (ISO 8601 format)
3. تأكد من صحة الروابط (URLs كاملة)

---

**آخر تحديث:** 2025-12-07  
**الإصدار:** 1.0