Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

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).

Stable

1. 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.
Keamanan Aset Digital

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:

Antarmuka utama Pustaka Media DagangBot dengan metrik kuota penyimpanan dan galeri aset digital multi-modul
Antarmuka utama Pustaka Media terpusat dengan filter modul (Knowledge Base, Branding, Produk) dan kartu metrik kapasitas penyimpanan
Modal pratinjau aset digital resolusi penuh dengan rincian ukuran teroptimasi dan tombol unduh
Dialog modal pratinjau dan inspeksi aset media digital sebelum ditautkan ke katalog atau bot WhatsApp

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. 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. 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. 3

    Langkah 3: Penautan Aset pada Modul Berbeda

    Aset yang berhasil disimpan akan mengembalikan objek MediaAsset dengan 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. 4

    Langkah 4: Publikasi Dokumentasi CMS Platform (Khusus Administrator)

    Akses URL konsol platform di rute frontend /super/docs. Antarmuka publikasi ini dimotori oleh DocsAdminHeader, DocsGroupManager, dan DocsHelpLinksManager. Administrator dapat menambah halaman dokumentasi (DocPageItem), menyusun kategori direktori (DocGroupItem), serta memperbarui tautan bantuan eksternal (DocHelpLinkItem). Publikasi ini tidak mengonsumsi kuota storage_quota_mb tingkat 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/finalize untuk mencatat metadatanya. Fail di bawah 50 MB akan ditolak di rute direct upload dan diarahkan kembali ke standard ingest.
MIME Deny List (Keamanan Lanjutan)

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.

Parameter Teknis Ambang Batas / Tipe Keterangan Verifikasi Sistem
Batas Maksimal File (Unggah Organik) 5 MB (Default Config) Dikontrol parameter manual_payment.max_upload_size_mb atau konfigurasi global. Melampaui limit memicu galat ErrFileTooLarge (HTTP 413).
Moda Direct Upload 50 MB - 500 MB Permintaan presigned URL R2. Jika ukuran kurang dari 50 MB, API merespons dengan ErrDirectUploadTooSmall.
Blacklist MIME Relatif HTML, SVG, JS Modul fileguard menolak jenis text/html, image/svg+xml, application/javascript, dan turunannya (absoluteDenyMIMEs).
Batas Dimensi Thumbnail > 320 px Width Memori alokasi konversi gambar akan bekerja jika dimensi lebar lebih dari 320px.
Format MIME Sah JPEG, PNG, PDF Tervalidasi hingga level biner (magic bytes), tipe lain ditolak dengan pesan ErrInvalidFileType.
Sistem Deduplikasi Aktif secara default Berkas dengan byte array identik tidak akan menambah beban kuota, mengembalikan aset terunggah sebelumnya (S4.2 Deduplication).
Engine Penyimpanan Local / Cloudflare R2 Bergantung parameter LOCAL_STORAGE_DIR. Rute fallback internal API merender http://localhost/uploads bila domain CDN belum dipetakan.
Visibilitas Cabang (Branching) Hierarkis (Soft Delete) Pengguna staf pada satu cabang hanya melihat aset khusus cabangnya (bila branchID terisi), administrator utama (owner) dapat melihat semua.

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 SendMediaMessage akan 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 dan inbound_media_quota_mb untuk 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:

  1. 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 NOTHING dan membagikan ID media_asset eksisten kepada kedua staf, menghemat ruang penyimpanan.
  2. 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).
  3. 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.
Gejala Masalah Penyebab Utama Solusi & Penanganan
Gagal mengunggah foto dengan error 413 (File Too Large). Berkas melebihi parameter maxUploadMB (standar 5 MB). Sesuaikan rasio dan kecilkan ukuran fail sebelum unggah, atau minta admin menaikkan batas konfigurasi limit paket (Plan Quota).
Gambar berekstensi .PNG ditolak dengan error ErrInvalidFileType. Terjadi peretasan terselubung, fail sebetulnya berbasis executable atau script berbalut ekstensi PNG. Sistem MIME sniffing menangkal berkas. Pastikan Anda hanya mengunggah fail murni dari editor gambar (Photoshop/Canva) bukan rename eksistensi executable.
Penyimpanan perubahan aset atau materi panduan tertolak. Token akses sesi kedaluwarsa atau telah direset demi keamanan. Lakukan autentikasi ulang (Log Out dan Log In kembali) di konsol platform.
Thumbnail media tidak tampil di jendela obrolan (Blank URL). Variabel lingkungan penyimpanan (LOCAL_STORAGE_BASE_URL dan API_BASE_URL) belum diset dengan host FQDN produksi. Cek startup log. Bila konfigurasi keliru, fallback URL ke localhost:8080/uploads digunakan dan WhatsApp API gagal membaca tautan localhost.
Fail diunggah oleh kasir, tapi manajer cabang A tidak melihat gambarnya. Isolasi Visibilitas Cabang aktif membatasi hak baca antar-cabang. Jika fail di-tag untuk branchB, hanya staf branchB atau pemegang tingkat owner (reachesAllBranches: true) yang memiliki hak akses (visibility rules).
Unggahan langsung R2 (Direct) gagal saat finalisasi. Endpoint /api/v1/media/finalize dipanggil terlalu lama atau klien terputus sebelum unggah selesai 100%. Ulangi proses permintaan presigned URL dan unggah fail. Catatan tertunda (orphaned) akan dibersihkan otomatis oleh sistem di belakang layar.

7. Referensi Terkait

content/docs/features/media-cms.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot