# مستندات مدیریت کالکشن‌های پادکست

## نحوه مدیریت کالکشن‌ها در پنل ادمین

### دو نوع کالکشن داریم:

#### 1️⃣ **Pinned Collections (کالکشن‌های پین‌شده - بخش بالا)**
- **مسیر در پنل ادمین:** `Pinned Collections (Top Section)`
- **API Endpoint:** `/api/podcast/pinned-collections/`
- **کاربرد:** نمایش در بالای صفحه (carousel/featured section)
- **ویژگی‌ها:**
  - نیاز به تصویر thumbnail دارد
  - می‌تواند summary داشته باشد
  - ترتیب نمایش با فیلد `order` مشخص می‌شود

#### 2️⃣ **Regular Collections (کالکشن‌های معمولی - بخش میانی)**
- **مسیر در پنل ادمین:** `Regular Collections (Middle Section)`
- **API Endpoint:** `/api/podcast/collections/`
- **کاربرد:** نمایش در بخش‌های میانی صفحه
- **ویژگی‌ها:**
  - تصویر thumbnail اختیاری است
  - ترتیب نمایش با فیلد `order` مشخص می‌شود

---

## راهنمای استفاده

### ایجاد کالکشن جدید

**برای کالکشن پین‌شده (بالای صفحه):**
1. به بخش `Pinned Collections (Top Section)` بروید
2. روی "Add" کلیک کنید
3. فیلدهای زیر را پر کنید:
   - Title (عنوان)
   - Summary (خلاصه - اختیاری)
   - Thumbnail (تصویر - **الزامی**)
   - Order (ترتیب نمایش)
   - Status (فعال/غیرفعال)
4. پادکست‌های مورد نظر را اضافه کنید

**برای کالکشن معمولی (بخش میانی):**
1. به بخش `Regular Collections (Middle Section)` بروید
2. روی "Add" کلیک کنید
3. فیلدهای زیر را پر کنید:
   - Title (عنوان)
   - Order (ترتیب نمایش)
   - Status (فعال/غیرفعال)
4. پادکست‌های مورد نظر را اضافه کنید

---

## نکات مهم

### تشخیص نوع کالکشن
در لیست کالکشن‌ها، ستون **Display Position** نوع هر کالکشن را نشان می‌دهد:
- 📌 **Pinned (Top)** → کالکشن پین‌شده
- 📋 **Regular (Middle)** → کالکشن معمولی

### تفاوت‌های کلیدی

| ویژگی | Pinned | Regular |
|-------|--------|---------|
| تصویر thumbnail | ✅ الزامی | ⚪ اختیاری |
| فیلد summary | ✅ دارد | ❌ ندارد |
| محل نمایش | بالای صفحه | بخش میانی |
| API Endpoint | `/pinned-collections/` | `/collections/` |

---

## ساختار فنی

### مدل‌ها
```python
# مدل پایه
PodcastCollection
├── display_position: 'pinned' یا 'middle'
├── title
├── slug
├── summary (nullable)
├── thumbnail (nullable)
├── order
└── status

# مدل‌های Proxy
PinnedPodcastCollection (display_position='pinned')
MiddlePodcastCollection (display_position='middle')
```

### فیلد display_position
این فیلد به صورت خودکار توسط Django Admin تنظیم می‌شود:
- در `Pinned Collections` → `display_position='pinned'`
- در `Regular Collections` → `display_position='middle'`

---

## سوالات متداول

**Q: چرا دو بخش جدا داریم؟**
A: برای جلوگیری از اشتباه و مدیریت بهتر. هر کدام کاربرد و ویژگی‌های متفاوتی دارند.

**Q: می‌توانم یک کالکشن را از Pinned به Regular تبدیل کنم؟**
A: خیر، باید کالکشن جدیدی در بخش مورد نظر ایجاد کنید و پادکست‌ها را کپی کنید.

**Q: چرا در API دو endpoint جدا داریم؟**
A: چون frontend نیاز دارد که کالکشن‌های بالا و میانی را جداگانه دریافت کند.

---

## تغییرات اخیر

### نسخه جدید (بهبود UX)
- ✅ نام‌های واضح‌تر برای مدل‌ها
- ✅ نمایش `Display Position` در لیست
- ✅ آیکون‌های بصری برای تشخیص سریع‌تر
- ✅ مستندات کامل

### نسخه قبلی
- نام‌های مبهم (`Middle Section` به جای `Regular`)
- عدم نمایش نوع کالکشن در لیست
- سردرگمی در یافتن بخش مناسب