Dovodi_Backend/apps/podcast/README_COLLECTIONS.md

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

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

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

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/

---

ساختار فنی

مدل‌ها

# مدل پایه
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)
• عدم نمایش نوع کالکشن در لیست
• سردرگمی در یافتن بخش مناسب