# مستندات API مدیریت صفحه اصلی

## فهرست

1. [مدیریت ویژگی‌های صفحه اصلی (Home Features)](#home-features)
2. [مدیریت ویترین محصولات (Product Showcases)](#product-showcases)
3. [ویترین‌های خودکار (Auto Showcases)](#auto-showcases)

---

## <a name="home-features"></a>1. مدیریت ویژگی‌های صفحه اصلی

این بخش برای مدیریت باکس‌های کوچک مثل "ارسال رایگان"، "پشتیبانی 24/7" و... استفاده می‌شود.

### دریافت ویژگی‌ها (عمومی)

```http
GET /api/home-features
```

**پاسخ نمونه:**
```json
{
  "data": [
    {
      "id": 1,
      "title": "ارسال رایگان",
      "description": "برای سفارش‌های بالای 500 هزار تومان",
      "icon": "Truck",
      "bg_color": "#E3F2FD",
      "icon_color": "#1976D2",
      "text_color": "#0D47A1",
      "sort_order": 1,
      "is_active": true
    }
  ]
}
```

### دریافت تمام ویژگی‌ها (مدیریت)

```http
GET /api/admin/home-features
Authorization: Bearer {token}
```

### ایجاد ویژگی جدید

```http
POST /api/admin/home-features
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "ارسال سریع",
  "description": "ارسال در کمتر از 24 ساعت",
  "icon": "Zap",
  "bg_color": "#FFF3E0",
  "icon_color": "#F57C00",
  "text_color": "#E65100",
  "sort_order": 5,
  "is_active": true
}
```

**آیکون‌های پیشنهادی:**
- `Truck` - کامیون (ارسال)
- `Headphones` - هدفون (پشتیبانی)
- `ShieldCheck` - سپر (ضمانت)
- `CreditCard` - کارت اعتباری (پرداخت)
- `Gift` - هدیه
- `Award` - جایزه
- `Zap` - برق (سرعت)
- `Heart` - قلب
- `Star` - ستاره

### ویرایش ویژگی

```http
PUT /api/admin/home-features/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "ارسال رایگان",
  "description": "برای سفارش‌های بالای 300 هزار تومان",
  "icon": "Truck",
  "is_active": true
}
```

### حذف ویژگی

```http
DELETE /api/admin/home-features/{id}
Authorization: Bearer {token}
```

---

## <a name="product-showcases"></a>2. مدیریت ویترین محصولات

این بخش برای ساخت ویترین‌های سفارشی محصولات استفاده می‌شود.

### دریافت ویترین‌ها (عمومی)

```http
GET /api/product-showcases
```

**پاسخ نمونه:**
```json
{
  "data": [
    {
      "id": 1,
      "title": "پرفروش‌ترین محصولات",
      "subtitle": "محصولاتی که مشتریان بیشتر خریداری کرده‌اند",
      "display_type": "grid",
      "bg_color": "#F5F5F5",
      "title_color": "#1976D2",
      "products": [
        {
          "id": 1,
          "name": "محصول 1",
          "price": "150000",
          "discount_price": "120000",
          "primary_image": {...},
          "category": {...}
        }
      ]
    }
  ]
}
```

### دریافت لیست ویترین‌ها (مدیریت)

```http
GET /api/admin/product-showcases
Authorization: Bearer {token}
```

### دریافت جزئیات یک ویترین

```http
GET /api/admin/product-showcases/{id}
Authorization: Bearer {token}
```

### ایجاد ویترین دستی

```http
POST /api/admin/product-showcases
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "محصولات ویژه",
  "subtitle": "بهترین انتخاب‌های ما برای شما",
  "display_type": "grid",
  "products_limit": 8,
  "bg_color": "#F5F5F5",
  "title_color": "#1976D2",
  "sort_order": 1,
  "is_active": true,
  "product_ids": [1, 2, 3, 4, 5, 6, 7, 8]
}
```

**مقادیر `display_type`:**
- `grid` - نمایش شبکه‌ای (پیش‌فرض)
- `carousel` - اسلایدر
- `list` - لیست عمودی

### ویرایش ویترین

```http
PUT /api/admin/product-showcases/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "محصولات ویژه",
  "subtitle": "بهترین پیشنهادات",
  "display_type": "carousel",
  "products_limit": 10,
  "is_active": true,
  "product_ids": [1, 3, 5, 7, 9, 11]
}
```

### حذف ویترین

```http
DELETE /api/admin/product-showcases/{id}
Authorization: Bearer {token}
```

---

## <a name="auto-showcases"></a>3. ویترین‌های خودکار

این API به شما اجازه می‌دهد که به صورت خودکار ویترین‌هایی بر اساس معیارهای مختلف بسازید.

### دریافت انواع ویترین‌های خودکار

```http
GET /api/admin/auto-showcases/types
Authorization: Bearer {token}
```

**پاسخ نمونه:**
```json
{
  "data": [
    {
      "type": "best_sellers",
      "title": "پرفروش‌ترین محصولات",
      "description": "محصولاتی که بیشترین فروش را داشته‌اند",
      "icon": "TrendingUp"
    },
    {
      "type": "discounted",
      "title": "محصولات تخفیف‌دار",
      "description": "محصولاتی که تخفیف دارند",
      "icon": "Percent"
    },
    {
      "type": "newest",
      "title": "جدیدترین محصولات",
      "description": "تازه‌ترین محصولات اضافه شده",
      "icon": "Sparkles"
    },
    {
      "type": "featured",
      "title": "محصولات ویژه",
      "description": "محصولات منتخب و برگزیده",
      "icon": "Star"
    },
    {
      "type": "high_rated",
      "title": "محصولات پربازدید",
      "description": "محصولاتی که بیشترین بازدید را داشته‌اند",
      "icon": "Eye"
    }
  ]
}
```

### پیش‌نمایش محصولات یک نوع ویترین

قبل از ساخت ویترین، می‌توانید ببینید چه محصولاتی در آن قرار می‌گیرند:

```http
POST /api/admin/auto-showcases/preview
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "best_sellers",
  "limit": 10
}
```

**پاسخ نمونه:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "محصول پرفروش 1",
      "price": "150000",
      "primary_image": {...}
    }
  ],
  "count": 10
}
```

### ساخت ویترین خودکار

```http
POST /api/admin/auto-showcases/create
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "best_sellers",
  "title": "پرفروش‌ترین‌ها",
  "subtitle": "محصولاتی که دیگران خریدند",
  "display_type": "grid",
  "products_limit": 8,
  "bg_color": "#F5F5F5",
  "title_color": "#1976D2",
  "is_active": true
}
```

**نکته:** اگر `title` را ندهید، عنوان پیش‌فرض برای آن نوع استفاده می‌شود.

---

## نمونه استفاده در React/Vue

### دریافت و نمایش ویژگی‌های صفحه اصلی

```javascript
// دریافت ویژگی‌ها
const response = await fetch('/api/home-features');
const { data: features } = await response.json();

// نمایش
features.map(feature => (
  <div style={{
    backgroundColor: feature.bg_color,
    color: feature.text_color
  }}>
    <Icon name={feature.icon} color={feature.icon_color} />
    <h3>{feature.title}</h3>
    <p>{feature.description}</p>
  </div>
));
```

### دریافت و نمایش ویترین‌ها

```javascript
// دریافت ویترین‌ها
const response = await fetch('/api/product-showcases');
const { data: showcases } = await response.json();

// نمایش
showcases.map(showcase => (
  <section style={{
    backgroundColor: showcase.bg_color
  }}>
    <h2 style={{ color: showcase.title_color }}>
      {showcase.title}
    </h2>
    <p>{showcase.subtitle}</p>
    
    <div className={`display-${showcase.display_type}`}>
      {showcase.products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  </section>
));
```

### ساخت ویترین خودکار از پنل ادمین

```javascript
// 1. دریافت انواع ویترین
const typesResponse = await fetch('/api/admin/auto-showcases/types', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const { data: types } = await typesResponse.json();

// 2. پیش‌نمایش محصولات
const previewResponse = await fetch('/api/admin/auto-showcases/preview', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'best_sellers',
    limit: 10
  })
});
const { data: products } = await previewResponse.json();

// 3. ساخت ویترین
const createResponse = await fetch('/api/admin/auto-showcases/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'best_sellers',
    title: 'پرفروش‌ترین‌ها',
    display_type: 'grid',
    products_limit: 8,
    is_active: true
  })
});
const { data: showcase } = await createResponse.json();
```

---

## نکات مهم

1. **ترتیب نمایش:** استفاده از فیلد `sort_order` برای مرتب‌سازی
2. **فعال/غیرفعال:** از `is_active` برای نمایش/مخفی کردن استفاده کنید
3. **رنگ‌ها:** از فرمت HEX (`#RRGGBB`) استفاده کنید
4. **محدودیت محصولات:** `products_limit` حداکثر تعداد محصولات در هر ویترین
5. **انواع نمایش:** `grid` برای دسکتاپ، `carousel` برای موبایل مناسب‌تر است

---

## اجرای سیدرها (داده‌های نمونه)

برای ایجاد داده‌های نمونه:

```bash
php artisan db:seed --class=HomeFeaturesSeeder
php artisan db:seed --class=ProductShowcasesSeeder
```

یا همه سیدرها با هم:

```bash
php artisan db:seed
```