Perkhidmatan All File Converter direka bentuk sebagai sistem SaaS teragih yang boleh berskala berdasarkan bertindan tak segerak (asynchronous stack) Python 3.12 moden. Seni binanya dibahagikan kepada lapisan bebas: penerimaan peristiwa rangkaian, orkestrasi tugasan, pelaksanaan terpencil bagi proses binari berat, dan litar analitikal.

1. Bertindan Teknologi Am dan Seni Bina Sistem

Platform ini diasaskan atas prinsip daya pemprosesan tinggi (high-throughput), penggunaan memori yang minimum, and perlindungan daripada kegagalan:

  • Telegram Bot Framework: Aiogram 3.13, beroperasi dalam mod Webhook dengan pengesahan token rahsia dan penapis kitaran hayat mesej tersuai.
  • Gerbang Web dan REST API: FastAPI berdasarkan pelayan ASGI Uvicorn dengan penstriman binari tak segerak (FileResponse) dan pembersihan latar belakang melalui BackgroundTasks.
  • Broker Baris Gilir dan Cache: Redis 7 (pengurusan tugasan Celery, penguncian daripada keadaan perlumbaan (race condition), perlindungan daripada serangan brute-force, pengecahan sesi).
  • Pelaku Latar Belakang (Task Queue): Celery 5.4 dengan kumpulan pekerja khusus dalam bekas terpencil converter_worker.
  • Pangkalan Data: PostgreSQL 16 dengan lapisan ORM SQLAlchemy 2.0 (asyncpg), kolam sambungan berterusan (20+10 overflow) dan cuba semula automatik untuk transaksi yang gagal (@db_retry).
  • Litar Rangkaian: Penyelarasan terowong melalui Cloudflare Zero Trust dengan penyekatan akses IP langsung ke pelayan melalui Middleware.

2. Baris Gilir Tak Segerak dan Pengasingan Pengkomputeran Berat (Celery + Redis)

Penukaran fail media dan pakej pejabat menghasilkan beban puncak pada CPU dan RAM. Untuk memastikan proses pemprosesan mesej masuk dalam Telegram tidak disekat semasa operasi berat, pengasingan ketat telah dilaksanakan:

  • Pewakilan Tugasan ke Redis: Apabila memilih format, pengendali Telegram mendaftarkan tugasan dalam pangkalan data dengan status PROCESSING dan meletakkan tugasan dalam baris gilir tasks.execute_conversion melalui Celery.
  • Bekas Pekerja Terpencil: Pelaksanaan utiliti penukaran berlaku di dalam bekas Linux yang berasingan dengan had masa pemproses dan memori sendiri.
  • Kawalan Pembekuan dan Masa Henti (Timeouts): Panggilan kepada utiliti luaran dibungkus dalam konteks tak segerak dengan kawalan masa yang ketat (conversion_timeout_sec = 180). Apabila had melebihi, proses ditamatkan secara paksa melalui proc.kill(), membebaskan sumber.
  • Fallback Tahan Ralat: Jika broker Redis tidak tersedia buat sementara waktu, tugasan tersebut dipintas secara automatik oleh pengdispatch tak segerak tempatan dan dilaksanakan secara langsung tanpa kegagalan kepada pengguna.

3. Paip Enjin Penukaran Khusus

Untuk setiap jenis data, utiliti dan pustaka asli yang khusus digunakan:

  • Dokumen dan Jadual (LibreOffice): Pakej pejabat tanpa kepala (soffice --headless) untuk pemaparan tepat DOCX, XLSX, PPTX, RTF, ODT kepada format PDF atau fail teks.
  • Audio dan Video Penstriman (FFmpeg): Pengekodan semula pelbagai benang untuk kodek video (H.264), kodek audio (MP3, OGG Opus), pengekstrakan trek bunyi, penjanaan GIF (penapis Lanczos) dan pemangkasan segi empat sama (1:1) untuk mesej video Telegram.
  • Pemprosesan PDF Kelajuan Tinggi (Poppler Utils): Utiliti pdftotext (pengekstrakan teks berformat segera dalam UTF-8) dan pdftoppm (pemaparan halaman PDF kepada imej raster tanpa overhed LibreOffice).
  • Pengecaman Aksara Optik (Tesseract OCR): Pengekstrakan teks bercetak berasaskan rangkaian saraf daripada imbasan dan foto dalam 40+ bahasa.
  • Grafik Raster dan Vektor: Pustaka Pillow (termasuk sokongan untuk format HEIC dan AVIF), CairoSVG untuk imej vektor, dan lottie untuk pelekat animasi Telegram (.TGS).
  • Buku, Subtajuk, dan Fon: Enjin Calibre (ebook-convert), pengurai subtajuk pysubs2 (SRT, VTT, ASS, SSA), dan penyusun fon fonttools (pemampatan Brotli dalam WOFF2).

4. Perlindungan Sumber Pencegahan (System Guard)

Untuk melindungi daripada keruntuhan pelayan akibat kekurangan memori (OOM Killer), perkhidmatan diagnostik pencegahan System Guard telah diperkenalkan. Sebelum menerima fail untuk diproses, sistem menyemak metrik hos utama:

  • Memori Akses Rawak Percuma (RAM): Minimum 500 MB volum percuma (guard_min_free_ram_mb).
  • Ruang Cakera: Minimum 2 GB ruang bebas dalam direktori /tmp (guard_min_free_disk_mb).
  • Baris Gilir Tugasan: Pengehadan panjang baris gilir Celery (tidak lebih daripada 20 tugasan yang menunggu).

Apabila had dilampaui, perkhidmatan ini mendayakan perlindungan buat sementara waktu (HTTP 503 / mesej dalam sembang), menghalang beban lampau pelayan dan menghantar amaran segera kepada pentadbir di Telegram.

5. Kitar Hayat Fail dan Keselamatan (GDPR)

Seni bina direka mengikut model Zero-Data-Footprint:

  • Fail pengguna dimuat naik ke volum terlindung tmp/conversions/ dengan awalan unik berdasarkan pengecam tugasan.
  • Fail kekal boleh diakses secara ketat dalam kerangka sesi kerja — tidak lebih daripada 15 minit (900 saat).
  • Pembersih sampah automatik memadamkan fail asal dan fail siap serta-merta selepas pengesahan penghantaran berjaya ke sembang atau selepas tamat tempoh sesi.
  • Pangkalan data PostgreSQL tidak menyimpan fail binari atau teks dokumen peribadi — hanya metadata teknikal yang dianonimkan direkodkan dalam jadual (format, saiz dalam bait, masa operasi, status).

6. REST API Universal untuk Perkhidmatan Web Luaran

Perkhidmatan ini pada awalnya direka sebagai bahagian belakang (backend) berbilang platform. Selain bot, antara muka pengaturcaraan yang dilindungi sepenuhnya berfungsi untuk tapak web (contohnya, pada Django) dan bot pihak ketiga:

  • GET /api/v1/formats — matriks JSON dinamik bagi arah penukaran yang tersedia, disegerakkan dengan tetapan Google Sheets.
  • POST /api/v1/convert — titik akhir universal yang menerima multipart/form-data (fail, format sasaran, ID pelanggan luaran) dan mengembalikan aliran bait siap dalam bentuk muat turun terus.
  • Pengesahan mengikut token Bearer (WEBHOOK_REFRESH_TOKEN) dengan perlindungan terhadap serangan masa melalui secrets.compare_digest.

7. Panel Kawalan dan Pemerhatian (NiceGUI + AG Grid)

Pemantauan penunjuk perniagaan dan keadaan sistem telah dibawa ke panel kawalan Single-Page asli berasaskan NiceGUI 2.x:

  • Jadual interaktif AG Grid (v32+) dengan penapis kotak semak gaya Excel tersuai (aggrid_filters.js).
  • Pemantauan masa nyata untuk baris gilir, kelewatan pembekal API, dan ping PostgreSQL / Redis.
  • Penapisan hujung ke hujung mengikut tarikh dengan integrasi lancar papan pemuka BI Metabase melalui token JWT yang ditandatangani.