# راهنمای جامع پیاده‌سازی و تست سیستم انتشار خودکار پادکست (RSS Distribution & Import) این مستند یک نقشه راه عملیاتی از صفر تا صد است تا بدون وابستگی به اکانت‌های کارفرما، بتوانیم کل چرخه **تولید فید RSS در بک‌اند**، **ایمپورت از RSS خارجی** و **انتشار خودکار روی پلتفرم‌های پادکست (Castbox، Spotify، Apple Podcasts و Mave)** را با اکانت‌های تستی خودمان پیاده‌سازی و آزمایش کنیم. --- ## ۱. معماری کلی سیستم چگونه کار می‌کند؟ در اکوسیستم جهانی پادکست، پلتفرم‌های شنیدن پادکست فایل صوتی را از شما دریافت (Push) نمی‌کنند، بلکه از طریق یک لینک استاندارد **XML (RSS 2.0 + iTunes Tags)** که سرور شما تولید می‌کند، اپیزودها را می‌خوانند (Pull). ```mermaid sequenceDiagram autonumber participant Admin as "پنل ری‌اکت (ادمین)" participant Backend as "بک‌اند جنگو (Dovoodi)" participant RSS as "اندپوینت RSS (/api/podcast/rss.xml)" participant Platforms as "پلتفرم‌ها (Castbox / Apple / Spotify)" Admin->>Backend: آپلود اپیزود جدید (MP3 + کاور + عنوان + توضیحات) Backend->>Backend: ذخیره در جدول Podcast و محاسبه زمان (audio_time) Platforms->>RSS: درخواست دوره‌ای (Polling) برای بررسی اپیزودهای جدید RSS->>Backend: خواندن لیست اپیزودهای فعال از دیتابیس RSS-->>Platforms: برگرداندن XML استاندارد با تگ‌های و Platforms->>Platforms: انتشار خودکار اپیزود جدید در اپلیکیشن‌ها ``` --- ## ۲. پیش‌نیازهای فنی برای اینکه پلتفرم‌ها فید ما را قبول کنند پلتفرم‌های پادکست (مخصوصاً Apple Podcasts و Castbox) قبل از تایید لینک RSS شما، چند قانون فنی را اعتبارسنجی (Validate) می‌کنند: > [!IMPORTANT] > **الزامات اجباری فید RSS استاندارد پادکست:** > 1. **پشتیبانی از HTTPS و Byte-Range:** لینک فید RSS، لینک عکس کاور و لینک فایل‌های صوتی `.mp3` حتماً باید روی `https://` باشند و سرور وب (Nginx) باید هدر `Accept-Ranges: bytes` را روی فایل‌های صوتی برگرداند (که Nginx به‌صورت پیش‌فرض روی فایل‌های استاتیک/مدیا پشتیبانی می‌کند). > 2. **ابعاد تصویر کاور کانال (``):** تصویر کاور اصلی پادکست باید مربع (`1:1`) و حداقل **`1400x1400` پیکسل** و حداکثر **`3000x3000` پیکسل** (فرمت JPG یا PNG با رنگ RGB) باشد. > 3. **وجود حداقل ۱ اپیزود منتشرشده:** فید RSS بدون تگ `` (اپیزود) توسط پلتفرم‌ها تایید نمی‌شود؛ پس قبل از ثبت لینک در پلتفرم‌ها باید حداقل ۱ اپیزود تستی در پنل ساخته باشیم. > 4. **تگ `` معتبر:** داخل فید باید یک تگ `` وجود داشته باشد که به آن ایمیل دسترسی داشته باشید، چون پلتفرم‌هایی مثل Castbox و Spotify کد تایید مالکیت (OTP) را به همان ایمیل داخل فید می‌فرستند! --- ## ۳. پیاده‌سازی در کد پروژه (بک‌اند و پنل ری‌اکت) ### بخش الف: تغییرات بک‌اند جنگو (`dovoodi/backend`) #### ۱. مدل تنظیمات کانال پادکست (`PodcastChannelSettings` یا فیلدهای تکمیلی در `PodcastPlaylist`) در فایل `apps/podcast/models.py` یک مدل Singleton (یا سطح پلی‌لیست) برای نگهداری متادیتای کلی فید RSS تعریف می‌کنیم: - `title`: نام کانال پادکست (مثلاً `Про ислам`) - `description`: توضیحات کانال - `author`: نام گوینده/نویسنده (``) - `owner_name` و `owner_email`: نام و ایمیل مالک برای تایید مالکیت در پلتفرم‌ها (``) - `language`: کد زبان (مثلاً `ru` یا `en`) - `category` و `subcategory`: دسته‌بندی استاندارد اپل (مثلاً `Religion & Spirituality` -> `Islam`) - `copyright`: متن کپی‌رایت - `cover_image`: تصویر کاور اصلی کانال (۱۴۰۰×۱۴۰۰) - `explicit`: بولین (`false`) - `source_rss_url`: لینک RSS خارجی جهت ایمپورت/سینک (مثلاً `https://cloud.mave.digital/34205`) همچنین در مدل `Podcast`: - افزودن فیلد اختیاری `external_guid = models.CharField(max_length=255, null=True, blank=True, unique=True)` تا هنگام ایمپورت از RSS خارجی، از ساخت اپیزود تکراری جلوگیری شود و شناسه `` هر اپیزود ثابت بماند. - افزودن فیلدهای اختیاری `episode_number` و `season_number`. #### ۲. ساخت اندپوینت خروجی RSS XML در `apps/podcast/views.py` و `apps/podcast/urls.py` ایجاد یک View عمومی (بدون نیاز به توکن لاگین، چون سرورهای Apple و Castbox باید بتوانند آن را بخوانند) در مسیر: - `/api/podcast/rss.xml` (فید سراسری پادکست‌ها) - `/api/podcast/playlists//rss.xml` (فید اختصاصی هر پلی‌لیست) این View هدر `Content-Type: application/rss+xml; charset=utf-8` برمی‌گرداند و ساختار زیر را تولید می‌کند: ```xml <![CDATA[عنوان کانال]]> https://yourdomain.com ru episodic false نام نویسنده نام مالک your-test-email@gmail.com <![CDATA[عنوان اپیزود]]> podcast-uuid-or-id Thu, 23 Apr 2026 03:00:00 GMT 3037 false full ``` #### ۳. ساخت سرویس و اندپوینت Import از RSS خارجی (`/api/podcast/admin/import-rss/`) - دریافت آدرس فید (مثلاً `https://cloud.mave.digital/34205`) یا فایل XML. - پارس کردن تگ `` و تمام تگ‌های `` با `xml.etree.ElementTree`. - بررسی `guid` هر آیتم؛ اگر قبلاً در جدول `Podcast` وجود نداشت: - دانلود تصویر `` و فایل صوتی `` - تبدیل `` (ثانیه) به `datetime.time` برای فیلد `audio_time` - ذخیره اپیزود در دیتابیس. --- ### بخش ب: تغییرات پنل ری‌اکت (`dovodi-panel/dashboard`) در بخش پادکست‌های پنل (`src/pages/Podcasts.tsx` / `src/components/archive/ArchiveSectionPage.tsx`): 1. **کارت / مودال «RSS & Distribution Settings»:** - نمایش لینک RSS سایت ما همراه با دکمه **Copy RSS URL** و دکمه **Preview XML**. - فرم ویرایش مشخصات فید کانال (`Channel Title`، `Author`، `Owner Email` برای دریافت کد تایید پلتفرم‌ها، `Cover 1400x1400`، `Language`، `Category`). 2. **مودال «Import from RSS Feed»:** - ورودی لینک RSS (یا آپلود فایل XML فید) + انتخاب پلی‌لیست مقصد. - نمایش پیش‌نمایش تعداد اپیزودهای پیداشده در فید و شروع ایمپورت در پس‌زمینه. --- ## ۴. مراحل تست عملی توسط خودمان (با اکانت‌های تستی رایگان) برای اینکه بدون نیاز به کارفرما، کل فرآیند را خودمان تست کنیم، مراحل زیر را به ترتیب انجام می‌دهیم: ```mermaid flowchart LR A["۱. آماده‌سازی لینک عمومی\n(سرور تست یا Cloudflare Tunnel)"] --> B["۲. ساخت ۱ اپیزود تستی در پنل\nو تنظیم ایمیل خودمان در Owner Email"] B --> C["۳. تست اعتبارسنجی فید در\nCastFeedValidator / Podba.se"] C --> D["۴. ثبت فید در Castbox و Spotify\nو دریافت کد تایید روی ایمیل"] D --> E["۵. آپلود اپیزود دوم در پنل\nو مشاهده انتشار خودکار"] ``` ### گام ۱: قابل دسترس کردن بک‌اند روی اینترنت (اگر روی لوکال تست می‌کنید) چون سرورهای Castbox و Spotify باید بتوانند لینک RSS و فایل MP3 شما را دانلود کنند، نمی‌توانید آدرس `http://127.0.0.1:8000` را به آن‌ها بدهید. - **اگر روی سرور استیجینگ/پروداکشن هستید:** از همان دامنه `https://...` سرور استفاده کنید. - **اگر روی سیستم لوکال خودتان تست می‌کنید:** با یک دستور رایگان Cloudflare Tunnel یا ngrok یک لینک HTTPS عمومی بگیرید: ```powershell npx cloudflared tunnel --url http://127.0.0.1:8000 ``` این دستور یک آدرس مثل `https://random-name.trycloudflare.com` به شما می‌دهد که لینک فید شما می‌شود: `https://random-name.trycloudflare.com/api/podcast/rss.xml` ### گام ۲: تنظیم ایمیل خودتان در فید و ساخت اپیزود تستی اول 1. در تنظیمات RSS پنل، فیلد **Owner Email** را روی **ایمیل شخصی خودتان** (مثلاً جیمیل خودتان) بگذارید. 2. یک تصویر مربع حداقل `1400x1400` پیکسل برای کاور کانال انتخاب کنید. 3. در پنل ری‌اکت یک پادکست تستی با یک فایل `.mp3` کوتاه آپلود و ذخیره کنید. ### گام ۳: تست سلامت فید در ابزارهای Validator رایگان (قبل از ثبت در پلتفرم‌ها) قبل از اینکه سراغ ساخت اکانت در پلتفرم‌ها بروید، لینک `rss.xml` خودتان را در یکی از این دو سایت رایگان تست کنید تا مطمئن شوید ۱۰۰٪ استاندارد است: 1. **Cast Feed Validator:** https://www.castfeedvalidator.com 2. **Podbase Validator:** https://podba.se/validate > [!TIP] > اگر هر دو سایت تیک سبز دادند (کاور ۱۴۰۰×۱۴۰۰، تگ‌های iTunes و پشتیبانی از Byte-Range روی فایل MP3)، فید شما آماده اتصال به تمام پلتفرم‌های دنیاست. ### گام ۴: ثبت رایگان در پلتفرم‌ها با اکانت تستی خودتان #### ۱. تست در **Castbox** (کاملاً رایگان و سریع‌ترین برای تست - حدود ۵ دقیقه) 1. وارد سایت **Castbox Creator Studio** شوید: https://castbox.fm/creator (با جیمیل خودتان ثبت‌نام کنید). 2. از منوی بالا یا داشبورد روی **Claim Ownership / Submit Podcast** کلیک کنید. 3. لینک RSS سایت خودمان (`https://.../api/podcast/rss.xml`) را وارد کنید. 4. کست‌باکس ایمیل داخل تگ `` فید را می‌خواند و یک کد تایید به جیمیل شما می‌فرستد. 5. کد را وارد کنید؛ پادکست بلافاصله در Castbox ساخته می‌شود! #### ۲. تست در **Spotify for Creators (Podcasters)** (کاملاً رایگان - حدود ۵ تا ۱۰ دقیقه) 1. وارد https://creators.spotify.com شوید و با یک اکانت رایگان Spotify لاگین کنید. 2. گزینه **I already have a podcast** را بزنید و لینک RSS سایت خودمان را وارد کنید. 3. اسپاتیفای یک کد ۸ رقمی به ایمیل داخل `` فید می‌فرستد. 4. کد را وارد کنید و Submit را بزنید؛ پادکست شما روی Spotify قرار می‌گیرد. #### ۳. تست در **Mave (`mave.digital`)** (برای تست ایمپورت و فید Mave) 1. وارد https://app.mave.digital شوید و با ایمیل خودتان یک اکانت رایگان بسازید. 2. گزینه **Создать подкаст (Create Podcast)** -> **Импортировать (Import via RSS)** را بزنید. 3. لینک RSS سرور خودمان را بدهید تا ببینید چطور Mave اپیزودهای پنل ما را می‌خواند، یا برعکس لینک RSS تستی Mave را در پنل خودمان ایمپورت کنید. #### ۴. تست در **Apple Podcasts Connect** > [!NOTE] > برخلاف Castbox و Spotify که کاملاً رایگان هستند، ثبت پادکست جدید در https://podcastsconnect.apple.com نیازمند داشتن یک Apple Account با روش پرداخت معتبر (یا اکانت توسعه‌دهنده اپل) است و بررسی اولیه آن توسط تیم اپل ۲۴ تا ۷۲ ساعت طول می‌کشد. بنابراین برای تست فنی خودمان، **Castbox** و **Spotify** بهترین و سریع‌ترین گزینه‌ها هستند و از دقیقاً همان استاندارد XML اپل استفاده می‌کنند. ### گام ۵: تست انتشار خودکار اپیزود دوم 1. حالا که فید را در Castbox یا Spotify ثبت کردید، دیگر وارد سایت آن‌ها نشوید. 2. فقط وارد **پنل ری‌اکت خودمان** شوید و **اپیزود تستی شماره ۲** را آپلود کنید. 3. لینک `/api/podcast/rss.xml` را رفرش کنید تا ببینید اپیزود ۲ به بالای XML اضافه شده است. 4. پس از سینک دوره‌ای پلتفرم، اپیزود ۲ به‌صورت خودکار در Castbox و Spotify ظاهر می‌شود!