Media Library, Aset Digital & Publikasi CMS
Kualitas aset digital visual sangat menentukan kredibilitas operasional bisnis modern, mulai dari foto katalog produk, spanduk promosi, hingga dokumen referensi di Knowledge Base. Modul Media Library DagangBot mengelola siklus hidup aset ini, menghadirkan repositori media terisolasi per tenant (Multi-Tenant Bucket) dengan sistem konversi otomatis, deduplikasi hash cerdas, dan sinkronisasi CDN berkinerja tinggi. Selain itu, DagangBot juga menyediakan permukaan publikasi konten tingkat platform lewat sistem CMS dokumentasi internal pada panel administrasi (/super/docs).
Stable1. Ikhtisar & Nilai Bisnis
Modul manajemen aset ini dirancang untuk menjawab tantangan batas jaringan WhatsApp dan efisiensi penyimpanan cloud. Mengirim fail berkapasitas masif ke klien via WhatsApp sering berujung pada tingginya angka kegagalan pengiriman dan pengalaman pelanggan yang buruk. Media Library memecahkan dilema tersebut melalui pengolahan pasca-unggah di latar belakang.
- Penyimpanan Terisolasi (Per-Tenant Storage): Setiap berkas yang diunggah dipisahkan ke dalam partisi aman berdasarkan ID Merchant, mencegah akses silang antar-tenant (cross-tenant leakage).
- Deduplikasi Hash Otomatis: Sistem mengekstrak hash dari setiap berkas. Jika dua staf mengunggah fail produk yang sama persis, penyimpanan hanya menyimpannya satu kali (menghemat kuota
storage_quota_mb), sembari tetap menjaga relasi data. - Konversi dan Pembuatan Thumbnail: Aset gambar beresolusi raksasa dikompres dan diduplikasi sebagai thumbnail jika lebarnya melampaui 320px, guna memastikan proses pemuatan gambar responsif dan latensi rendah pada terminal kasir atau layar pembeli.
- Isolasi Kuota Inbound vs Storage: Adanya perhitungan terpisah antara unggahan inisiatif merchant (
storage_quota_mb) dengan berkas media yang diterima melalui percakapan inbound WhatsApp (inbound_media_quota_mb), sehingga lonjakan kiriman dari pelanggan tidak langsung melumpuhkan kapasitas katalog merchant. - Publikasi Dokumen & Aset: Tim pengelola platform memiliki kendali terpusat untuk memublikasikan, merotasi, dan mengatur direktori aset panduan serta materi edukasi secara terstruktur.
Sistem perlindungan mengeliminasi risiko injeksi skrip atau penyusupan biner. Setiap berkas diuji menggunakan pengecekan tipe MIME sniffing (mengidentifikasi bit biner murni) sehingga unggahan dokumen palsu yang diam-diam berisi berkas executable atau script malware akan langsung diintersepsi dan ditolak.
2. Alur Visual & Antarmuka
Berikut adalah tampilan antarmuka saat pengguna berinteraksi langsung dengan Pustaka Media (Media Library), mulai dari pemantauan kuota penyimpanan multi-tenant, penyaringan aset berdasarkan modul bisnis, hingga inspeksi pratinjau berkas teroptimasi:


3. Panduan Langkah-demi-Langkah
Untuk memaksimalkan penggunaan kapasitas media dan publikasi dokumen pada sistem, staf merchant dan platform administrator dapat mengikuti alur baku di bawah:
- 1
Langkah 1: Pengunggahan File Media Organik
Buka halaman media atau formulir entitas yang membutuhkan gambar (misalnya menu penambahan produk atau pengaturan logo toko). Seret dan lepaskan fail Anda (berformat JPEG, PNG, atau PDF). Sistem secara internal memanggil endpoint API (contoh:
/api/v1/agency/branding/logo). Saat fail ditransfer, pembatas unggah sistem (maxUploadBytes) akan memvalidasi besar fail agar tidak melampaui limit konfigurasi standar (default 5 MB). - 2
Langkah 2: Proses Kompresi & Pembuatan Thumbnail Latar Belakang
Setelah fail lolos validasi keamanan (MIME sniffing), modul media_service akan menyusun direktori berbasis ID Merchant. Untuk fail berjenis gambar dengan lebar di atas 320 pixel, DagangBot otomatis memproduksi thumbnail berukuran optimal. Konversi format ke WebP atau kompresi JPEG dilakukan agar latensi transfer CDN tidak memberatkan aplikasi.
- 3
Langkah 3: Penautan Aset pada Modul Berbeda
Aset yang berhasil disimpan akan mengembalikan objek
MediaAssetdengan properti URL terenkripsi yang sudah memiliki proteksi kadaluarsa penandatanganan tautan (signed presigned upload URL untuk R2, atau rute HTTP statis untuk lokal). Gunakan asset ID tersebut di dalam kolom modul terkait (seperti Katalog Produk atau Knowledge Base). Sistem tidak akan menggandakan bytes jika Anda menautkan gambar yang sama. - 4
Langkah 4: Publikasi Dokumentasi CMS Platform (Khusus Administrator)
Akses URL konsol platform di rute frontend
/super/docs. Antarmuka publikasi ini dimotori olehDocsAdminHeader,DocsGroupManager, danDocsHelpLinksManager. Administrator dapat menambah halaman dokumentasi (DocPageItem), menyusun kategori direktori (DocGroupItem), serta memperbarui tautan bantuan eksternal (DocHelpLinkItem). Publikasi ini tidak mengonsumsi kuotastorage_quota_mbtingkat merchant karena berada pada bucket internal infrastruktur platform.
4. Parameter & Spesifikasi Teknis
Klasifikasi Modul Media
Sistem DagangBot membagi setiap aset media ke dalam konteks Modul. Pembagian ini berdampak pada masa simpan retensi dan perilaku pengiriman. Modul yang didukung meliputi:
product: Aset untuk katalog produk, banner toko. Tidak memiliki waktu kedaluwarsa secara default.broadcast: Berkas untuk dikirim via blast WhatsApp. Umumnya gambar kompresi tinggi.cms&kb: Gambar dan berkas untuk basis pengetahuan bot atau CMS halaman admin.branding: Logo merchant, favicon. Disajikan untuk publik via CDN.payment_proof: Bukti transfer pembayaran manual. Terikat ke Rate Limit ketat per tenant.general: Aset umum yang tidak terikat pada modul spesifik.
Mode Unggahan (Standard vs Direct Upload)
Infrastruktur media DagangBot memiliki dua jalur unggahan utama berdasarkan ukuran berkas:
- Standard Ingest (< 50 MB): Fail dikirimkan sebagai multipart/form-data ke backend platform. Backend menampung, memvalidasi tipe berkas via MIME sniffing (menggunakan paket internal
fileguard), memproduksi thumbnail (jika lebar > 320px), lalu meneruskannya ke objek penyimpanan (Cloudflare R2 atau lokal). - Direct Upload (50 MB - 500 MB): Untuk fail video, arsip besar, atau dokumen tebal. Aplikasi klien meminta tanda tangan presigned URL dari rute
/api/v1/media/direct-upload-url. Setelah klien langsung mengirim ke R2, backend memanggil/api/v1/media/finalizeuntuk mencatat metadatanya. Fail di bawah 50 MB akan ditolak di rute direct upload dan diarahkan kembali ke standard ingest.
Selain MIME sniffing biner, sistem menolak fail dengan konten aktif secara absolut: text/html, image/svg+xml, application/javascript. Keputusan ini ditujukan untuk mencegah penyisipan skrip XSS atau injeksi aset statis berbahaya, kendati ekstensi fail disamarkan.
Aturan batas dan batas teknis modul Media Library serta CMS dikendalikan langsung oleh engine penyimpanan di backend, mengacu kepada tier paket langganan merchant.
5. Relasi & Integrasi
Infrastruktur berkas ini mengakar kuat pada hampir seluruh modul DagangBot. Alur data dari Media Service menjalar menuju:
- Modul Gateway WhatsApp: Pesan berformat media dikirim ke pelanggan dengan mengambil rujukan berkas. Metode
SendMediaMessageakan menyisipkan URL signed (atau Data URI base64 kecil) agar diterima oleh Evolution API atau OpenWA. - Modul Billing & Pembayaran Manual: Fitur unggah bukti transfer bergantung pada kapabilitas batas laju (Rate Limit) modul media per tenant per jam (
payment_methods.max_uploads_per_hour, maksimal 5). Gambar bukti pembayaran melewati kompresi intensif untuk menghemat ruang arsip. - Modul Quota Manager: Menyelaraskan sisa ruang per-merchant (
storage_quota_mb) untuk unggahan murni staf daninbound_media_quota_mbuntuk media masuk dari percakapan obrolan pengguna WhatsApp (User 1 vs User 2 Quota Isolation).
6. Pemecahan Masalah (Troubleshooting) & Kasus Tepi
Modul Media CMS juga menangani berbagai kasus tepi akibat perilaku asinkron atau keterbatasan klien:
- Unggahan Duplikat Bersamaan (Race Condition Deduplication): Jika dua staf secara persis bersamaan mengunggah gambar katalog yang sama (memiliki hash SHA256 identik), DagangBot tetap menyimpannya satu kali dengan menggunakan
ON CONFLICT DO NOTHINGdan membagikan IDmedia_asseteksisten kepada kedua staf, menghemat ruang penyimpanan. - Aset Yatim (Orphaned Assets) pada Direct Upload: Ketika klien meminta presigned URL (Direct Upload) tapi terputus koneksinya (gagal mengirim fail ke R2), catatan metadata sementaranya akan dibersihkan oleh cron job penyapu otomatis jika finalize endpoint tidak terpanggil dalam batas waktu konfigurasi (umumnya 2-4 jam).
- Rotasi URL CDN & Kedaluwarsa: Beberapa aset pribadi di-render via URL ber-signature. Jika pelanggan membuka pesan WhatsApp yang telah lewat 7 hari dan signed URL usang, reverse proxy akan menolak akses. Solusinya, pengguna dapat meminta tautan yang disegarkan ke bot.
7. Referensi Terkait
Katalog Commerce
Penggunaan file Media Library untuk banner, katalog promo, dan SKU.
Platform Admin Console
Manajemen CMS docs dan kontrol infrastruktur level aplikasi.
Pencegahan Fraud
Validasi MIME sniffing dan pencegahan payload berbahaya di unggahan media.
Sistem Paket Langganan
Korelasi antara Storage Quota dan batas penerimaan Inbound Media.
