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

## 📋 خلاصه قابلیت‌های اضافه شده

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

### ✅ قابلیت‌های اصلی

1. **مدیریت ویژگی‌های صفحه اصلی (Home Features)**
   - ساخت باکس‌های ویژگی مثل "ارسال رایگان"، "پشتیبانی 24/7"
   - ویرایش متن‌ها، آیکون‌ها و رنگ‌ها
   - حذف و فعال/غیرفعال کردن

2. **ویترین‌های محصولات دستی (Manual Showcases)**
   - ساخت ویترین با انتخاب دستی محصولات
   - تنظیم عنوان، زیرعنوان و رنگ‌ها
   - انتخاب نوع نمایش (شبکه، اسلایدر، لیست)

3. **ویترین‌های خودکار (Auto Showcases)**
   - پرفروش‌ترین محصولات
   - محصولات تخفیف‌دار
   - جدیدترین محصولات
   - محصولات ویژه
   - محصولات پربازدید

---

## 📁 فایل‌های اضافه شده

### کنترلرها
- ✅ `app/Http/Controllers/HomeFeatureController.php` (از قبل وجود داشت)
- ✅ `app/Http/Controllers/ProductShowcaseController.php` (از قبل وجود داشت)
- ✨ `app/Http/Controllers/AutoShowcaseController.php` **(جدید)**

### مدل‌ها
- ✅ `app/Models/HomeFeature.php` (از قبل وجود داشت)
- ✅ `app/Models/ProductShowcase.php` (از قبل وجود داشت)
- ✅ `app/Models/ProductShowcaseItem.php` (از قبل وجود داشت)

### مایگریشن‌ها
- ✅ `database/migrations/2026_06_15_095511_create_home_features_table.php` (از قبل وجود داشت)
- ✅ `database/migrations/2026_06_16_075026_create_product_showcases_table.php` (از قبل وجود داشت)

### سیدرها (Seeders)
- ✨ `database/seeders/HomeFeaturesSeeder.php` **(جدید)**
- ✨ `database/seeders/ProductShowcasesSeeder.php` **(جدید)**

### مستندات
- ✨ `docs/HOME_PAGE_MANAGEMENT_API.md` - مستندات کامل API **(جدید)**
- ✨ `docs/HOMEPAGE_SETUP.md` - راهنمای راه‌اندازی **(جدید)**
- ✨ `docs/FRONTEND_EXAMPLES.md` - نمونه کدهای React **(جدید)**

### اسکریپت‌ها
- ✨ `SETUP_COMMANDS.bat` - اجرای خودکار راه‌اندازی **(جدید)**

### روت‌ها
- ✅ `routes/api.php` - روت‌های جدید اضافه شدند

---

## 🚀 راه‌اندازی سریع

### گام 1: اجرای مایگریشن‌ها

```bash
php artisan migrate
```

### گام 2: اجرای سیدرها (اختیاری - برای داده‌های نمونه)

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

**یا استفاده از اسکریپت خودکار:**

```bash
SETUP_COMMANDS.bat
```

### گام 3: تست API‌ها

```bash
# دریافت ویژگی‌های صفحه اصلی
curl http://localhost:8000/api/home-features

# دریافت ویترین محصولات
curl http://localhost:8000/api/product-showcases
```

---

## 📡 API Endpoints

### عمومی (Public)

```
GET  /api/home-features           # دریافت ویژگی‌های فعال
GET  /api/product-showcases       # دریافت ویترین‌های فعال
```

### مدیریتی (Admin - نیاز به توکن)

#### Home Features
```
GET     /api/admin/home-features        # لیست تمام ویژگی‌ها
POST    /api/admin/home-features        # ایجاد ویژگی جدید
PUT     /api/admin/home-features/{id}   # ویرایش ویژگی
DELETE  /api/admin/home-features/{id}   # حذف ویژگی
```

#### Product Showcases
```
GET     /api/admin/product-showcases        # لیست تمام ویترین‌ها
GET     /api/admin/product-showcases/{id}   # جزئیات ویترین
POST    /api/admin/product-showcases        # ایجاد ویترین دستی
PUT     /api/admin/product-showcases/{id}   # ویرایش ویترین
DELETE  /api/admin/product-showcases/{id}   # حذف ویترین
```

#### Auto Showcases
```
GET     /api/admin/auto-showcases/types     # انواع ویترین خودکار
POST    /api/admin/auto-showcases/preview   # پیش‌نمایش محصولات
POST    /api/admin/auto-showcases/create    # ساخت ویترین خودکار
```

---

## 💡 نمونه استفاده

### 1. ساخت ویژگی جدید

```javascript
const response = await fetch('/api/admin/home-features', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'بازگشت وجه',
    description: 'تا 7 روز ضمانت بازگشت وجه',
    icon: 'RefreshCw',
    bg_color: '#E8F5E9',
    icon_color: '#388E3C',
    text_color: '#1B5E20',
    is_active: true
  })
});
```

### 2. ساخت ویترین خودکار (پرفروش‌ها)

```javascript
const response = await fetch('/api/admin/auto-showcases/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'best_sellers',
    title: 'پرفروش‌ترین محصولات',
    subtitle: 'محبوب‌ترین محصولات میان مشتریان',
    display_type: 'grid',
    products_limit: 8,
    is_active: true
  })
});
```

### 3. ساخت ویترین دستی

```javascript
const response = await fetch('/api/admin/product-showcases', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'محصولات ویژه هفته',
    subtitle: 'بهترین انتخاب‌های ما',
    display_type: 'carousel',
    products_limit: 10,
    bg_color: '#F5F5F5',
    title_color: '#1976D2',
    product_ids: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19],
    is_active: true
  })
});
```

---

## 🎨 آیکون‌های پیشنهادی

استفاده از [Lucide Icons](https://lucide.dev/):

- **ارسال:** `Truck`, `Package`, `ShoppingCart`
- **پشتیبانی:** `Headphones`, `MessageCircle`, `Phone`
- **ضمانت:** `ShieldCheck`, `Award`, `BadgeCheck`
- **پرداخت:** `CreditCard`, `Wallet`, `DollarSign`
- **سرعت:** `Zap`, `Rocket`, `Clock`
- **هدیه:** `Gift`, `Heart`, `Star`
- **بازگشت:** `RefreshCw`, `RotateCcw`

---

## 🎯 انواع ویترین خودکار

| نوع | توضیح | معیار |
|-----|-------|-------|
| `best_sellers` | پرفروش‌ترین محصولات | بر اساس تعداد سفارشات |
| `discounted` | محصولات تخفیف‌دار | محصولات با discount_price |
| `newest` | جدیدترین محصولات | بر اساس تاریخ ایجاد |
| `featured` | محصولات ویژه | بر اساس قیمت |
| `high_rated` | محصولات پربازدید | بر اساس تعامل |

---

## 📱 انواع نمایش ویترین

| نوع | توضیح | مناسب برای |
|-----|-------|------------|
| `grid` | نمایش شبکه‌ای | دسکتاپ و تبلت |
| `carousel` | اسلایدر | موبایل |
| `list` | نمایش لیستی | جزئیات بیشتر |

---

## 🎨 پالت‌های رنگی پیشنهادی

```javascript
// آبی (ارسال)
{ bg: "#E3F2FD", icon: "#1976D2", text: "#0D47A1" }

// بنفش (پشتیبانی)
{ bg: "#F3E5F5", icon: "#7B1FA2", text: "#4A148C" }

// سبز (ضمانت)
{ bg: "#E8F5E9", icon: "#388E3C", text: "#1B5E20" }

// نارنجی (پرداخت)
{ bg: "#FFF3E0", icon: "#F57C00", text: "#E65100" }

// قرمز (تخفیف)
{ bg: "#FFEBEE", icon: "#C62828", text: "#B71C1C" }

// طوسی (خنثی)
{ bg: "#F5F5F5", icon: "#616161", text: "#212121" }
```

---

## 📚 مستندات کامل

برای جزئیات بیشتر، فایل‌های زیر را مطالعه کنید:

- **`docs/HOME_PAGE_MANAGEMENT_API.md`** - مستندات کامل API
- **`docs/HOMEPAGE_SETUP.md`** - راهنمای راه‌اندازی و عیب‌یابی
- **`docs/FRONTEND_EXAMPLES.md`** - نمونه کدهای React و Vue

---

## ✅ چک‌لیست راه‌اندازی

- [ ] مایگریشن‌ها اجرا شدند (`php artisan migrate`)
- [ ] سیدرها اجرا شدند (اختیاری)
- [ ] روت‌های جدید اضافه شدند
- [ ] کنترلر `AutoShowcaseController` ایجاد شد
- [ ] توکن احراز هویت برای تست API‌ها آماده است
- [ ] فرانت‌اند برای استفاده از API‌ها آماده است

---

## 🐛 عیب‌یابی

### مشکل: ویترین خودکار خالی است

```bash
# بررسی تعداد محصولات فعال
php artisan tinker
>>> App\Models\Product::where('is_active', true)->count();
```

### مشکل: آیکون‌ها نمایش داده نمی‌شوند

در فرانت‌اند، کتابخانه Lucide React را نصب کنید:

```bash
npm install lucide-react
```

### مشکل: خطای 401 Unauthorized

مطمئن شوید که توکن احراز هویت صحیح است و کاربر نقش `super_admin` دارد.

---

## 📞 پشتیبانی

برای سوالات و مشکلات، به مستندات مراجعه کنید یا با تیم توسعه تماس بگیرید.

---

## 🎉 تست سریع

برای اطمینان از نصب صحیح:

```bash
# 1. مایگریشن‌ها
php artisan migrate:status

# 2. تست API عمومی
curl http://localhost:8000/api/home-features
curl http://localhost:8000/api/product-showcases

# 3. تست API مدیریتی (با توکن)
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8000/api/admin/auto-showcases/types
```

اگر همه موارد بالا کار کرد، سیستم با موفقیت نصب شده است! 🎊