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

ASPRI AI

Sistem ASPRI (Asisten Pribadi AI) memungkinkan pemilik bisnis dan jajaran manajemen tingkat atas untuk memantau indikator kinerja utama (KPI) secara langsung melalui antarmuka WhatsApp. Berbeda dengan dasbor web konvensional, ASPRI secara proaktif memberikan ringkasan intelijen bisnis dua kali sehari dan merespons pertanyaan analitik menggunakan pemrosesan bahasa alami, sehingga pengambilan keputusan dapat dilakukan secara seketika (real-time) dari perangkat seluler tanpa proses otentikasi aplikasi berlapis.

Stable

1. Ikhtisar & Nilai Bisnis

ASPRI mengubah paradigma akses data bisnis dari sistem tarik (pull) melalui dasbor menjadi sistem dorong (push) interaktif yang tertanam di platform pesan harian. Sistem ini dirancang dengan isolasi data yang ketat untuk memastikan bahwa data finansial hanya dapat diakses oleh pihak yang memiliki otoritas penuh.

  • Laporan Proaktif Harian: Pengiriman matriks kunci pada pagi hari dan ringkasan tutup buku pada malam hari, secara otomatis dipicu oleh sistem worker (cron).
  • Pembatasan Data Granular per Nomor: Setiap entri whitelist memiliki tingkat akses (full, summary, atau per_branch). Tingkat per_branch membatasi visibilitas metrik hanya pada transaksi dari ID cabang yang secara eksplisit diizinkan (allowed_branches).
  • Verifikasi Ganda Terlindungi: Menggabungkan validasi Caller-ID (nomor pengirim WhatsApp) dan sesi PIN dinamis berdurasi terbatas untuk mencegah penyadapan data bisnis melalui akses perangkat fisik secara tidak sah.
  • Isolasi Konfigurasi Multi-Tenant: Aturan, jadwal (waktu tayang), dan jenis metrik (metrics_ids) ditautkan secara langsung pada relasi tenant (ID Merchant), memastikan batas data absolut antar entitas.
Arsitektur Keamanan Zero-Trust

ASPRI secara default menolak semua interaksi dari nomor yang tidak terdaftar. Permintaan akan dieksekusi hanya apabila lapisan aspri_whitelist memvalidasi nomor telepon pelanggan pada entitas merchant yang aktif, dengan pengecekan PIN aktif yang diverifikasi dalam basis data (hash PIN).

2. Alur Visual & Antarmuka

Laporan harian dan pengaturan jadwal dirancang sesederhana mungkin bagi pengguna tingkat akhir, sekaligus memuat matriks yang sangat kustom pada backend administrasi.

Tampilan WhatsApp berisi laporan briefing pagi ASPRI dengan omzet kemarin dan target hari ini
Contoh Briefing Pagi ASPRI yang memuat rekap penjualan H-1 dan agenda operasional berjalan.
Tampilan laporan malam hari ASPRI yang merinci ringkasan omzet harian dan sisa stok
Laporan Malam hari berisi konsolidasi total transaksi dan peringatan stok minimum.
Dasbor panel pengaturan ASPRI, menampilkan formulir jam jadwal briefing dan daftar metrik aktif
Panel konfigurasi ASPRI untuk mengaktifkan jadwal pelaporan dan manajemen metrik global.

3. Panduan Langkah-demi-Langkah

Proses implementasi dan konfigurasi sistem ASPRI dilakukan melalui panel administrasi utama. Konfigurasi terdiri atas aktivasi fitur, penetapan jadwal pelaporan global, dan penambahan nomor kontak whitelist.

  1. 1

    Langkah 1: Aktivasi Layanan ASPRI dan Jadwal Global

    Akses modul ASPRI pada konsol pengelola. Buka bagian Konfigurasi Briefing. Aktifkan toggle is_active untuk memulai layanan penjadwalan. Tentukan waktu Briefing Pagi (morning_time) dan Laporan Malam (night_time). Standar waktu server adalah 08:00:00 dan 21:00:00 zona waktu lokal. Konfigurasi ini disimpan pada entitas konfigurasi briefing ASPRI dan menjadi standar acuan untuk seluruh penerima kecuali disetel secara kustom.

  2. 2

    Langkah 2: Pendaftaran Nomor Whitelist

    Masuk ke tab Whitelist Nomor. Klik Tambah Eksekutif untuk meregistrasi entitas baru. Masukkan nomor telepon (wajib menggunakan kode negara, misalnya 62812...). Anda tidak dapat meregistrasi nomor Instance WhatsApp (nomor bot itu sendiri) karena pesan dari nomor tersebut diklasifikasikan sebagai pesan keluar, bukan pesan masuk, sehingga akan menimbulkan rekursi tanpa ujung. Sistem secara ketat memberlakukan validasi asimetris untuk hal ini.

  3. 3

    Langkah 3: Penentuan Tingkat Akses dan Hierarki Cabang

    Pilih tingkat otorisasi. Opsi full mengizinkan akses ke nilai moneter dan laporan komprehensif seluruh cabang. Opsi summary menyembunyikan metrik sensitif tertentu, sementara opsi per_branch mengharuskan Anda memilih satu atau lebih ID Cabang spesifik. ASPRI akan menerapkan klausa SQL terisolasi sehingga perhitungan laporan agregat akan terpotong secara absolut hanya pada data cabang yang dialokasikan.

  4. 4

    Langkah 4: Aktivasi Keamanan Lapisan Tambahan (PIN)

    Aktifkan opsi Gunakan PIN (pin_enabled) dan masukkan 4 hingga 6 digit kombinasi numerik. Sistem backend (kode Go) akan memproses hashing PIN tersebut dan menyimpannya secara kriptografis (pin_hash). Penerima harus memasukkan PIN ini pada permulaan interaksi obrolan.

  5. 5

    Langkah 5: Penerapan Metrik Spesifik dan Jadwal Kustom

    Bila nomor bersangkutan adalah level manajer divisi yang tidak membutuhkan notifikasi ganda, hidupkan opsi custom_schedule_enabled. Masukkan array jam (misal: ["07:30", "15:00"]). Alokasikan juga metrik khusus melalui antarmuka, di mana setiap penambahan akan memicu pencatatan relasional ke entitas aspri_whitelist_metrics.

  6. 6

    Langkah 6: Uji Coba Simulasi Briefing

    Lakukan pengujian akhir dengan memanfaatkan API sinkron /api/v1/aspri/briefing/test melalui penekanan tombol Kirim Briefing Uji. Sistem akan melakukan simulasi cron job (menarik data metrik dan menggunakan LLM untuk generate teks bahasa alami) dan mem-bypass batasan jam, guna memastikan respons terkirim secara berhasil ke perangkat whitelist.

4. Parameter & Spesifikasi Teknis

4.1 Parameter Konfigurasi API Dasar (Whitelist & Briefing)

Parameter JSON berikut wajib disertakan saat memanggil metode POST atau PUT pada ujung titik (endpoint) manajemen ASPRI:

Parameter Teks Tipe Data Ambang Batas / Default Deskripsi Fungsional Backend
phone String Format E.164 (tanpa +) Validasi ketat (unik per merchant). Tidak boleh sama dengan nomor instance operasional.
access_level Enum full, summary, per_branch Kunci klausa perizinan. Membatasi kedalaman data BI.
allowed_branches JSON Array [] jika full Kumpulan UUID referensi entitas cabang. Wajib jika level per_branch.
custom_schedule_enabled Boolean false Memutus kaitan fallback pewarisan dari konfigurasi briefing utama.
schedule_times JSON Array Maks. 4 jadwal Array of String dengan format waktu militer HH:MM.
metrics JSON Array Dinamis per akun Kumpulan metrik yang didukung, contoh: ["omzet", "orders", "cs_performance"].
pin_enabled Boolean false Menghidupkan gatekeeper dialog pada saat inisialisasi intent WhatsApp.
pin String 4-6 digit karakter numerik Hanya dikirim pada rute mutasi. Akan dikonversi ke hash saat persistensi data.

4.2 Mesin Penjadwalan & Infrastruktur Metric Resolusi

Proses penarikan laporan mengandalkan kombinasi Cron Scheduler dan antrean pekerja latar belakang. Terdapat sebuah proses latar yang memeriksa waktu secara terus-menerus. Jika waktu lokal (dikonversi dari zona waktu UTC berdasarkan konfigurasi jadwal operational_schedule) telah melewati atau sama dengan titik eksekusi (schedule_times atau morning_time/night_time), tugas akan ditempatkan di dalam antrean.

Untuk proses resolusi, jika pengguna tidak mendefinisikan metrik kustom, sistem menggunakan mekanisme penyusutan ke tingkat dasar (fallback). Modul logika ResolveMetricsForVIP akan memanggil metrik bawaan toko yang tersimpan pada konfigurasi. Pemisahan arsitektur ini memastikan tidak ada bentrok antar-divisi yang memantau entitas pelaporan yang berbeda, karena katalog definisi metrik sistem diorganisir dengan urutan tampilan yang deterministik.

Kapasitas maksimum metrik kustom diatur secara administratif di platform, dengan batasan standar sebanyak 20 definisi metrik tambahan untuk mencegah pelampauan batas konteks komputasi. Ambang batas ini disimpan pada konfigurasi platform.

4.3 Struktur Payload API Lanjutan (Mutasi Whitelist)

Untuk para integrator teknis yang ingin melakukan manajemen whitelist ASPRI secara terprogram tanpa melalui antarmuka pengguna web, kami menyediakan API sinkron dengan mekanisme perlindungan ganda (JWT).

Berikut adalah struktur skema permintaan lengkap yang diizinkan untuk rute Endpoint POST /api/v1/aspri/whitelist:

json
{
  "phone": "6281299990000",
  "name": "Direktur Utama",
  "access_level": "full",
  "allowed_branches": [],
  "pin_enabled": true,
  "pin": "123456",
  "custom_schedule_enabled": true,
  "schedule_times": [
    "06:30",
    "20:00"
  ]
}

Endpoint ini memvalidasi parameter hanya apabila permintaan diterbitkan oleh token yang membawa klaim otorisasi RBAC aspri dengan hak create atau update. Kegagalan validasi payload, seperti format nomor telepon yang tidak sesuai dengan E.164, akan mengembalikan kode kesalahan HTTP 400 Bad Request.

4.4 Infrastruktur Keamanan Verifikasi Nomor (Caller-ID)

Mekanisme penjaga lapis pertama ASPRI bersifat asimetris dan statis:

  1. Pemindaian Sesi (Session Lookup): Saat pesan baru masuk melalui kanal Webhook WhatsApp, konektor routing akan mengevaluasi setiap pesan sebelum mendistribusikannya ke bot pelanggan biasa. Apabila nomor tersebut tercatat dalam aspri_whitelist, rute penerimaan akan dibelokkan dari modul dukungan pelanggan standar ke modul kecerdasan analitik eksekutif.
  2. Anti-Rekursi Loop Terbatas: Terdapat proteksi tingkat layanan pada backend (service.ErrASPRISelfNumber) yang mencegah nomor koneksi Gateway mandiri diregistrasikan. Hal ini dirancang untuk mencegah skenario komunikasi berputar tanpa akhir (infinite loop response).
  3. Manajemen Otentikasi Terenkripsi: Hash nilai rahasia disimpan dalam rupa pin_hash dan dihitung menggunakan operasi serupa Bcrypt. Sekalipun pangkalan data ditransmisikan, rahasia PIN tetap terjaga secara kriptografis satu-arah, sehingga administrator merchant pun tidak dapat membacanya melainkan hanya bisa meresetnya.

5. Relasi & Integrasi

Sistem ASPRI tidak berjalan secara terisolasi. Infrastruktur ini merupakan irisan rumit dari berbagai mesin fungsional yang berjalan di latar belakang:

  1. Mesin RAG (Retrieval-Augmented Generation) Terpadu: Ketika eksekutif mengetik pertanyaan, modul Intent mendelegasikan kueri tersebut ke PromptService dan VectorSearch. Data intelijen dipadukan langsung dengan hasil basis pengetahuan (Knowledge Base) menggunakan dokumen yang memiliki penanda 'all' atau 'aspri'. Ini membuat bot fasih mengenai pedoman internal tanpa campur tangan kode sama sekali.
  2. Konektor Redmine: Jika instansi menggunakan Redmine, ASPRI mampu mendeteksi intent status pekerjaan (Sprint/Bug) melalui Plugin Integration Service, membungkus payload otentikasi proyek, serta melaporkan tiket kedaluwarsa secara langsung di sela-sela ringkasan Order toko.
  3. Pusat Notifikasi Token & Saldo Realtime: Setiap hasil tanggapan generative yang sukses akan memicu pengurangan saldo token (Metric Service WSHub). Pembaruan saldo dan batas penggunaan ini dikembalikan ke klien web administrator secara realtime menggunakan WebSockets tanpa perlunya pemuatan ulang halaman antarmuka.

6. Pemecahan Masalah (Troubleshooting)

Tabel berikut merangkum masalah-masalah teknis yang sering kali timbul dalam alur operasional ASPRI, disertai akar permasalahan fungsional dan solusi definitifnya.

Gejala Terlihat Penyebab Akar (Root Cause) Solusi & Tindakan
Pesan tidak pernah direspons oleh ASPRI Nomor telepon didaftarkan dengan format angka 0 di depan (mis. 0812...) alih-alih format 62812.... Ubah pendaftaran profil whitelist sesuai format E.164. Backend melakukan perbandingan strict string.
Error "Phone number is already registered" Pengguna telah terdaftar di merchant ini atau nomor tersebut bertepatan dengan nomor Instance WA bot itu sendiri. Sistem melarang rekursi (ErrASPRISelfNumber). Gunakan nomor perangkat seluler fisik yang terpisah dari mesin Gateway.
Briefing tidak terkirim pada jam yang disetel Konfigurasi zona waktu pada tabel operational_schedule tidak selaras, atau worker Asynq tertahan tugas lain. Verifikasi zona waktu pada panel. Jika queue sedang penuh, eksekusi akan tertunda namun akan diselesaikan ketika baris pekerja terbebas.
Sebagian data cabang tidak tampak pada laporan access_level berada pada mode per_branch namun allowed_branches melupakan ID dari cabang bersangkutan. Edit entri whitelist, pilih secara eksplisit setiap Cabang yang berhak disurvei oleh nomor penerima.
Sistem ASPRI mengulang kembali permintaan PIN Periode cache dari sesi PIN in-memory telah melampaui masa kedaluwarsa (kadaluwarsa idle standar). Sesi bersifat ephemeral. Pengguna hanya perlu memasukkan kembali 4-6 digit numerik yang tepat untuk menginisialisasi sesi baru.
Balasan terputus, atau respons melantur acak Pengguna menanyakan parameter bisnis eksternal yang melebihi batas 20 metrics, atau konteks LLM dipenuhi noise dokumen. Persempit konteks menggunakan pertanyaan yang jelas. Konfigurasi ulang Custom Metrics dan kurangi indikator tidak relevan dari panel dasbor.
Peringatan: "Sesi Anda sudah kedaluwarsa, silakan masukkan PIN kembali" Waktu idle obrolan interaktif melebihi durasi yang diizinkan sistem sehingga sistem secara defensif mengunci sesi. Kirimkan PIN unik Anda dalam satu gelembung obrolan tanpa atribut karakter tambahan. Setelah terverifikasi, lanjutkan mengirim kalimat pertanyaan.
Data cabang tidak konsisten, pelaporan tetap mencakup cabang pusat Anda menetapkan opsi level per_branch tanpa menghilangkan metrik finansial tingkat agregat tinggi di konfigurasi kustom, atau cache Redis belum tersinkronisasi. Evaluasi panel Whitelist Metrics, pastikan Anda hanya memilih metrik spesifik yang mendukung partisi cabang.
Metrik baru tidak muncul di dalam dokumen ringkasan pagi/malam Indikator yang dimaksud memiliki status dinonaktifkan (is_active = FALSE) pada katalog metrik platform. Lakukan refresh konfigurasi dari antarmuka Administrator, dan picu Simulasi Briefing guna memverifikasi perubahan tersebut.

7. Referensi Terkait

Untuk pemahaman API lanjutan dan pengelolaan integrasi pengiriman yang mendasari sistem ASPRI, Anda dapat mengeksplorasi referensi spesifik berikut:

content/docs/features/aspri.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot