Panduan Lengkap Dataplatform

Versi dokumentasi: 19 Oktober 2026 · Bahasa Indonesia · Untuk semua role.

Panduan ini menjelaskan aplikasi yang sudah tersedia: cara masuk, mengolah data, membaca hasil, membuat audience, menjalankan campaign, mengumpulkan jawaban, dan mengelola instalasi. Nama tombol mengikuti UI berbahasa Inggris agar mudah dicari. Semua identitas pada screenshot adalah data demo sintetis, bukan data pelanggan. Angka pada gambar merupakan contoh, bukan patokan hasil instalasi Anda.

Untuk membaca seluruh buku di browser, buka index.html. Klik gambar untuk melihat ukuran asli. Markdown di folder ini menjadi sumber penyuntingan.

Untuk dicetak atau dibagikan, gunakan PDF modul A4. PDF memiliki cover, daftar isi yang bisa diklik, nomor halaman, header/footer, caption gambar, dan panel berurutan untuk screenshot panjang. Cetak A4 portrait dengan skala 100% / Actual size.

Jika tautan file dari chat/editor membuka source HTML, gunakan browser melalui alamat dokumentasi lokal. Alamat tersebut memerlukan server dokumentasi aktif; cara menjalankannya ada di bab 12.

Daftar isi dan urutan belajar

Cara menggunakan panduan

1. Pengguna baru membaca bab 01 dan SOP role di bab 02.
2. Pelajari bab sesuai pekerjaan; setiap bab menyebut prasyarat, langkah, dan hasil.
3. Bila angka berbeda, periksa filter, waktu, Trash, dedup, dan jenis hasil yang dihitung.
4. Jika tombol tidak muncul, bandingkan hak akses role sebelum meminta perubahan akun.
5. Jika terjadi masalah, catat halaman, waktu, ID proses, dan pesan error; ikuti bab 11.

Acuan dan kejujuran status

Arah produk mengikuti PRD dan aturan sistem. Untuk perilaku yang sudah terpasang, panduan ditulis dari route, permission, controller, action, komponen UI, dan pengamatan browser. Perbedaan implementasi dengan target dicatat di cakupan.

Dokumentasi ini ikut versi repository. Setiap perubahan alur, hasil, akses, atau UI wajib memperbarui bab dan gambar terkait sebelum pekerjaan dinyatakan selesai; mekanismenya ada di bab 12. Pemutakhiran isi tetap membutuhkan review perubahan aplikasi; tidak ada layanan yang diam-diam menulis ulang buku ini.

01 · Mulai di sini

Apa yang dihasilkan Dataplatform

Satu instalasi dipakai satu client/workspace. Platform mengubah data sumber menjadi profil customer yang dapat dicari, kualitas data yang dapat ditinjau, segment dinamis, audience campaign, serta respons form/survei yang memperkaya profil.

Alur utama:

CSV / Google Sheet / URL CSV          Form atau survei publik
             ↓                                ↓
Staging → mapping → commit          Validasi dan jawaban tersimpan
             └──────────────┬───────────────────┘
                    Normalisasi identitas
                            ↓
                 Customer + Review Queue
                            ↓
                  Segment → Campaign
                            ↓
                 Hasil / event → Analytics

Staging berarti data belum menjadi customer. Commit memulai penerapan data. Review berarti diperlukan keputusan manusia. Jumlah baris sumber, jumlah profil, jumlah review, jumlah eligible, dan pesan terkirim memiliki arti berbeda.

Fitur yang tersedia dan batasnya

Masuk dan keluar

Prasyarat: URL instalasi dan akun aktif dari Admin/Super Admin. Tidak ada registrasi mandiri publik. Akun pertama dibuat operator; akun berikutnya melalui Users & roles.

1. Buka URL instalasi; aplikasi mengarah ke login bila belum memiliki sesi.
2. Isi Email address dan Password, lalu Log in.
3. Jika 2FA diaktifkan, masukkan kode authenticator atau recovery code yang sah.
4. Setelah berhasil, dashboard muncul dengan navigasi sesuai permission akun.
5. Akhiri sesi melalui menu akun → Log out, terutama pada perangkat bersama.

Remember me mempertahankan autentikasi lebih lama; gunakan pada perangkat pribadi. Akun inactive tidak dapat masuk. Menu yang hilang dapat merupakan batas hak akses.

Lupa password

1. Di login, pilih Forgot your password?.
2. Masukkan email akun dan kirim permintaan reset.
3. Buka email reset, ikuti tautan, lalu buat password baru.
4. Kembali login menggunakan password baru.

Hasil: password diperbarui setelah tautan/token diterima dan formulir valid. Pesan bahwa permintaan terkirim bukan bukti email sampai ke inbox. Jika tidak diterima, periksa spam dan minta Admin memeriksa SMTP. Jangan kirim password atau tautan reset ke log proyek/support publik.

Profil dan keamanan akun

Buka menu akun → Settings → Profile untuk mengubah nama/email dan simpan. Jika email baru memerlukan verifikasi, gunakan tautan verifikasi sebelum melanjutkan fitur yang mengharuskan akun verified.

Security dapat meminta konfirmasi password saat dibuka. Untuk ganti password, isi password saat ini, password baru, dan konfirmasi, lalu simpan. Pada produksi, aturan password lebih ketat; ikuti validasi layar.

Untuk 2FA: aktifkan, daftarkan QR di authenticator, konfirmasi kode, lalu simpan recovery codes di tempat privat. Screenshot manual tidak memuat QR, secret, atau recovery code. Untuk passkey: pilih pembuatan passkey, beri nama, lalu selesaikan dialog keamanan browser/perangkat. Passkey bergantung HTTPS/localhost dan dukungan perangkat.

Latihan pertama per role

Lanjutkan ke role dan SOP. Untuk belajar tanpa data bisnis, gunakan lingkungan demo pada bab pemeliharaan.

02 · Role, hak akses, dan SOP

Role bersifat tetap. Sumber implementasi: Role.php. Tidak ada UI untuk membuat role baru. Semua aksi tetap diperiksa server.

Matriks akses operasional

Keterangan: Kelola mencakup aksi pada baris tersebut; Baca hanya melihat; — tidak mendapat permission bawaan. Permission yang terdaftar belum tentu memiliki UI; gunakan daftar fitur di bab 01 untuk mengetahui fitur yang tersedia.

VIP memiliki info customer lengkap sesuai implementasi, sehingga akses baca tetap berarti akses ke data pribadi. Pemberian permission export langsung kepada VIP didukung model permission; form user saat ini memilih role dan tidak menyediakan toggle khusus VIP export. Minta pengelola melakukan provisioning terkontrol bila memang diperlukan; jangan menganggap semua VIP sudah punya export.

Super Admin: pemilik instalasi

Tanggung jawab: kesiapan workspace, akun privileged, kebijakan, backup, dan update.

1. Periksa General: timezone, nama workspace, status sistem, backup terakhir.
2. Periksa Users: hanya beri role yang sesuai; pastikan ada Super Admin aktif.
3. Pastikan SMTP dan channel yang dipakai teruji, tanpa membagikan secret.
4. Tinjau Review Queue/import gagal bersama Data Analyst.
5. Periksa audit setelah perubahan akun/kebijakan/reset/update.
6. Sebelum operasi besar, pastikan backup dan rencana pemulihan operator tersedia.

Hasil kerja: instalasi siap dipakai, keputusan kebijakan terdokumentasi, akun terkendali, backup tercatat, hambatan operasional ditindaklanjuti.

Admin: pengelola operasional dan integrasi

1. Periksa Data Sources dan status import/sync.
2. Tangani akun pengguna operasional melalui Users & roles.
3. Tinjau koneksi WhatsApp/SMTP/AI, ubah dan test sesuai kebutuhan.
4. Bantu review data, pengelolaan segment, campaign, dan Experience.
5. Gunakan Audit logs untuk menelusuri aksi; eskalasikan perubahan General, backup manual, reset workspace, dan install versi ke Super Admin.

Hasil kerja: sumber dan koneksi siap, akun operasional sesuai peran, pekerjaan data dan campaign dapat diteruskan. Admin tidak dapat mengelola akun Super Admin atau menyimpan setting yang memerlukan settings.manage.

SPV: pengawas aktivasi

1. Baca dashboard dan kualitas/ketersediaan kontak customer.
2. Buat atau periksa segment, buka sampel, bandingkan dengan tujuan campaign.
3. Buat campaign draft; periksa eligible, message/template, jadwal, dan simulasi.
4. Launch sesuai otorisasi bisnis, lalu pantau status; pause bila perlu.
5. Baca Analytics dan respons Experience untuk menentukan tindakan berikutnya.
6. Bila customer perlu disembunyikan sementara, pindahkan ke Trash; restore bila keputusan dibatalkan. Eskalasi hapus permanen ke Admin/Super Admin.

Hasil kerja: audience dan campaign dapat dipertanggungjawabkan, tindak lanjut hasil jelas. Masalah source/review/akun/integrasi diteruskan kepada role terkait.

Data Analyst: penjaga kualitas data

1. Periksa sumber dan pemilik tiap kolom identitas sebelum import.
2. Stage → cek samples/uniqueness → mapping → commit satu batch yang benar.
3. Rekonsiliasi counters, total customer, invalid, serta review; jangan menyamakan baris dengan profil atau menjumlah review sebagai customer baru.
4. Selesaikan konflik/identitas berdasarkan bukti sumber.
5. Buat segment untuk kebutuhan analisis dan periksa preview.
6. Gunakan export sesuai filter untuk analisis; bila perlu kelola campaign/Experience.
7. Ajukan penghapusan customer kepada SPV/Admin; role ini tidak bisa Trash/restore/ permanent delete dan tidak memiliki system settings.

Hasil kerja: mapping benar, profil lebih tepercaya, review menurun dengan bukti, segment dan catatan kualitas siap dipakai SPV.

VIP: pembaca dan penilai hasil

1. Baca KPI dan periode di dashboard/Analytics.
2. Telusuri customer, segment, campaign, dan respons Experience yang relevan.
3. Catat temuan beserta filter/periode; berikan rekomendasi kepada pengelola.
4. Export hanya bila permission langsung sudah diberikan dan tombol tersedia.

Hasil kerja: evaluasi dan rekomendasi; tidak melakukan perubahan bisnis. URL halaman terlarang tetap mengembalikan 403 walaupun diketik langsung.

Responden publik dan serah-terima

Responden form bukan role login. Ia membuka /f/{slug} yang dipublikasikan, mengisi jawaban, dan menerima ucapan terima kasih. Ia tidak mendapat dashboard/customer.

Untuk handoff, sertakan tujuan → halaman/ID → status → hasil → tindakan berikutnya → penanggung jawab. Contoh sintetis: “Import demo committed, created 1, invalid 0; mapping sudah diperiksa; Data Analyst memeriksa profil, SPV menilai segment.” Jangan memuat password, token, atau salinan data customer ke tiket/log publik.

03 · Dashboard dan Analytics

Dashboard: membaca kondisi saat ini

Akses: semua role. Halaman: /dashboard. Tujuannya melihat data, kualitas, segment, dan aktivasi sebelum memilih pekerjaan berikutnya.

1. Lihat KPI jumlah customer, segment, campaign aktif, pesan, completeness, dan review.
2. Gunakan pencarian header untuk menuju customer yang dicari.
3. Periksa Customer growth & enrichment untuk pola bertambahnya profil.
4. Buka segment/review/import dari tautan kartu untuk memeriksa penyebab angka.
5. Gunakan Regional command dan top cities/business types untuk melihat distribusi.

Completeness menghitung field name, phone, email, province, city, district, village dengan bobot sama. Contoh 5 dari 7 terisi ≈ 71%; pembulatan ditampilkan UI. Data health keseluruhan merata-ratakan persentase keterisian tujuh field. Custom attributes belum menambah skor ini; kebijakan bobot yang dapat dikonfigurasi masih target.

Peta memakai koordinat provinsi referensi dan tile OpenStreetMap. Peta bukan lokasi GPS tiap customer. Bila tile tidak termuat, periksa internet; daftar/ranking wilayah tetap memberi informasi yang tersedia.

Panel insight deterministik tidak menjadi bukti AI telah aktif. Nilai — atau empty state menunjukkan data/fitur belum tersedia; jangan mengubahnya menjadi nol penjualan atau menyimpulkan tidak ada potensi bisnis.

Analytics: membandingkan periode

Halaman: /analytics. Pilihan periode: 3, 6, 12 bulan; default 6 bulan.

1. Pilih rentang bulan.
2. Baca new customers/messages/read rate beserta perbandingan periode sebelumnya.
3. Tinjau tren customer dan pesan per bulan.
4. Baca funnel sent → delivered → read → clicked → replied.
5. Bandingkan channel dan segment; cari konteks di campaign/Experience terkait.

Hasil: ringkasan pertumbuhan, event campaign, channel, segment dan kota. Total customer adalah populasi saat ini; new customers dibatasi periode. Periode dimulai awal bulan pada timezone workspace, bukan rentang tanggal bebas. Perbandingan memakai rentang bulan sebelumnya dengan panjang sama.

Read rate = event read ÷ event sent × 100% pada periode yang dibaca. Bila belum ada sent, rate tidak bermakna dan dapat tampil —. Angka funnel bergantung event provider; tidak setiap channel mengirim semua event. Periode event read/sent bisa berbeda dari tanggal pembuatan campaign, sehingga hindari menganggap semua tahap sebagai cohort penerima yang persis sama.

Event simulasi dapat ikut agregat dan UI menandainya. Jangan memakai hasil simulasi sebagai laporan delivery nyata. Revenue/order/ROI belum dapat dihitung dari modul transaksi yang belum tersedia.

Rekonsiliasi dan hasil kerja

Metrik memakai cache hingga 5 menit; banyak perubahan model menginvalidasi cache lebih awal. Bulk event tertentu dapat terlihat setelah TTL. Muat ulang setelah job selesai, gunakan filter/periode yang sama, dan periksa Trash sebelum menyimpulkan angka salah. Data baru dapat menambah profil atau hanya memperkaya profil lama.

Contoh laporan yang tepat: “Periode 6 bulan, customer baru X, sent Y, sebagian event simulasi; kelengkapan email perlu ditingkatkan.” Sertakan periode dan batas data, bukan sekadar screenshot angka tanpa konteks.

04 · Data Sources dan Import

Prasyarat dan hasil akhir

Role: Super Admin, Admin, Data Analyst. Halaman: /data-sources. Siapkan sumber customer yang boleh digunakan, pemilik tiap kolom, serta worker imports untuk commit. Sumber harus customer; jalur transaksi belum tersedia.

Hasil akhir bukan sekadar file terunggah: batch harus committed, counters telah dibaca, profil bisa ditemukan di Customers, dan invalid/review memiliki tindak lanjut.

Menyiapkan file dan identitas

CSV harus UTF-8, memiliki header, dan memakai susunan kolom konsisten. Upload maksimal 20 MiB. XLSX perlu diekspor menjadi CSV dahulu; export customer XLSX adalah fitur berbeda. Hindari header kosong/ganda dan baris dengan jumlah kolom melebihi header; parser saat ini dapat memotong nilai berlebih tanpa menandai baris invalid.

Contoh sintetis berikut tidak memuat nomor telepon yang berpotensi milik orang:

Nama,Email,Kota,Jenis Usaha
Toko Impor Demo,impor@example.test,Kota Surabaya,Bengkel

Pastikan email/phone milik customer, bukan surveyor, agen, atau kantor bersama. Kontak berulang yang salah dipetakan sebagai identitas berisiko menggabungkan orang. Untuk external ID, koordinasikan namespace sumber: implementasi import saat ini belum menyediakan pemetaan external_source terpisah; ID sama dari sistem berbeda dapat bertabrakan. Jangan langsung memakai ID lokal dari dua sistem sebagai satu identitas tanpa penilaian pengelola data.

Memasukkan data

Google Sheet publik: atur akses agar dapat dilihat melalui tautan. Tempel URL Spreadsheet di Data Sources; sertakan gid bila ingin tab tertentu. Tanpa gid, export memakai tab pertama/default. Jangan mengubah sheet privat menjadi publik tanpa otorisasi pemilik data; gunakan upload CSV bila sumber harus tetap privat.

URL CSV: gunakan URL HTTPS publik yang langsung mengembalikan CSV, bukan halaman login/HTML. URL jaringan privat/internal dan redirect yang tidak diizinkan ditolak.

Upload: pilih file CSV dari komputer melalui kontrol upload. Upload adalah snapshot; perubahan file komputer tidak otomatis tersinkron.

Setelah data dapat dibaca, aplikasi membuka batch mapping. Pada tahap ini file dan baris staging sudah tersimpan, tetapi customer belum diubah.

Memeriksa mapping

1. Baca header, Samples, dan Filled / unique setiap kolom.
2. Cocokkan kolom ke field utama, attribute, atau Ignore.
3. Periksa semua email/phone secara manual; jangan menerima saran otomatis begitu saja.
4. Pastikan satu target hanya dipakai satu kolom. Gabungkan kolom di sumber jika perlu.
5. Pastikan minimal satu dari name, phone, email, external ID terpetakan. Ini syarat mapping, bukan jaminan setiap baris memiliki identitas yang cukup.
6. Tekan tombol commit setelah yakin; pilih satu batch yang benar, hindari duplikat snapshot.

Nama key attribute berbentuk huruf kecil/angka/underscore. Gunakan arti yang stabil, misalnya jenis_usaha. Nilai placeholder global seperti invalid, invld, tidak valid, data tidak valid, -, n/a, null diperlakukan kosong, termasuk pada attribute. Jika “Tidak Valid” merupakan kategori bisnis yang perlu dibedakan, eskalasikan definisi datanya; jangan menganggap filter empty akan memulihkan kategorinya.

Rasio unique rendah pada email/phone menampilkan peringatan; ambang saran saat ini 0,5. Saran otomatis dapat memindahkan kolom ke attribute. UI dapat tetap menyimpan mapping berisiko; pengelola wajib menilai pemilik kontak, bukan menganggap server selalu menolaknya.

Commit dan membaca hasil

Progress adalah total rows dikurangi pending, bukan jumlah customer baru. Hasil per baris:

Konflik field pada profil yang cocok dapat menghasilkan review sambil baris berstatus updated/unchanged. Jumlah Review Queue tidak wajib sama dengan counter review batch. Lima counters adalah outcome baris; jumlahnya tidak sama dengan jumlah field konflik.

Re-import identitas yang sama biasanya menautkan profil yang sama, tetapi idempotensi bergantung identitas/mapping. File sama tanpa identitas memadai tidak menjamin hasil aman. Jangan memulai ulang hanya karena proses lambat. Error batch dapat terjadi setelah sebagian chunk sudah committed; retry perlu pemeriksaan, bukan asumsi rollback seluruh file.

Sumber tersambung dan sync

Commit Sheet/URL CSV yang berhasil menyimpan source dan mapping untuk sync berikutnya. Upload CSV tidak menjadi sumber file komputer yang dipantau. Sync now mengambil ulang data source; Auto-sync mengaktifkan/menonaktifkan penjadwalan. Interval default 3 jam, dapat diatur Super Admin; scheduler memeriksa sumber due tiap 10 menit.

Layout header yang berubah meminta mapping baru; periksa sebelum commit. Layout sama dapat memakai mapping sebelumnya. Incremental saat ini membandingkan isi baris dengan histori processed source. Perubahan A → B → A dapat terlewati karena A pernah diproses; jangan menjanjikan sinkronisasi snapshot sempurna. Menghapus baris di Sheet juga tidak berarti customer otomatis dihapus. Untuk kasus koreksi/reversion, minta operator data meninjau sumber dan staging.

Disconnect memerlukan mengetik DELETE, ditolak saat source syncing, dan menghentikan koneksi source; customer hasil import tetap ada. Riwayat batch menjadi terlepas dari source. Tombol disconnect bukan reset customer. Penghapusan batch secara terpisah belum memiliki route UI pada versi ini walaupun permission imports.delete terdaftar.

Bukti selesai

Catat ID batch, status committed, counters, mapping yang disepakati, dan pemilik tindak lanjut invalid/review. Untuk sumber tersambung, periksa status dan waktu sync terakhir. Gunakan ID dan ringkasan agregat pada handoff; simpan sample pelanggan hanya di penyimpanan privat yang memang diperuntukkan untuk itu.

05 · Customer, identitas, dan Review Queue

Menemukan dan membaca customer

Halaman: /customers. Akses baca: semua role.

1. Gunakan pencarian nama/phone/email.
2. Persempit dengan segment, provinsi, atau ketersediaan kontak.
3. Buka customer untuk melihat detail.
4. Pastikan filter yang aktif sebelum membaca jumlah atau melakukan export/aksi massal.
5. Pindah halaman daftar bila data melebihi 25 profil per halaman.

Detail memuat profil, identifier, attributes, dan informasi terkait yang tersedia. Kosong berarti belum ada nilai yang tersimpan, bukan selalu “tidak memiliki”. Nilai attribute dapat berubah sesuai sumber terbaru. Permission create/update customer terdaftar, tetapi halaman ini belum menjadi editor CRUD manual lengkap; pengayaan berjalan lewat import, Experience, dan keputusan review.

Aturan identitas dan pengayaan

Telepon dinormalisasi ke E.164 bila valid, default wilayah Indonesia. Satu field dapat berisi beberapa nomor; semua nomor valid dapat menjadi identifier, nomor pertama menjadi utama. Nomor tidak valid tidak menjadi identifier; raw tetap di staging. Email/phone tersimpan tidak membuktikan izin pemasaran eksplisit. Opt-out per channel memengaruhi eligibility campaign.

Export CSV dan Excel

Akses: Super Admin, Admin, SPV, Data Analyst; VIP hanya jika diberi customers.export secara langsung. Tombol Export muncul sesuai izin.

1. Terapkan filter customer yang dibutuhkan.
2. Pilih Export.
3. Pilih current filters/segment bila ingin subset, atau All customers untuk seluruh customer non-Trash.
4. Pilih CSV atau Excel .xlsx dan tunggu unduhan selesai.
5. Periksa jumlah dan kolom file sebelum meneruskan analisis.

Hasil: file berisi ID, profil, status, opt-outs, created/updated, serta attribute yang ditemukan pada populasi export (maksimal 300 key). Waktu mengikuti timezone workspace. Export mencakup semua hasil filter, bukan hanya 25 baris halaman aktif. Tombol tidak ditampilkan pada Trash. Data file adalah snapshot saat diunduh, tidak ikut sync otomatis. CSV memberi perlindungan nilai yang tampak seperti formula; aplikasi spreadsheet dapat menampilkan awalan apostrof pada nilai tertentu. Aksi export dicatat ke audit.

Trash, restore, dan hapus permanen

Move to trash: SPV/Admin/Super Admin memilih baris, atau memakai tombol di detail. “Select all” memilih halaman saat ini, bukan seluruh database. Server menerima maksimal 1.000 ID per aksi. Profil menghilang dari daftar normal/segment; identifier tetap dipegang profil di Trash.

Restore: buka Trash (N), pilih profil, lalu restore. Profil kembali ke populasi normal. Import ulang kontak yang sama tidak otomatis mengeluarkan profil dari Trash; gunakan restore bila ingin menampilkannya lagi.

Delete permanently: hanya Admin/Super Admin, hanya dari Trash, konfirmasi DELETE. Profil dan identifier dihapus; review dan histori campaign terkait dapat terhapus mengikuti relasi. Raw import dan jawaban form dapat tetap ada dengan link customer menjadi null. Hapus permanen bukan anonimisasi semua bukti sumber. Koordinasikan kebutuhan retention dengan operator sebelum memakai aksi ini.

Review Queue: konflik nilai

Halaman: /review. Akses: Super Admin, Admin, Data Analyst.

1. Pilih jenis conflict, field, atau customer untuk mempersempit daftar pending.
2. Bandingkan current/incoming serta sumber dan konteks profil.
3. Pilih keputusan yang sesuai bukti:

Bulk hanya untuk konflik, maksimal 100 ID, menggunakan validasi yang sama per item. Perhatikan toast jumlah resolved/skipped; item yang sudah ditangani orang lain tidak boleh dianggap terselesaikan ulang. Bulk tidak membuktikan seluruh field memiliki kebenaran yang sama; kelompokkan berdasarkan alasan yang benar-benar seragam.

Review Queue: identitas ambigu

1. Pilih identity dan baca payload serta daftar kandidat.
2. Periksa customer kandidat dan bukti asal data.
3. Pilih This one pada kandidat yang benar untuk attach, Create separate bila memang entitas berbeda, atau Ignore bila belum layak dipakai.
4. Sesudah attach, periksa konflik field tambahan yang dapat muncul.

Attach berarti menerapkan record masuk ke kandidat yang dipilih. Ini bukan tombol umum untuk menggabungkan dua profil master lengkap. UI universal “merge dua customer” belum tersedia; jangan menyamakan istilah target Merge dengan aksi attach sekarang.

Hasil review: item keluar dari pending, memiliki resolution/pelaku/waktu, serta audit. Gunakan alasan berbasis sumber pada catatan kerja; jumlah review berkurang tidak boleh menjadi alasan memilih incoming tanpa validasi.

06 · Segments dan audience dinamis

Baca: semua role. Kelola: Super Admin, Admin, SPV, Data Analyst. Halaman: /segments; builder melalui create atau edit segment yang dipilih.

Segment menyimpan aturan, bukan salinan daftar customer. Anggota mengikuti data profil saat query dijalankan. Seorang customer dapat masuk banyak segment. Menghapus segment tidak menghapus customer.

Membuat segment

1. Pilih Create segment atau template yang tersedia.
2. Isi nama yang menjelaskan audience serta deskripsi tujuan.
3. Pilih Match all (AND) atau Match any (OR).
4. Tambahkan condition: field, operator, value.
5. Bila perlu tambahkan grup AND/OR satu tingkat dan kondisi Exclude.
6. Periksa estimate dan sampai 10 sampel preview; cocokkan dengan tujuan bisnis.
7. Simpan, lalu buka daftar customer dari segment untuk pemeriksaan lebih luas.

Contoh: “Bengkel Surabaya” dengan City equals Kota Surabaya AND Jenis Usaha equals Bengkel. Hasil adalah profil yang memenuhi kedua kondisi, bukan semua customer Surabaya ditambah semua bengkel.

Field, operator, dan logika

Field utama: name, phone, email, province, city, district, village. Attribute muncul berdasarkan key pada data customer yang ada. Saran nilai mengambil sampai 20 nilai teratas. Saran bukan kamus wajib; nilai lain tetap dapat dimasukkan sesuai operator.

Angka pada attribute disimpan sebagai teks; operator numerik hanya cocok nilai yang terbaca angka. Operator tanggal/rolling period belum tersedia. Maksimal 30 condition dan grup bersarang satu tingkat; jangan merancang nesting tak terbatas.

Rules tanpa condition mencocokkan seluruh customer non-Trash, sebelum exclude. Jangan menyimpan segment kosong dengan anggapan audience-nya nol; periksa preview.

AND: seluruh kondisi harus cocok. OR: salah satu cukup. Exclude: keluarkan customer yang cocok salah satu kondisi exclude. Customer dengan field kosong tidak otomatis terbuang hanya karena tidak memenuhi teks exclude. Untuk kebutuhan kosong, gunakan operator empty/set secara eksplisit.

Contoh grup: (city = Surabaya OR city = Bandung) AND jenis_usaha = Bengkel. Contoh exclude: buang attributes.status_toko equals Tutup. Periksa preview untuk memastikan logika sesuai, terutama ketika ada data kosong.

Membaca hasil dan merawat segment

Rules attribute yang sudah disimpan tetap valid ketika data kosong/reset; attribute yang belum dimiliki siapa pun dapat menghasilkan nol. Field suggestions dapat berkurang bila tidak ada data. Tidak perlu mengubah rule hanya untuk memaksa count menjadi positif.

Gunakan Duplicate untuk membuat variasi tanpa mengubah definisi lama. Edit akan memengaruhi penggunaan dinamis berikutnya; audience one-time campaign yang sudah dibentuk tidak otomatis diganti hanya karena segment diedit. Ongoing dapat menambah anggota eligible baru pada tick berikutnya. Sebelum delete, periksa campaign yang memakainya; penghapusan segment dapat mengurangi audience definisi tersebut.

VIP dapat membuka builder sebagai pembaca, tetapi tidak menyimpan/duplicate/delete. Audience Copilot masih planned; gunakan builder manual.

Hasil kerja selesai: nama/deskripsi jelas, aturan disimpan, count/sample sesuai, serta pemakai campaign memahami bahwa segment bersifat dinamis.

07 · Campaigns: dari draft sampai hasil

Baca: semua role. Kelola: Super Admin, Admin, SPV, Data Analyst. Halaman: /campaigns.

Prasyarat channel dan mode

Satu campaign memakai satu channel. WhatsApp nyata memerlukan konektor Qiscus connected dan template yang telah disetujui provider. Email/SMS campaign masih simulasi. SMTP yang connected hanya mengaktifkan email sistem pada jalur saat ini. WhatsApp tanpa provider connected juga menggunakan simulasi saat launch; periksa label mode, jangan menyimpulkan adanya delivery nyata dari status sent saja.

Tidak ada aksi kirim nyata yang dijalankan untuk menghasilkan screenshot manual ini.

Membuat dan memeriksa campaign

1. Buat campaign; isi nama, purpose, priority dan channel.
2. Pilih mode One-time atau Ongoing.
3. Pilih include segment dan exclude segment bila diperlukan.
4. Baca matched, duplicates removed, eligible, dan preview.
5. Susun pesan/template sesuai channel.
6. Atur jadwal mulai bila diperlukan, hari aktif, dan jam kirim.
7. Simpan draft. Periksa readiness dan mode nyata/simulasi sebelum launch.
8. Launch jika audience, konten, dan jadwal telah disetujui pemilik campaign.

Matched adalah customer unik di gabungan include sebelum pengurangan exclude/ eligibility. Duplicates removed adalah overlap membership, bukan profil terhapus. Eligible menyaring exclude, destination, status aktif, dan opt-out channel. Jumlah ini belum menjamin semua recipient lolos cap/window saat pengiriman.

Implementasi eligibility memakai status aktif dan opt-outs; tidak ada editor consent eksplisit lengkap di UI sekarang. Data contactable tidak dengan sendirinya membuktikan consent pemasaran. Pengelola memastikan dasar penggunaan channel sebelum launch.

Menulis pesan

Email membutuhkan subject dan body; SMS body. Variabel yang dikenal: {{name}}, {{city}}, {{district}}, {{province}}.

Contoh sintetis: Halo {{name}}, kami mengundang usaha Anda di {{city}} mengisi survei. Preview membantu menemukan field kosong/variabel yang salah sebelum launch.

WhatsApp menggunakan nama template approved, bahasa, serta body parameter berurutan. Placeholder provider seperti {{1}} dihubungkan ke variabel profil yang tersedia. Body preview tidak menggantikan persetujuan template di Qiscus/Meta. Perubahan konektor yang material perlu save/test ulang; daftar template yang tersedia berasal dari konfigurasi/integrasi, bukan generator AI.

Readiness, lifecycle, dan kontrol

Readiness memeriksa segment terpilih, eligible > 0, kelengkapan message/template, dan konfigurasi sending window. Readiness bukan pengujian delivery end-to-end. Hanya draft yang bisa diedit.

Gunakan tombol pause/resume/stop/cancel yang tersedia sesuai status. Untuk membatalkan campaign aktif, UI dapat memerlukan pause terlebih dahulu; server tidak menerima status bebas. Hapus campaign hanya diizinkan pada status draft atau cancelled; riwayat terkait ikut relasi penghapusan. Untuk campaign berjalan, kendalikan lifecycle lebih dahulu dan pertimbangkan kebutuhan menyimpan bukti hasil.

Scheduler mengantrekan tick setiap menit pada jalur campaigns. Di luar window, recipient menunggu. One-time selesai ketika tidak ada recipient queued; selesai tidak berarti semuanya delivered/read. Ongoing menunggu anggota eligible baru sampai dihentikan.

Frequency cap dan hasil penerima

Default cap adalah 5 pesan per customer per minggu, gabungan seluruh channel. Awal minggu mengikuti timezone client. High priority tetap tunduk cap. One-time melewati recipient yang mencapai cap; ongoing dapat menunggu minggu berikutnya. Kode setting sekarang menerima 1–50, sementara aturan produk menyebut batas 5; perbedaan ini membutuhkan keputusan produk, dan bukan rekomendasi menaikkan cap.

Unique recipient per campaign/customer mencegah penambahan anggota ganda. Kegagalan provider tidak otomatis di-retry karena risiko kirim dobel. Jangan membuat kampanye ulang ke audience sama sebagai jalan pintas tanpa memeriksa delivery sebelumnya.

Membaca hasil dan tindak lanjut

Buka daftar campaign untuk status dan counters, kemudian Analytics untuk agregat periode/channel/funnel. Pisahkan hasil simulasi dari pengiriman nyata. Untuk form survei, periksa submission di Experiences; tautan biasa tidak otomatis membuktikan attribution campaign. Link customer bertanda tangan didukung server, tetapi penyisipan otomatis/journey lengkap belum menjadi flow builder saat ini.

Handoff campaign mencakup tujuan, channel, mode, segment include/exclude, jadwal, jumlah eligible, status terakhir, dan tindak lanjut failed/skipped. Hindari klaim ROI atau revenue ketika data transaksi belum ada.

08 · Experiences: form, survei, dan pengayaan

Baca/respons: semua role login. Kelola: Super Admin, Admin, SPV, Data Analyst. Responden: publik, tidak perlu akun. Halaman pengelola: /experiences.

Membuat form atau survei

1. Pilih Create experience, lalu Form atau Survey.
2. Isi nama internal dan purpose: lead capture, profile enrichment, feedback, preference, event signup, atau other.
3. Atur judul publik, deskripsi, hero opsional, label tombol, dan thank-you message.
4. Tambahkan/edit pertanyaan, tipe, required, pilihan, dan tujuan pemetaan datanya.
5. Gunakan preview untuk membaca tampilan responden.
6. Simpan draft untuk meninjau. Ubah status published untuk menerima jawaban.
7. Salin URL publik dan uji dengan data sintetis sebelum membagikannya kepada audience.

Nama internal maksimal 120 karakter; judul publik 160, deskripsi 2.000, thank-you 255, label tombol 40. Hero mendukung JPG/JPEG/PNG/WebP hingga 2 MiB. Penyimpanan hero dan file memerlukan storage aplikasi yang berfungsi.

Pertanyaan dan pemetaan

Satu Experience memiliki 1–50 pertanyaan; key harus unik, diawali huruf kecil, kemudian huruf kecil/angka/underscore, maksimal 40 karakter. Pilihan maksimal 20 per pertanyaan, tidak boleh ganda. Target field profil hanya dapat dipakai sekali.

File otomatis response only. Lokasi penuh hanya boleh satu pertanyaan dan tidak digabung pertanyaan terpisah yang menulis provinsi/kota/kecamatan/desa. Pilih lokasi bertahap dari daftar; jika parent berubah, pilih ulang level turunannya. Referensi wilayah disimpan lokal, tidak menebak label bebas.

Status dan publikasi

Draft/closed tidak berarti URL selalu 404; halaman dapat tetap terbuka dengan pesan closed. Jangan meletakkan informasi rahasia pada judul/deskripsi form yang punya URL publik. URL memakai slug unik; jangan menganggapnya password.

Alur responden

1. Buka URL /f/{slug} tanpa login.
2. Isi semua pertanyaan required, pilih rating/lokasi/pilihan sesuai layar.
3. Lampirkan file bila diminta dan masih dalam batas ukuran/tipe.
4. Tekan tombol submit; perbaiki pesan validasi di bawah field bila ada.
5. Setelah berhasil, halaman menampilkan thank-you message.

Hasil UI sukses berarti jawaban diterima; belum tentu membuat customer baru. Responden dapat cocok ke profil lama, membuat profil baru, menimbulkan review, atau tetap anonymous. Sistem membatasi submit publik 20 per menit per mekanisme throttle route; terlalu banyak percobaan dapat menampilkan 429.

Membaca respons dan dampaknya

1. Dari Experience, buka Responses/Submissions.
2. Baca waktu, jawaban, status, dan customer terkait.
3. Unduh lampiran dari tautan bila tersedia; pengunduhan memerlukan login/izin baca.
4. Cari customer untuk memastikan pengayaan profil, atau buka Review Queue untuk identitas/field yang ambigu.

Nama saja dapat menghasilkan anonymous. Nama + kota atau email/phone yang valid membantu resolver. Field standar yang berbeda tetap melalui konflik; attribute mengikuti latest-wins dengan audit. “None” tidak dapat dicari sebagai attribute segment karena hanya tersimpan di jawaban.

Daftar respons dipaginasi 50 per halaman. Views bertambah saat halaman published dibuka, termasuk kunjungan ulang; bukan unique visitor. Conversion/responses ÷ views adalah indikator sederhana dan tidak menjamin identitas/attribution pemasaran. Channel yang tidak tercatat dapat tampil direct.

Sebelum mengubah key/field pada form yang sudah menerima jawaban, pertimbangkan bahwa schema builder dan jawaban lama dapat berbeda. Simpan versi form baru bila perlu mempertahankan interpretasi pertanyaan lama. Menghapus Experience menghapus jawaban/ lampiran terkait sesuai relasi/storage; profil customer hasil pengayaan tetap terpisah. Landing page/journey yang bertanda Soon belum menjadi tipe builder yang tersedia.

09 · Settings: workspace, akun, integrasi, dan sistem

Menu Settings memiliki dua arti Integrations: item workspace dapat menuju Data Sources; konfigurasi WhatsApp/SMTP berada di Communication channels (/settings/integrations). Gunakan tujuan halaman, bukan hanya kemiripan nama.

General dan workspace

Baca: Super Admin/Admin. Simpan: Super Admin.

1. Buka General, periksa nama workspace, timezone, kontak perusahaan, website, bahasa, mata uang, dan interval sync.
2. Ubah field yang diperlukan dan simpan bila berwenang.
3. Baca toast dan muat ulang untuk memastikan perubahan tersimpan.
4. Periksa Database, Queue, AI server dan File storage. Status probe bukan load test atau bukti worker sedang memproses seluruh jalur.

Timezone memengaruhi jadwal campaign, minggu cap, rentang audit dan tampilan waktu tertentu. Currency saat ini IDR; language id/en tersedia sebagai preference tetapi tidak berarti seluruh UI telah diterjemahkan. Interval sync: 1, 3, 6, 12, 24 jam; default 3 jam. Data source juga harus Auto-sync aktif dan scheduler/worker berjalan.

Backup

Super Admin menekan Back up now untuk mengantrekan backup pada jalur imports. Periksa riwayat hingga succeeded, ukuran dan finished time; toast “started” bukan bukti dump selesai. Backup harian dijadwalkan 02:00 Asia/Jakarta dengan retensi default 14. Disk default local belum merupakan salinan offsite.

Status failed perlu diperiksa operator: pg_dump, versi client/server, disk, permission, dan error run. Backup database tidak mencakup seluruh object file. Tidak ada tombol restore UI; lihat runbook operator.

Reset workspace

Hanya Super Admin, konfirmasi password dan nama workspace persis. Aksi menghapus customer, review, import/staging, source, segment, campaign beserta run/recipient/event, Experience beserta jawaban, dan direktori file bisnis terkait. User/role/settings, koneksi integrasi, audit log, dan referensi wilayah dipertahankan.

Ini berbeda dari reset import terarah pada riwayat pengembangan. Jangan memakai reset workspace bila hanya ingin membersihkan satu sumber atau memindahkan beberapa profil ke Trash. Pastikan keputusan bisnis dan backup sesuai sebelum mengeksekusinya.

Users & roles

Super Admin: seluruh role. Admin: semua kecuali akun Super Admin.

1. Buka Users & roles; cari nama/email atau filter role/status.
2. Pilih pembuatan user, isi nama, email unik huruf kecil, role, dan password awal.
3. Simpan; sampaikan akses melalui kanal privat yang disepakati. UI membuat akun dengan password awal, bukan workflow undangan email otomatis lengkap.
4. Untuk ubah profil/role, pilih edit pada akun yang berwenang dikelola lalu simpan.
5. Untuk menghentikan akses, gunakan deactivate; middleware mengeluarkan akun inactive pada request berikutnya. Aktifkan kembali bila diperlukan. Jangan menganggap flow ini sudah menjadi fitur manajemen/pencabutan token API lengkap.
6. Delete memerlukan konfirmasi email akun persis; gunakan hanya bila diperlukan.

Tidak boleh menonaktifkan/menghapus diri sendiri. Super Admin aktif terakhir tidak boleh dinonaktifkan/dihapus/diturunkan. Admin tidak boleh membuat, mengubah atau menghapus akun Super Admin. Perubahan tercatat di audit. Untuk hak akses rinci lihat matriks role.

Communication channels: WhatsApp/Qiscus

Kelola: Admin/Super Admin.

1. Isi App ID, Secret Key, Channel ID numerik, Namespace dan region id/my dari akun provider yang dipakai.
2. Simpan; konfigurasi lengkap yang berubah menjadi ready_to_test.
3. Test menggunakan nomor uji yang disetujui, approved template, bahasa dan body params. Test ini mengirim pesan nyata, bukan hanya ping.
4. Periksa status connected atau error, waktu test, dan pesan provider.
5. Pasang webhook URL aplikasi di konfigurasi Qiscus sesuai kebutuhan; URL mengandung token privat dan tidak boleh disebar ke dokumentasi/screenshot.

Field secret kosong saat menyimpan mempertahankan secret lama. UI hanya menunjukkan flag secret tersimpan; tidak memulangkan nilainya. Mengubah konfigurasi material membatalkan status test lama. Webhook event yang didukung harus mencapai server agar delivery/read bertambah; connected tidak membuktikan semua callback telah diterima.

Communication channels: Email/SMTP

1. Pilih konfigurasi Email · SMTP.
2. Isi host tanpa https:// atau path, port, encryption, username/password bila perlu, from address, dan from name.
3. Simpan; password kosong mempertahankan password lama.
4. Tekan Send test email to me, lalu periksa email akun yang sedang login dan status.
5. Jika error, periksa konfigurasi/provider dan batas jaringan bersama operator.

Hasil: email sistem memakai konektor SMTP ini; mailer .env menjadi fallback saat tidak ada konfigurasi konektor. Worker diberi sinyal restart setelah perubahan. Jangan menyimpulkan campaign Email sudah aktif mengirim nyata; jalurnya masih simulasi. Screenshot tidak menguji SMTP/provider nyata.

Identity resolution dan Campaign settings

Identity resolution menunjukkan jumlah profil, identifier, review dan kebijakan yang dikunci. Ini halaman penjelasan, bukan editor aturan merge. Mengubah kebijakan inti memerlukan perubahan kode/aturan yang ditinjau.

Campaign settings: Admin membaca, Super Admin menyimpan. Atur default hari/jam, priority order yang memuat high/normal/low masing-masing sekali, dan frequency cap. Default window Senin–Jumat 08:00–20:00 dan cap 5 per minggu. Jam akhir harus setelah jam mulai; lintas tengah malam tidak direpresentasikan oleh satu window saat ini. Perbedaan batas kode 1–50 dengan aturan cap maksimum 5 dicatat di cakupan; gunakan kebijakan produk dan eskalasikan perubahan batas.

AI & knowledge

Admin/Super Admin dapat menyimpan API key OpenAI dan model yang ada dalam daftar, lalu test. Key kosong saat simpan mempertahankan key lama. Disconnect memerlukan DISCONNECT dan menghapus key konektor. Ollama diatur lewat environment operator dan dapat diuji dari UI. Failover/circuit status menjelaskan provider yang dapat dipakai, alasan fallback serta waktu retry bila tersedia.

Test provider dapat menggunakan layanan berbayar dan mengirim prompt uji. Jangan memasukkan PII ke key/name/field prompt. Konfigurasi OpenAI-compatible umum/OpenRouter yang disebut keputusan pengembangan belum menjadi editor provider bebas di UI saat ini.

Identity Resolver AI, Audience Copilot, Campaign Copilot, dan Knowledge Base tercantum planned. Provider connected tidak mengaktifkan fitur-fitur tersebut. Tidak ada alur upload dokumen KB aktif yang perlu diikuti pengguna sekarang.

Update & changelog

Admin membaca, Super Admin menjalankan upload/install/rollback dengan konfirmasi password. Operator harus memasang agent host, public key dan allow-list image repository terlebih dahulu; checkout ini baru memiliki komponen updater, belum installer/compose app produksi lengkap.

1. Periksa versi terpasang dan konfigurasi updater.
2. Upload bundle rilis bertanda tangan Ed25519 dari proses rilis tepercaya.
3. Baca versi/catatan, lalu install versi lebih baru.
4. Pantau pending → running → succeeded/failed/rolled_back.
5. Bila perlu, rollback ke image known-good yang tersedia lewat flow rollback.

Web app memverifikasi dan mencatat permintaan; agent host yang membuat backup, mengganti image by digest, menjalankan migration dan health check. Raw ZIP kode tidak didukung. Rollback hanya kode, tidak membatalkan schema/database. Prosedur teknis ada di deploy/updater/README.md.

Audit logs

Admin/Super Admin memilih action, user/system, tanggal from/to pada timezone workspace, lalu meninjau aksi dan entitas. Daftar dipaginasi 30 baris. Gunakan untuk menjawab siapa melakukan apa, kapan dan pada objek mana; detail yang ditampilkan bergantung aksi. Audit bukan layar semua log infrastruktur. Jika investigasi membutuhkan raw source, pakai akses privat operator; jangan menyalin PII/secret ke dev log atau Git.

10 · Teknis, instalasi lokal, dan operasional

Bab ini ditujukan untuk developer/operator. Jalankan perintah dari root repository dan pastikan environment tujuan sebelum migration, seed, restore, atau job manual. Jangan memakai database pelanggan untuk percobaan dokumentasi/testing.

Stack dan batas deployment

Laravel 13/PHP, React/TypeScript/Inertia, Tailwind, PostgreSQL 17 dengan pgvector, Redis queue/cache, S3-compatible storage (MinIO lokal), Ollama opsional dan provider cloud AI. composer.json menerima PHP ^8.3; desain/runtime development memakai 8.4. Gunakan versi PHP/extensions yang memenuhi composer check-platform-reqs.

docker-compose.yml saat ini menyediakan layanan development, bukan app/Nginx/ Horizon/scheduler produksi lengkap. Spesifikasi installer VPS masih dokumen rancangan. Jangan menyebut docker compose up sebagai installer produksi A-Z yang sudah selesai.

Instalasi development baru

Prasyarat: Git, PHP dan Composer, Node/npm yang mendukung toolchain terkunci, Docker Compose. Periksa versi Node terhadap dependency lock/toolchain, bukan menebak dari contoh versi di dokumen lama. Gunakan database yang baru disediakan.

1. Ambil repository dari lokasi yang diberikan pengelola dan masuk root proyek.
2. Salin .env.example menjadi .env hanya pada instalasi baru; jangan menimpa konfigurasi yang sudah ada. Ganti semua kredensial contoh dengan nilai privat.
3. Periksa DB host/port/name, Redis, S3 endpoint/bucket, APP_URL, dan mailer.
4. Pasang dependency, jalankan layanan, buat key dan migration:

composer install
npm.cmd ci
docker compose up -d
php artisan key:generate
php artisan migrate
php artisan user:create-super-admin
npm.cmd run build
composer run dev

Pada shell Linux gunakan npm sebagai pengganti npm.cmd. Perintah pembentukan akun meminta nama, email, password secara interaktif dan menyelaraskan role permission. Jangan menaruh password di command line. db:seed default membuat akun development; untuk produksi gunakan command akun pertama di atas. Jangan menjalankan migrate:fresh pada instalasi berisi data.

Compose lokal memetakan PostgreSQL 5433, Redis 6380, MinIO 9000/9001 untuk menghindari bentrok layanan host. Dari container, port internal berbeda (5432/6379). MinIO init membuat bucket sekali; periksa exit/statusnya. Jangan menggunakan password contoh .env.example pada deployment sungguhan.

composer run dev menghidupkan server/Vite dan runner yang terdaftar, termasuk worker empat jalur dan scheduler. Buka APP_URL yang sesuai port server. Di Windows Horizon memerlukan ekstensi Linux sehingga dev menggunakan queue listener; jangan menjalankan Horizon Windows sebagai syarat dokumentasi.

Jika menjalankan komponen manual:

php artisan serve --host=127.0.0.1 --port=8000
npm.cmd run dev
php artisan queue:work --queue=campaigns,imports,ai,default --tries=1 --timeout=3600
php artisan schedule:work

Jalankan masing-masing pada proses terpisah. Hindari worker/scheduler ganda dari runner lama. Mengakhiri terminal Windows belum tentu mengakhiri pohon proses concurrently; identifikasi proses milik instalasi ini sebelum menghentikannya.

Memverifikasi kesiapan lokal

composer check-platform-reqs
php artisan about
php artisan migrate:status
php artisan route:list --except-vendor
php artisan schedule:list

Lalu login, buka dashboard, stage CSV sintetis, commit, periksa created/customer, buat segment, dan submit form publik sintetis. Jangan menguji channel nyata tanpa penerima uji yang disetujui. /up adalah health endpoint dasar, bukan bukti seluruh integrasi, scheduler, storage, dan delivery sehat.

Queue, scheduler, dan cache

Produksi Horizon mengatur concurrency per jalur; periksa config/horizon.php. Redis retry_after harus lebih panjang dari timeout job paling lama. Import timeout 3.600 detik; konfigurasi kini 3.900 detik. Menambah worker bukan solusi pertama untuk job lambat; periksa database, query, blocking dan resource terlebih dahulu.

Dashboard/Analytics/count segment memakai MetricsCache TTL 300 detik dan versi yang naik ketika model terkait berubah. Bulk write tanpa event wajib bump cache; beberapa event dapat basi hingga TTL. Cache bukan sumber kebenaran data.

Command manual campaigns:tick dapat mengirim pesan nyata dan sources:sync dapat mengubah data. Gunakan setelah memeriksa environment, campaign/source due dan worker; bukan perintah observasi tanpa dampak. queue:failed bisa dipakai menginspeksi gagal, tetapi jangan queue:retry all tanpa diagnosis dan pemahaman idempotensi.

Backup dan restore

Manual backup:

php artisan backup:run

Hasil: backup_runs dengan disk/path/status/size/time; format dump PostgreSQL custom. Default local berada di storage privat backups. Retensi di BACKUP_KEEP; arahkan BACKUP_DISK ke disk S3 eksternal yang telah dikonfigurasi untuk salinan offsite. pg_dump harus versi sama/lebih baru dari server (PostgreSQL 17 pada stack ini). Host/port backup dari dalam container harus cocok, jangan memakai port forwarding host tanpa memeriksa konteks proses dump.

Dump hanya database. Backup terpisah diperlukan untuk object storage, .env/APP_KEY, dan konfigurasi infrastruktur secara aman. APP_KEY diperlukan membaca secret terenkripsi; jangan mengganti key pada instalasi berjalan sebagai cara mengatasi error sembarang.

Prosedur pemulihan operator:

1. Pastikan target, waktu dump, versi app/schema, dan file storage yang cocok.
2. Backup kondisi sekarang dan uji dump pada database pemulihan terpisah dahulu.
3. Hentikan penulisan/scheduler/worker untuk cutover sesuai rencana maintenance.
4. Jalankan pg_restore ke target pemulihan dengan identitas DB yang disetujui.
5. Periksa schema, akun, jumlah data, file terkait dan flow penting.
6. Alihkan konfigurasi bila memang rencana cutover disetujui, restart worker, lalu verifikasi login/dashboard/import/campaign dan catat hasil.

Contoh pola pada shell operator (ganti nama/path contoh sesuai target pemulihan):

pg_restore --list /private/path/backup.dump
pg_restore --host=127.0.0.1 --port=5433 --username=operator --dbname=dataplatform_restore --no-owner --no-privileges /private/path/backup.dump

Target harus sudah dibuat kosong dan memiliki extension/prasyarat yang sesuai. Gunakan prompt password/penyimpanan kredensial privat; jangan menaruh password dalam command atau Git. --clean terhadap database aktif bersifat destruktif; tidak menjadi langkah default latihan ini. Restore produksi bukan kemampuan UI sekali klik.

Deployment dan update produksi

Target arsitektur: satu VPS 4 vCPU/16 GB, reverse proxy HTTPS dan app, PostgreSQL, Redis, storage, worker dan scheduler; Ollama dibatasi agar tidak menghabiskan RAM/CPU. Layanan internal tidak dibuka publik. Compose development belum menerapkan seluruh topologi tersebut, sehingga operator harus melengkapi deployment sebelum go-live.

Gunakan APP_ENV=production, APP_DEBUG=false, APP_URL HTTPS yang benar, cookie/CSRF sesuai domain, backup offsite, dan secret privat. Pastikan worker/scheduler supervised serta environment sama. Ikuti aturan runtime dan runbook updater untuk bundle Ed25519, image digest, public key host dan health check. Migration harus expand/contract karena rollback kode tidak mengembalikan database.

Pemeriksaan developer

composer ci:check menjalankan pemeriksaan frontend, TypeScript, style PHP, PHPStan dan test. phpunit.xml menunjuk database dataplatform_test; sediakan terpisah sebelum test (suite memakai RefreshDatabase). Hasil CI lama di log bukan hasil sesi baru. Untuk perubahan manual saja, jalankan pemeriksaan dokumentasi di bab 12; jangan mengklaim seluruh CI lulus bila hanya mengambil screenshot.

Tidak ada REST API eksternal umum/Sanctum yang lengkap hanya karena disebut desain. Route yang ada adalah web session, form publik, webhook Qiscus dan endpoint framework; periksa route aktual sebelum memberikan kontrak integrasi kepada pihak lain.

11 · Troubleshooting dan glosarium

Mulai dari gejala, periksa status/filter/role dan identitas proses. Hindari mengulang mutasi hanya untuk “mencoba lagi”. Eskalasi dengan halaman, waktu/timezone, role, ID batch/campaign/Experience, status dan pesan error yang sudah dibersihkan dari secret.

Data dan audience

Campaign, form, dan integrasi

Halaman error

Pada produksi detail exception tidak ditampilkan (APP_DEBUG=false). Waktu UTC pada halaman 5xx membantu pencocokan log; sertakan timezone ketika melapor. Error saat navigasi Inertia dapat muncul dalam modal. Tombol Back/Retry tidak menjamin aman mengulang mutasi yang mungkin sudah diproses.

Glosarium

12 · Dokumentasi yang terus diperbarui

Aturan pembaruan

Manual ini menjadi bagian pekerjaan pengembangan. Dokumentasi dianggap selesai ketika perilaku, langkah, hasil, akses, screenshot yang berubah, serta bukti verifikasinya telah disesuaikan. Kewajiban ini juga dicantumkan di indeks utama, yang harus dibaca setiap sesi sesuai AGENTS.md.

Pembaruan tidak terjadi sendiri saat UI berubah. Script dapat mengulang capture, memeriksa referensi dan membangun buku; penulis tetap memeriksa makna berdasarkan kode dan hasil aktual. Jangan mengklaim sinkronisasi otomatis penuh.

Checklist setiap perubahan

1. Baca docs/README.md dan entri log terbaru; tulis scope/baseline sebelum implementasi.
2. Tentukan bab, role dan gambar terdampak. Update aturan authoritative bila ada keputusan produk/data baru sebelum mengubah perilaku.
3. Implementasikan dan verifikasi fitur; pisahkan fitur aktif, simulasi dan planned.
4. Perbarui langkah, input, output/status, batas akses dan cara menangani kegagalan.
5. Bangun bundle frontend terbaru bila akan mengambil screenshot.
6. Regenerasi gambar dalam lingkungan sintetis terisolasi; jangan screenshot customer sungguhan, password, QR 2FA, recovery code, API key atau token webhook.
7. Periksa screenshot ukuran asli: halaman benar, konten termuat, label terbaca, data sintetis, field sensitif disamarkan. Jangan mengganti UI dengan mockup AI.
8. Perbarui tanggal manual, coverage.md, dan hasil aktual di log.
9. Bangun HTML, jalankan pemeriksaan dokumen, periksa buku di browser.
10. Tinjau diff termasuk gambar dan pastikan handoff menyebut keterbatasan yang belum diuji. Ikuti otorisasi pemilik untuk commit/push; script tidak melakukan keduanya.

Lokasi sumber dan alat

PNG dari docs/references adalah referensi desain historis, bukan bukti UI aplikasi terpasang. Manual menggunakan screenshot baru di foldernya sendiri. Gambar memakai viewport 1440×1000 dengan full page; tinggi file mengikuti isi. Input readonly dimask pada capture untuk mencegah token webhook ikut gambar. Fixture memakai alamat example.test, label Demo, serta tanpa nomor telepon penerima nyata.

Mengulang capture pada Windows

Gunakan checkout lokal dengan PostgreSQL berjalan, kredensial dev yang dapat membuat database baru, vendor terpasang dan bundle public/build tersedia. Bootstrap menolak cached config agar tidak memakai database bisnis. Jangan mengubah config produksi hanya untuk menjalankan dokumentasi; gunakan checkout terpisah.

Pasang tool di direktori sementara, tidak mengubah dependency aplikasi:

$docsBrowserPath = Join-Path $env:TEMP 'dataplatform-docs-browser'
npm.cmd install --prefix $docsBrowserPath playwright --no-audit --no-fund
$docsPythonPath = Join-Path $env:TEMP 'dataplatform-docs-python'
python -m pip install --target $docsPythonPath -r docs/manual/tools/requirements.txt
npm.cmd run build
$env:DOCS_BROWSER_MODULES = $docsBrowserPath
$env:PYTHONPATH = $docsPythonPath
python docs/manual/tools/refresh.py
python docs/manual/tools/build_pdf.py
python docs/manual/tools/verify_pdf.py
python docs/manual/tools/build.py
python docs/manual/tools/check.py
python docs/manual/tools/check.py --source
node docs/manual/tools/verify-book.mjs
node docs/manual/tools/verify-print.mjs

Default browser Chrome yang terpasang; untuk Edge set $env:DOCS_BROWSER_CHANNEL = 'msedge'. Jika browser tidak tersedia, pasang browser yang sesuai sebelum capture; jangan menganggap download Chromium selalu sudah ada.

refresh.py membuat nama dataplatform_docs_YYYYMMDDHHMMSS baru. seed.php menolak database yang sudah ada dan tidak memakai migrate:fresh. Cache array, cookie sesi khusus, storage privat storage/app/private/documentation/<nama-db>, email log, serta Ollama dinonaktifkan untuk sesi ini. Password random tidak ditulis ke repository. Script tidak menyalakan worker/scheduler dan tidak launch campaign atau mengirim test provider. Form publik yang disubmit hanya milik demo.

Setelah selesai/gagal, server yang dibuat script dihentikan; database sintetis ditinggalkan agar bisa diperiksa. Operator dapat membersihkan hanya DB dengan prefix tersebut dan marker workspace demo setelah memastikan tidak ada koneksi yang dipakai. Jangan memakai wildcard untuk menghapus database/file bisnis. Log server lokal berada di storage/logs/documentation-server.log, tidak masuk buku atau Git.

Fixture bergantung schema/controller/action terbaru. Jika route/label/status/field berubah, sesuaikan seed/capture bersama bab manual. Browser automation menggunakan label/role tombol; capture gagal harus didiagnosis, bukan dilewati agar semua hijau.

Manifest menyimpan fingerprint SHA-256 sumber app, routes, halaman/komponen UI, dan config. check.py --source gagal bila file sumber yang tercatat berubah setelah capture; ini sinyal untuk menilai dampak dokumentasi dan mengambil ulang gambar. Fingerprint tidak membaca .env atau data DB dan tidak menilai kebenaran teks secara semantik. Untuk source baru yang menambah halaman, perbarui inventaris cakupan dan capture; jangan mengandalkan pemeriksaan file lama saja.

Membangun dan membaca buku

Jika tautan HTML dari chat/editor menampilkan source, jalankan server dokumentasi dari root proyek, lalu buka http://127.0.0.1:8020/ di Chrome/Edge:

python -m http.server 8020 --bind 127.0.0.1 --directory docs/manual

Biarkan terminal tersebut berjalan; Ctrl+C menghentikan server. Ini hanya menyajikan folder manual pada komputer lokal dan tidak memerlukan login aplikasi. URL tersebut tidak dapat dibuka dari perangkat lain. Tautan file di editor dapat membuka source; URL HTTP menampilkan buku sebagai halaman browser.

Setelah source Markdown atau screenshot berubah, jalankan build dan check di atas. Buka docs/manual/index.html langsung dari file manager/browser. Semua isi dan CSS lokal; gambar memakai path relatif. Untuk membagikan buku HTML, sertakan folder manual beserta screenshots. Untuk satu file yang siap dibagikan/dicetak, gunakan PDF modul A4. Tombol Cetak / Simpan PDF membuka PDF tersebut; tombol Cetak halaman web menjadi alternatif cetak HTML.

PDF menggunakan font Arial/Consolas dari C:/Windows/Fonts (dapat diubah dengan DOCS_FONT_DIR), ReportLab dan pypdf dari requirements tool dokumentasi. Jalankan build_pdf.py setelah Markdown/gambar berubah, lalu build HTML dan periksa keduanya. File utama di output/pdf/dataplatform-modul-panduan.pdf; salinan identik di folder manual disediakan agar server lokal dapat melayaninya. Tidak ada kebutuhan DB untuk build PDF. Pemeriksaan PDF perlu mencakup daftar isi/bookmark, nomor halaman, semua isi tabel, caption/panel screenshot, dan render visual setiap halaman. Jangan memperbarui PDF dengan menulis manual terpisah yang dapat menyimpang dari Markdown.

Cetak PDF pada A4 portrait dengan skala 100% / Actual size, satu halaman per lembar. Header/footer dan nomor sudah berada di PDF. Screenshot tinggi dibagi pada batas panel; file screenshot sumber tetap utuh. Untuk membaca detail kecil gunakan zoom PDF atau buka PNG ukuran asli pada buku browser.

HTML adalah hasil generate; edit Markdown lalu build ulang supaya sumber konsisten. Untuk membaca source Markdown, gunakan preview editor/repository. Link ke kode memakai path repository yang relatif terhadap folder manual.

Batas verifikasi dan catatan rilis

Capture adalah bukti tampilan dan pemeriksaan route baca. Ia bukan pengganti test otorisasi semua mutasi, test provider nyata, test restore, atau sertifikasi performa. Saat rilis, isi catatan ringkas: perubahan perilaku, role terdampak, bab/gambar yang diganti, tanggal, hasil command aktual, batas uji dan next step.

Contoh: “Pencarian/filter export diperbarui; bab 05 dan gambar export disesuaikan; check dokumen lulus; unduh XLSX diuji pada fixture; provider kirim tidak disentuh.” Jangan menulis hasil yang tidak benar-benar dijalankan.

Cakupan, sumber, dan bukti verifikasi

Baseline manual: 19 Oktober 2026, implementasi worktree termasuk perubahan yang belum di-commit. Manual tidak menjadi spesifikasi yang memperluas hak akses/fitur. Semua gambar browser memakai fixture sintetis di database terpisah.

Versi cetak tersedia sebagai modul PDF A4, dibangun dari Markdown dan screenshot yang sama. Susunan halaman PDF, cover, daftar isi dan caption merupakan presentasi dokumentasi, bukan perubahan fitur aplikasi.

Halaman dan screenshot

Nama di atas menunjuk PNG pada folder screenshots. Metadata aktual berada di manifest capture.

Sumber implementasi utama

UI pada resources/js/pages dan komponen Experience/Settings ikut diperiksa untuk nama kontrol, status fitur, dan pemetaan data yang benar-benar ditampilkan.

Perbedaan target dan implementasi yang harus diketahui

Perbedaan di sini tidak mengubah authority PRD/system-rules. Keputusan mengubah aturan produk harus ditulis pada pemilik topiknya dan ditinjau, bukan diselesaikan diam-diam oleh panduan pengguna.

Apa yang dibuktikan capture

Capture memuat login lima role, render halaman operasional dan Settings yang tercakup, submit form publik sintetis sampai thank-you, serta 28 observasi status route baca untuk empat role selain Super Admin (sources, review, General, users, create segment, create campaign, create Experience). Status yang diharapkan dibandingkan dengan permission kode; 403/404 juga diambil sebagai gambar.

Fixture committed dibentuk memakai action staging dan job import nyata pada database demo. Form memakai action submission yang sama dengan aplikasi. Tidak ada data pelanggan asli, nomor penerima nyata, API key atau password disertakan. Input readonly konektor dimask pada capture, termasuk URL webhook.

Capture tidak menguji pengiriman Qiscus/SMTP/OpenAI/Ollama nyata, pemasangan update host, backup/restore nyata, semua mutasi per role, atau performance produksi. Keberadaan test di repository bukan klaim test tersebut telah dijalankan ulang dalam sesi manual. Hasil capture terakhir dan pemeriksaan dokumen dicatat di docs/log.md.