تم تصميم خدمة All File Converter كـنظام SaaS موزع قابل للتوسيع بناءً على تقنية Python 3.12 غير المتزامنة الحديثة. تنقسم الهندسة المعمارية إلى طبقات مستقلة: استقبال الأحداث الشبكية، تنسيق المهام، التنفيذ المعزول للعمليات الثنائية الثقيلة، ودائرة التحليل.

1. التقنيات العامة وهندسة النظام

تعتمد المنصة على مبادئ الأداء العالي (high-throughput)، الحد الأدنى من استهلاك الذاكرة، والحماية من الأعطال:

  • Telegram Bot Framework: Aiogram 3.13، يعمل في وضع Webhook مع التحقق من الرموز السرية والفلاتر المخصصة لدورة حياة الرسائل.
  • بوابة الويب و REST API: FastAPI القائم على خادم ASGI المسمى Uvicorn مع التسليم غير المتزامن لتدفقات الملفات الثنائية (FileResponse) والتنظيف في الخلفية عبر BackgroundTasks.
  • وسيط طوابير الانتظار والتخزين المؤقت: Redis 7 (إدارة مهام Celery، قفل لمنع ظروف التسابق، حماية ضد الهجمات العمياء، التخزين المؤقت للجلسات).
  • منفذ المهام في الخلفية (Task Queue): Celery 5.4 مع مجموعة مخصصة من العمال داخل حاوية معزولة converter_worker.
  • قاعدة البيانات: PostgreSQL 16 مع طبقة ORM المتمثلة في SQLAlchemy 2.0 (asyncpg)، ومجموعة اتصالات مستمرة (20+10 overflow) وإعادة المحاولة التلقائية للمعاملات الفاشلة (@db_retry).
  • الدائرة الشبكية: توجيه النفقي عبر Cloudflare Zero Trust مع حظر الوصول المباشر عبر IP إلى الخادم باستخدام Middleware.

2. طوابير الانتظار غير المتزامنة وعزل الحسابات الثقيلة (Celery + Redis)

يؤدي تحويل ملفات الوسائط والحزم المكتبية إلى توليد أحمال ذروة على وحدة المعالجة المركزية (CPU) والذاكرة العشوائية (RAM). ولضمان عدم توقف عملية معالجة الرسائل الواردة في Telegram أثناء العمليات الثقيلة، تم تطبيق عزل صارم:

  • تفويض المهام إلى Redis: عند اختيار التنسيق، يسجل معالج Telegram المهمة في قاعدة البيانات بحالة PROCESSING ويضع المهمة في طابور tasks.execute_conversion عبر Celery.
  • حاوية عامل معزولة: يتم تنفيذ أدوات التحويل داخل حاوية Linux منفصلة ذات حدود خاصة لوقت المعالجة والذاكرة.
  • التحكم في التوقف المؤقت والمهل الزمنية: استدعاءات الأدوات الخارجية مغلفة في سياق غير متزامن مع تحكم صارم في الوقت (conversion_timeout_sec = 180). عند تجاوز الحد، يتم إنهاء العملية قسراً عبر proc.kill() لتحرير الموارد.
  • آلية بديلة مقاومة للأعطال (Fallback): في حال عدم توفر وسيط Redis مؤقتاً، يتم اعتراض المهمة تلقائياً بواسطة المُرسِل المحلي غير المتزامن وتنفيذها مباشرة دون حدوث أي خطأ للمستخدم.

3. خطوط أنابيب محركات التحويل المتخصصة

لكل نوع بيانات، يتم استخدام أدوات ومكتبات أصلية متخصصة للغاية:

  • المستندات والجداول (LibreOffice): حزمة مكتبية بدون واجهة رسومية (soffice --headless) للتقديم الدقيق لملفات DOCX، XLSX، PPTX، RTF، ODT إلى تنسيق PDF أو ملفات نصية.
  • الصوت والفيديو المتدفق (FFmpeg): إعادة ترميز متعددة الخيوط لترميزات الفيديو (H.264)، ترميزات الصوت (MP3، OGG Opus)، استخراج المسارات الصوتية، توليد صور GIF (فلتر Lanczos) والقص المربع (1:1) لرسائل الفيديو في Telegram.
  • معالجة PDF عالية السرعة (Poppler Utils): أدوات pdftotext (استخراج فوري للنصوص المنسقة بتنسيق UTF-8) و pdftoppm (تقديم صفحات PDF إلى صور نقطية دون النفقات العامة لـ LibreOffice).
  • التعرف البصري على الحروف (Tesseract OCR): استخراج النصوص المطبوعة بالشبكات العصبية من عمليات المسح الضوئي والصور بأكثر من 40 لغة.
  • الرسومات النقطية والمتجهية: مكتبات Pillow (بما في ذلك دعم تنسيقات HEIC و AVIF)، و CairoSVG للرسومات المتجهية، و lottie للملصقات المتحركة في Telegram (.TGS).
  • الكتب، الترجمات والخطوط: محرك Calibre (ebook-convert)، محلل الترجمات pysubs2 (SRT، VTT، ASS، SSA) ومُصمّم الخطوط fonttools (ضغط Brotli إلى WOFF2).

4. الحماية الاستباقية للموارد (System Guard)

لحماية الخادم من الانهيار بسبب نقص الذاكرة (OOM Killer)، تم دمج خدمة التشخيص الاستباقي System Guard. قبل قبول الملف للمعالجة، يتحقق النظام من المقاييس الرئيسية للمضيف:

  • الذاكرة العشوائية الحرة (RAM): بحد أدنى 500 ميغابايت من المساحة الحرة (guard_min_free_ram_mb).
  • مساحة القرص: بحد أدنى 2 جيجابايت من المساحة الحرة في المجلد /tmp (guard_min_free_disk_mb).
  • طابور المهام: تقييد طول طابور Celery (ما لا يزيد عن 20 مهمة قيد الانتظار).

عند تجاوز الحدود، تقوم الخدمة بتفعيل الحماية مؤقتاً (HTTP 503 / رسالة في الدردشة)، مما يمنع التحميل الزائد على الخادم وإرسال تنبيه فوري للمسؤولين في Telegram.

5. دورة حياة الملفات والأمان (GDPR)

تم تصميم الهندسة المعمارية وفقاً لنموذج Zero-Data-Footprint:

  • يتم تحميل ملفات المستخدمين في وحدة تخزين آمنة tmp/conversions/ مع بادئات فريدة تعتمد على معرفات المهام.
  • تبقى الملفات متاحة حصرياً في إطار جلسة العمل — بحد أقصى 15 دقيقة (900 ثانية).
  • يقوم جامع النفايات التلقائي بمسح الملفات الأصلية والجاهزة فور تأكيد الإرسال الناجح إلى الدردشة أو عند انتهاء مهلة الجلسة.
  • لا تخزن قاعدة بيانات PostgreSQL الملفات الثنائية أو النصوص الشخصية للمستندات — يتم فقط تسجيل البيانات الوصفية التقنية مجهولة المصدر في الجداول (التنسيقات، الأحجام بالبايت، وقت التشغيل، الحالات).

6. واجهة REST API شاملة لخدمات الويب الخارجية

تم تصميم الخدمة في الأصل كواجهة خلفية متعددة المنصات. إلى جانب البوت، تعمل واجهة برمجة تطبيقات محمية بالكامل لمواقع الويب (مثل Django) والبوتات الخارجية:

  • GET /api/v1/formats — مصفوفة JSON ديناميكية لاتجاهات التحويل المتاحة، متزامنة مع إعدادات جداول Google.
  • POST /api/v1/convert — نقطة نهاية شاملة تقبل multipart/form-data (الملف، التنسيق المستهدف، معرف العميل الخارجي) وتُرجع دفقاً جاهزاً من البايتات على شكل تنزيل مباشر.
  • المصادقة عبر رموز Bearer (WEBHOOK_REFRESH_TOKEN) مع الحماية ضد هجمات التوقيت عبر secrets.compare_digest.

7. لوحة التحكم والمراقبة (NiceGUI + AG Grid)

تم نقل مراقبة مؤشرات الأعمال وحالة النظام إلى لوحة تحكم أصلية من نوع Single-Page تعتمد على NiceGUI 2.x:

  • جداول تفاعلية AG Grid (v32+) مع فلاتر خانات اختيار مخصصة على نمط Excel (aggrid_filters.js).
  • مراقبة طوابير الانتظار، تأخيرات موفري واجهة برمجة التطبيقات، و ping الخاص بـ PostgreSQL / Redis في الوقت الفعلي.
  • تصفية شاملة حسب التواريخ مع تكامل سلس لوحة معلومات BI الخاصة بـ Metabase عبر رموز JWT الموقعة.