Sinkronisasi & Offline
Antrian Sync & Retry
Bagaimana mutasi offline diantrikan dan dikirim ulang otomatis saat koneksi tersedia, serta apa yang terjadi bila pengiriman gagal berulang kali.
Apa itu Antrian Sync?
Setiap kali Anda membuat pesanan, mengubah status, atau mencatat pembayaran saat offline (atau bahkan saat online — karena data selalu disimpan lokal dahulu), operasi tersebut ditambahkan ke antrian sinkronisasi (sync queue) di perangkat.
Antrian ini menyimpan daftar operasi yang belum berhasil dikirim ke server, lengkap dengan:
- Jenis entitas (pesanan, pembayaran, dll.)
- Data lengkap operasinya
- Stempel waktu HLC (Hybrid Logical Clock) untuk menjaga urutan yang konsisten
- Jumlah percobaan pengiriman
Antrian ini tersimpan permanen di database lokal — tidak akan hilang meski aplikasi ditutup atau perangkat di-restart.
Alur Pengiriman Antrian
Saat koneksi tersedia, sync engine memproses antrian dengan urutan berikut:
- Ambil semua operasi yang belum terkirim dari database lokal.
- Kirim ke server dalam satu batch melalui
POST /pos/sync/batch— lebih efisien daripada kirim satu per satu. - Server membalas dengan status tiap operasi: berhasil atau ditolak (dengan kode alasan).
- Operasi yang berhasil ditandai selesai (synced) dan tidak akan dikirim ulang.
- Operasi yang gagal dicatat jumlah percobaannya dan akan dicoba lagi pada sinkronisasi berikutnya.
Tips: Anda tidak perlu menunggu antrian kosong sebelum melanjutkan penjualan. Antrian berjalan di latar belakang secara paralel dengan aktivitas kasir.
Mekanisme Retry (Coba Ulang)
Bila pengiriman gagal (koneksi terputus di tengah proses, atau server mengembalikan error sementara), operasi tidak langsung dianggap gagal permanen. POS mencoba ulang secara otomatis:
| Percobaan ke- | Perilaku |
|---|---|
| 1–3 | Dicoba ulang pada sinkronisasi berikutnya (setiap 5 menit, atau segera saat koneksi pulih) |
| 4 (maks) | Ditandai gagal permanen dan dicatat dengan kode kesalahan dari server |
Batas maksimum percobaan adalah 3 kali setelah percobaan awal. Setelah itu operasi dihentikan untuk mencegah loop tak terbatas.
Apa yang Terjadi Bila Gagal Permanen?
Bila sebuah operasi gagal melewati batas retry, kemungkinan penyebabnya adalah:
- Konflik data — misalnya pesanan yang sama sudah dibuat dari perangkat lain.
- Data tidak valid — item menu sudah dihapus dari server, atau meja tidak lagi tersedia.
- Otorisasi — token kedaluwarsa, perangkat dicabut aksesnya.
Dalam kondisi ini:
- Kasir tidak perlu melakukan apapun secara manual — data pesanan tetap tersimpan lokal dan bisa diakses.
- Untuk kasus yang memerlukan tindak lanjut (misalnya pembayaran yang terdeteksi duplikat), hubungi manajer atau tim dukungan teknis.
- Bila perlu, gunakan Sinkron Manual untuk memicu ulang proses sinkronisasi dan melihat apakah error sudah teratasi.
Perhatian: Bila perangkat terlalu lama offline (melewati masa validasi token), aplikasi akan meminta login ulang saat koneksi tersedia. Setelah login, antrian yang tersimpan akan dikirim otomatis.
Batch vs. Single Push
POS menggunakan mekanisme batch (kirim banyak sekaligus) sebagai cara utama — lebih cepat dan efisien. Jika batch gagal (misalnya server batch tidak merespons), POS otomatis beralih ke fallback single push — mengirim satu per satu secara berurutan. Hasilnya sama, hanya sedikit lebih lambat.
Konflik Antar Perangkat
Bila dua perangkat mengedit data yang sama secara bersamaan (misalnya dua kasir mengedit pesanan yang sama saat offline), konflik diselesaikan berdasarkan HLC timestamp:
- Pesanan lokal yang belum terkirim (unsynced) tidak akan ditimpa oleh data dari server — data lokal dipertahankan hingga berhasil dikirim.
- Pesanan lokal yang sudah terkirim (synced) akan diperbarui oleh versi server bila ada perubahan dari perangkat lain.
Pendekatan ini memastikan tidak ada data yang hilang di tengah kondisi jaringan tidak stabil.
Untuk memahami mekanisme stempel waktu HLC yang menjaga urutan antar perangkat, baca artikel Konsistensi Data (HLC).