Mode Offline & Sinkronisasi Data

Gambaran Umum

Di dunia ritel fisik yang dinamis dan tak kenal ampun, koneksi internet seringkali menjadi musuh terbesar yang tak kasat mata. Kabel optik di tiang luar bisa saja terputus karena kecelakaan, penyedia layanan internet (ISP) bisa mengalami gangguan masal, atau cuaca buruk bisa melumpuhkan sinyal seluler seketika. Namun, di dalam toko Anda, pelanggan yang sedang mengantre memegang barang dan dompet tidak mempedulikan masalah teknis server. Mereka hanya ingin membayar dan segera pergi. Kasir yang berhenti melayani karena alasan “Sistem Sedang Offline” adalah malapetaka bisnis yang dapat menghilangkan omzet jutaan rupiah dan menghancurkan reputasi toko dalam sekejap.

Menjawab tantangan mematikan ini, Temuya POS dibekali dengan fitur ketahanan yang luar biasa: Mode Offline (Luring) Tingkat Lanjut. Fitur ini bukanlah sekadar pesan peringatan yang menenangkan layar, melainkan sebuah perubahan wujud (transformasi) arsitektural secara instan yang terjadi di belakang layar tanpa disadari oleh kasir. Saat denyut nadi koneksi internet terputus, aplikasi tidak akan pernah membeku (freeze). Ia segera memindahkan otak operasinya dari server cloud yang jauh kembali ke dalam rahim browser perangkat lokal itu sendiri.

Melalui file pengendali offlineStorage.ts dan hook observasi pergerakan jaringan useOfflineMode.tsx, Temuya POS memanfaatkan teknologi basis data internal peramban (IndexedDB) sebagai bunker penyimpanan darurat. Katalog harga produk yang telah diunduh sebelumnya dibekukan di memori, dan setiap klik transaksi penjualan mulai ditelan ke dalam antrean (queue) brankas lokal. Kasir dapat terus memindai barcode, mencetak struk termal, membuka laci uang logam, dan menyerahkan barang kepada pembeli seolah-olah dunia digital baik-baik saja. Lalu, di kemudian waktu, begitu kabel internet tersambung dan ikon WiFi menyala kembali, aplikasi Temuya POS akan dengan gesit melakukan “Sinkronisasi Balas Dendam”—membongkar celengan antrean lokal dan membanjiri server dengan seluruh data transaksi luring tersebut dalam satu aliran rapi tanpa cacat.

Skenario Bisnis Nyata

Kisah tentang ketangguhan ini dapat ditemukan di “Minimarket Segar Abadi”, sebuah swalayan independen 24 jam yang terletak agak terpencil di jalur lintas provinsi. Suatu malam di tengah badai hujan yang sangat deras, petir menyambar gardu distribusi komunikasi di kecamatan tersebut, membuat koneksi internet kabel utama di swalayan terputus total. Sinyal telepon seluler pun turun menjadi sebatas 2G yang sama sekali tidak dapat memuat lalu lintas data modern. Padahal, pada jam tersebut, puluhan pelintas antar kota dan sopir truk sedang berdesakan di swalayan tersebut untuk membeli kopi panas, camilan, dan jas hujan plastik darurat.

Di minimarket tetangga yang menggunakan sistem kasir berbasis cloud kuno (legacy), para staf terpaksa menghentikan layanan, mencatat penjualan dengan pensil di atas buku tulis lusuh—sebuah kekacauan yang akan berujung pada stok barang yang berantakan besok paginya. Namun, kasir Minimarket Segar Abadi, Budi, tidak panik. Di sudut atas layar sentuh aplikasi Temuya POS-nya, indikator hijau ceria berubah menjadi label oranye berkedip dengan tulisan “Mode Offline Aktif - 0 Transaksi Tersimpan”. Budi tersenyum dan terus memindai kaleng kopi dan jas hujan pelanggan tanpa hambatan kecepatan sedikitpun. Struk kertas tetap tercetak keluar dari mesin printer dengan bunyi berdesis yang menenangkan.

Tiga jam kemudian, antrean indikator di layar Budi telah menunjukkan angka “125 Transaksi Tersimpan”. Sekitar pukul dua pagi, hujan mereda dan sinyal internet menyala kembali. Lampu indikator oranye di aplikasi Temuya berubah menjadi animasi berputar pelan dengan status “Sinkronisasi…”. Dalam kurun waktu kurang dari empat puluh detik, indikator tersebut kembali hijau cerah. Sebanyak 125 transaksi senilai jutaan rupiah telah mengalir deras ke server pusat Temuya tanpa ada satupun pemotongan stok yang tertukar atau pencatatan Rupiah yang lenyap. Budi pulang shift pagi harinya tanpa harus melakukan entri ulang data melelahkan, dan manajer toko sama sekali tidak tahu bahwa toko mereka baru saja selamat dari krisis operasional.

Alur Kerja Transisi Jaringan

Diagram State Transition (Transisi Keadaan) dan bagan Sinkronisasi di bawah ini memaparkan bagaimana Temuya POS mendeteksi perubahan alam jaringan di sekitarnya dan bereaksi seperti organisme hidup yang mengubah metode pernafasannya.

stateDiagram-v2
    [*] --> OnlineState
    
    state OnlineState {
        direction LR
        OnlineTx: Transaksi Baru
        OnlineTx --> HonoBackend: Kirim via HTTP API
        HonoBackend --> D1Server: Simpan di D1 Database
    }
    
    OnlineState --> OfflineState: Offline Event / Ping Gagal
    
    state OfflineState {
        direction LR
        OfflineTx: Transaksi Baru
        OfflineTx --> IndexedDB: Simpan ke IndexedDB (offline_queue)
        IndexedDB --> Timestamp: Beri Stempel Waktu & UUID
    }
    
    OfflineState --> SyncingState: Online Event
    
    state SyncingState {
        direction TB
        FetchQueue: Ambil Data dari IndexedDB
        SendBatch: Kirim Batch Data ke Hono API
        ValidateServer: Validasi Server & Cek Konflik
        
        FetchQueue --> SendBatch
        SendBatch --> ValidateServer
        ValidateServer --> ClearLocal: Sukses
        ValidateServer --> RetryQueue: Gagal
    }
    
    SyncingState --> OnlineState: Antrean Sinkronisasi Kosong

Teknologi & Infrastruktur (Penopang Offline)

Fitur luar biasa ini bukanlah keajaiban, melainkan rekayasa perangkat lunak cermat yang menggabungkan kemampuan terbaru standar peramban web modern (HTML5) dengan logika state management React.

Komponen Teknis	Teknologi Inti yang Digunakan	Penjelasan Fungsional di Latar Belakang
Deteksi Kondisi Jaringan	navigator.onLine & DOM Event Listeners	useOfflineMode.tsx secara diam-diam memonitor event JavaScript standar (window.addEventListener('online' / 'offline')) untuk merasakan putusnya nadi koneksi di tingkat sistem operasi perangkat.
Gudang Data Transaksi Luring	IndexedDB API	Berbeda dengan LocalStorage yang ringkih dan dibatasi 5MB, IndexedDB adalah basis data NoSQL internal browser berskala besar (bisa menyimpan ratusan Megabyte) yang sempurna untuk menyimpan ribuan objek transaksi berat yang tertahan.
Cache Katalog Produk (Penyedia Harga)	Service Workers & Cache API (PWA)	Sebuah jaring pengaman yang mengunduh (preload) seluruh daftar produk dan harga terakhir ke memori browser. Tanpa fitur ini, kasir tidak akan tahu harga barang yang dipindai saat offline.
Identitas Unik Anti-Bentrok	UUID v4 (Universally Unique Identifier)	Saat transaksi dibuat luring, ia tidak diberi ID berurut (seperti Nomor 1, Nomor 2). Ia diberi string acak yang sangat panjang. Ini mencegah kekacauan (konflik ID utama) jika ada tiga kasir berbeda yang luring secara bersamaan dan mencoba menyinkronkan data mereka nanti.
Algoritma Pengiriman Balik	Sequential Promise Queue & Backoff	Saat syncing, transaksi tidak dikirim sekaligus seperti meriam (yang bisa membuat server kelebihan beban HTTP 429), melainkan dikirim satu per satu secara berurutan dan tenang untuk memastikan integritas pemotongan inventaris.

Keterkaitan dengan Fitur Lain

Mode Luring sangat bergantung pada dan mempengaruhi siklus hidup fitur-fitur krusial lainnya di dalam ekosistem kasir:

1. Integrasi Thermal Printer: Fitur cetak setruk (via thermalPrinter.ts Web Serial/Bluetooth) adalah pahlawan tanpa tanda jasa saat internet mati. Karena ia bekerja di perangkat keras murni tanpa perlu verifikasi server, pelanggan tetap menerima bukti bayar kertas yang valid meski di pedalaman tanpa sinyal.
2. API Reference & Modul Inventori: Ketika proses sinkronisasi (sync) menembakkan data transaksi offline kembali ke backend Hono, API Inventori akan melakukan proses catch-up (kejar ketertinggalan), yakni mengkalkulasi ulang pengurangan stok fisik barang berdasarkan semua stempel waktu masa lalu (retroaktif) di transaksi luring tersebut.
3. Laporan Shift & Kasir: Sistem akan secara otomatis memblokir kemampuan kasir untuk melakukan “Tutup Shift Akhir Hari (End of Day)” jika aplikasi mendeteksi masih ada sisa antrean transaksi luring (offline) yang belum tersinkronisasi ke pusat, mencegah terjadinya ketidakseimbangan (selisih) laporan keuangan tunai antar cabang.

Hal Penting yang Perlu Diketahui

Kebebasan beroperasi tanpa internet juga memikul beberapa kompromi tak terhindarkan. Pemilik toko dan staf manajerial mutlak harus mengerti batasan-batasan dan pedoman operasi kritis berikut ini:

• Peringatan Browser Cache Clear (Pembersihan History): SANGAT FATAL! Seluruh transaksi mode luring disimpan sementara di dalam “ruang memori abu-abu” browser (IndexedDB). Jika seorang karyawan kasir iseng melakukan pembersihan riwayat peramban (Clear Browsing Data atau Clear Cache & Cookies) saat masih ada antrean offline yang belum tersinkronisasi, seluruh data transaksi tersebut akan musnah dan lenyap selamanya tanpa bisa dipulihkan. Pasang peringatan ini besar-besaran di meja mesin kasir Anda.
• Fitur Apa Saja yang Mati Saat Luring: Mode Offline hanya difokuskan untuk “Menyelamatkan Proses Penjualan di Meja Kasir (Check-out)”. Seluruh operasional manajemen berat lainnya secara otomatis akan membeku dan menampilkan halaman peringatan abu-abu. Staf Anda TIDAK akan bisa melakukan: Penambahan Produk Baru, Perubahan Harga Barang, Pembuatan Akun Karyawan Baru, Menampilkan Laporan Analitik Keuangan, atau Menerima Pembayaran E-Wallet/QRIS dinamis yang mengharuskan kontak ke server perbankan. Semuanya murni transaksi Uang Tunai atau Kartu Mesin EDC Fisik mandiri.
• Waspadai Risiko “Stok Minus / Overselling” (Bentrok Data): Jika stok sebungkus kopi tinggal 1 unit di server, lalu tiba-tiba toko luring (offline), kasir masih bisa menjual kopi tersebut. Namun masalah timbul jika di saat yang sama (secara online di toko E-Commerce) seseorang juga membeli produk itu. Saat aplikasi POS kembali online dan melakukan sinkronisasi, sistem akan dipaksa mengurangi stok, menyebabkan angka sisa stok produk (inventory stock) di sistem Temuya menjadi Minus Satu (-1). Manajer gudang harus melakukan rekonsiliasi manual lewat fitur “Penyesuaian Inventaris (Inventory Adjustment)” di pagi hari untuk merapikan selisih tak terhindarkan ini.
• Gunakan Mode Penyamaran (Incognito/Private) Dengan Risiko Anda Sendiri: Perlu ditekankan berkali-kali bahwa jika Anda menjalankan aplikasi POS Temuya di jendela Incognito / Jendela Pribadi peramban, browser berhak membuang semua data (termasuk penyimpanan lokal IndexedDB) secara kejam seketika aplikasi ditutup (Close Tab). Menggunakan sistem ini di mode penyamaran ibarat berjalan di atas tali sirkus tanpa jaring pengaman, jauhi praktik ini.
• Jangan Matikan Komputer Jika Ada Sisa Antrean: Pada saat jam toko tutup di malam hari, kasir harus memastikan bahwa lampu indikator internet sudah hijau dan pesan tulisan “Antrean Sinkronisasi (0)” muncul sebelum mereka memutus daya (shutdown/mencabut saklar listrik) komputer terminal POS utama tersebut. Mematikan mesin saat aplikasi sedang sibuk mensinkronisasikan antrean dapat menyebabkan dokumen digital (JSON payload) rusak di tengah jalan (corrupt).