سرویس All File Converter به عنوان یک سیستم SaaS توزیع‌شده و مقیاس‌پذیر بر پایه پشته ناهمگام مدرن Python 3.12 طراحی شده است. معماری به لایه‌های مستقل تقسیم می‌شود: دریافت رویدادهای شبکه، ارکستراسیون وظایف، اجرای ایزوله‌شده فرآیندهای باینری سنگین و چرخه تحلیلی.

۱. پشته کلی فناوری و معماری سیستم

پایه و اساس این پلتفرم بر اصول کارایی بالا (high-throughput)، مصرف حداقل حافظه و محافظت در برابر خطاها بنا شده است:

  • فریم‌ورک ربات تلگرام: Aiogram 3.13، در حال کار در حالت Webhook با اعتبارسنجی توکن‌های امنیتی و فیلترهای سفارشی چرخه عمر پیام‌ها.
  • دروازه وب و REST API: FastAPI بر پایه سرور ASGI فریم‌ورک Uvicorn با ارسال جریانی ناهمگام فایل‌های باینری (FileResponse) و پاک‌سازی در پس‌زمینه از طریق BackgroundTasks.
  • کارگزار صف‌ها و کش: Redis 7 (مدیریت وظایف Celery، قفل‌ها برای جلوگیری از وضعیت مسابقه، محافظت در برابر بروت‌فورس، کش کردن نشست‌ها).
  • اجراکننده پس‌زمینه (صف وظایف): Celery 5.4 با استخری تخصصی از کارگران در یک کانتینر ایزوله‌شده converter_worker.
  • پایگاه داده: PostgreSQL 16 با لایه ORM فریم‌ورک SQLAlchemy 2.0 (asyncpg)، استخر اتصالات دائمی (20+10 overflow) و تلاش مجدد خودکار برای تراکنش‌های دارای خطا (@db_retry).
  • حوزه شبکه: تونل‌سازی از طریق Cloudflare Zero Trust با مسدود کردن دسترسی مستقیم IP به سرور از طریق Middleware.

۲. صف‌های ناهمگام و ایزوله‌سازی محاسبات سنگین (Celery + Redis)

تبدیل فایل‌های چندرسانه‌ای و بسته‌های اداری بار پیک زیادی روی CPU و RAM ایجاد می‌کند. برای اینکه روند پردازش پیام‌های ورودی در تلگرام در طول عملیات سنگین مسدود نشود، ایزوله‌سازی سختی پیاده‌سازی شده است:

  • تفویض وظایف به Redis: هنگام انتخاب فرمت، پردازشگر تلگرام وظیفه را با وضعیت PROCESSING در پایگاه داده ثبت می‌کند و کار را از طریق Celery در صف tasks.execute_conversion قرار می‌دهد.
  • کانتینر ایزوله‌شده کارگر: اجرای ابزارهای تبدیل در یک کانتینر لینوکس جداگانه با محدودیت اختصاصی برای زمان پردازنده و حافظه انجام می‌شود.
  • کنترل توقف‌ها و زمان‌های انتظار (Timeout): فراخوانی ابزارهای خارجی در یک کانتینر ناهمگام با کنترل دقیق زمان (conversion_timeout_sec = 180) پیچیده شده است. در صورت تجاوز از حد مجاز، فرآیند به‌زور توسط proc.kill() پایان می‌یابد و منابع آزاد می‌شوند.
  • پشتیبان مقاوم در برابر خطا (Fallback): در صورت عدم دسترسی موقت کارگزار Redis، وظیفه به‌طور خودکار توسط مدیر ناهمگام محلی رهگیری شده و بدون بروز خطا برای کاربر مستقیماً اجرا می‌شود.

۳. پایپ‌لاین موتورهای تخصصی تبدیل

برای هر نوع داده، ابزارها و کتابخانه‌های بومی بسیار تخصصی به کار گرفته می‌شوند:

  • اسناد و جدول‌ها (LibreOffice): بسته اداری بدون رابط گرافیکی (soffice --headless) برای رندر دقیق فایل‌های DOCX، XLSX، PPTX، RTF، ODT به فرمت PDF یا فایل‌های متنی.
  • صدا و تصویر جریانی (FFmpeg): ترکدینگ چندنخی کدهای ویدیویی (H.264)، کدهای صوتی (MP3، OGG Opus)، استخراج باندهای صوتی، تولید GIF (فیلتر Lanczos) و کادربندی مربعی (1:1) پیام‌های ویدیویی تلگرام.
  • پردازش پرسرعت PDF (Poppler Utils): ابزارهای pdftotext (استخراج آنی متن قالب‌بندی شده در UTF-8) و pdftoppm (رندر صفحه‌به‌صفحه PDF به تصاویر رستر بدون سربار LibreOffice).
  • تشخیص نوری متن (Tesseract OCR): استخراج متن چاپی از اسکن‌ها و عکس‌ها با استفاده از شبکه‌های عصبی به بیش از ۴۰ زبان.
  • گرافیک رستر و وکتور: کتابخانه‌های Pillow (شامل پشتیبانی از فرمت‌های HEIC و AVIF)، CairoSVG برای تصاویر وکتور و lottie برای استیکرهای متحرک تلگرام (.TGS).
  • کتاب‌ها، زیرنویس‌ها و فونت‌ها: موتور Calibre (ebook-convert)، تجزیه‌کننده زیرنویس pysubs2 (SRT، VTT، ASS، SSA) و کامپایلر فونت fonttools (فشرده‌سازی Brotli در WOFF2).

۴. محافظت پیشگیرانه از منابع (System Guard)

برای محافظت در برابر از کار افتادن سرور به دلیل کمبود حافظه (OOM Killer)، سرویس تشخیص پیشگیرانه System Guard پیاده‌سازی شده است. پیش از پذیرش فایل برای پردازش، سیستم معیارهای کلیدی میزبان را بررسی می‌کند:

  • حافظه اصلی آزاد (RAM): حداقل ۵۰۰ مگابایت فضای آزاد (guard_min_free_ram_mb).
  • فضای دیسک: حداقل ۲ گیگابایت فضای خالی در دایرکتوری /tmp (guard_min_free_disk_mb).
  • صف وظایف: محدودیت طول صف Celery (حداکثر ۲۰ وظیفه در انتظار).

هنگام تجاوز از حد مجاز، سرویس به‌طور موقت محافظت را فعال می‌کند (HTTP 503 / پیام در چت)، که از بار بیش از حد سرور جلوگیری کرده و هشدار آنی را برای مدیران در تلگرام ارسال می‌کند.

۵. چرخه عمر فایل‌ها و امنیت (GDPR)

معماری بر اساس مدل Zero-Data-Footprint طراحی شده است:

  • فایل‌های کاربران در درایو امن tmp/conversions/ با پیشوندهای منحصر‌به‌فرد بر اساس شناسه‌های وظایف بارگذاری می‌شوند.
  • فایل‌ها دقیقاً در چارچوب نشست کاری قابل دسترسی می‌مانند — حداکثر ۱۵ دقیقه (۹۰۰ ثانیه).
  • زباله‌جمع‌کن خودکار فایل‌های مبدأ و آماده را بلافاصله پس از تأیید ارسال موفق به چت یا پس از پایان زمان نشست پاک می‌کند.
  • پایگاه داده PostgreSQL فایل‌های باینری یا متن‌های شخصی اسناد را ذخیره نمی‌کند — در جدول‌ها فقط فراداده‌های فنی ناشناس (فرمت‌ها، اندازه‌ها به بایت، زمان کار، وضعیت‌ها) ثبت می‌شوند.

۶. رابط REST API جهانی برای سرویس‌های وب خارجی

این سرویس از ابتدا به عنوان یک بک‌اند چندپلتفرمی طراحی شده است. در کنار ربات، یک رابط برنامه‌نویسی امن کامل برای وب‌سایت‌ها (مثلاً روی Django) و ربات‌های شخص ثالث نیز کار می‌کند:

  • GET /api/v1/formats — ماتریس JSON پویا از مسیرهای تبدیل موجود، همگام‌سازی شده با تنظیمات Google Sheets.
  • POST /api/v1/convert — یک اندپوینت جهانی که multipart/form-data (فایل، فرمت مقصد، شناسه مشتری خارجی) را دریافت کرده و جریان آماده بایت‌ها را به صورت دانلود مستقیم ارائه می‌دهد.
  • احراز هویت با توکن‌های Bearer (WEBHOOK_REFRESH_TOKEN) با محافظت در برابر حملات زمانی از طریق secrets.compare_digest.

۷. کنترل‌پنل و Observability (NiceGUI + AG Grid)

پایش شاخص‌های تجاری و وضعیت سیستم به کنترل‌پنل بومی Single-Page بر پایه NiceGUI 2.x منتقل شده است:

  • جداول تعاملی AG Grid (v32+) با فیلترهای چک‌باکس سفارشی به سبک Excel (aggrid_filters.js).
  • پایش صف‌ها، تأخیرهای ارائه‌دهندگان API و پینگ PostgreSQL / Redis در زمان واقعی.
  • فیلترینگ سراسری بر اساس تاریخ با ادغام یکپارچه داشبورد BI Metabase از طریق توکن‌های امضاد شده JWT.