title: “Offline Mode” description: “Sistem offline-first untuk POS dan inventory dengan auto-sync, conflict resolution, dan data persistence lokal.”

Offline Mode

Offline Mode adalah kemampuan SNISHOP ERP untuk tetap berfungsi meskipun tidak ada koneksi internet. Fitur ini menggunakan arsitektur offline-first — data disimpan secara lokal di perangkat melalui IndexedDB dan otomatis tersinkronisasi ke server ketika koneksi kembali tersedia. Sistem ini dirancang untuk menjamin zero data loss pada kondisi jaringan tidak stabil, menjaga integritas transaksi keuangan, dan memastikan konsistensi data inventory melalui mekanisme conflict resolution yang deterministik.

Kasus Penggunaan Kritis

Fitur ini sangat kritis untuk skenario berikut:

Skenario	Deskripsi	Dampak jika Tidak Ada Offline Mode
Kasir toko	Jaringan intermittently di area komersial padat	Transaksi gagal, antrian pelanggan menumpuk
Staf gudang	Bekerja di basement, gudang tertutup, area minim sinyal	Stock movement tidak tercatat, selisih inventaris
Sales lapangan	Kunjungan ke area dengan coverage buruk	Order tidak masuk, kehilangan penjualan
Backup server	Server pusat mengalami downtime sementara	Operasional berhenti total
Event/bazaar	Lokasi sementara tanpa infrastruktur jaringan stabil	Tidak bisa bertransaksi selama acara
Multi-cabang	Sinkronisasi antar cabang tertunda	Data stok tidak akurat antar outlet

Arsitektur Offline-First

Diagram Arsitektur Umum

Lapisan Data Persistence

Komponen Sistem

1. Local Storage Engine

Data disimpan menggunakan IndexedDB di browser dengan struktur object store terorganisasi:

Komponen	Fungsi	Entitas Terkait	Kapasitas
Transaction Store	Menyimpan transaksi POS offline	`CompanyPOSTransaction`, `POSTransaction`	Unlimited (tergantung storage)
Inventory Store	Data stok & movement lokal	`Inventory`, `CompanyPOSInventory`	Mirror dari server
Product Store	Katalog produk & harga	`CompanyPOSProduct`, `CompanyPOSCategory`	Mirror dari server
Stock Movement Store	Pergerakan stok lokal	`StockMovement`	Unlimited
Transfer Store	Dokumen transfer stok	`StockTransfer`	Unlimited
Opname Store	Data stock opname	`StockOpname`	Unlimited
Customer Store	Data pelanggan/member	`POSMember`	Mirror dari server
Alert Store	Alert stok lokal	`StockAlert`	Mirror dari server
Warehouse Store	Data lokasi gudang	`WarehouseLocation`	Mirror dari server
Sync Queue	Antrian data yang belum tersync	Semua entitas	Unlimited
Config Store	Konfigurasi & settings	`CompanyPOSSettings`	Kecil

Storage Limits per Browser:

Browser	Default Limit	Kebijakan Eviction	Catatan
Chrome	60% of disk	Auto-evict LRU (Least Recently Used)	Origin-based quota
Firefox	50% of disk	Prompt jika melebihi limit	Persistent storage recommended
Safari	1 GB	Hard limit, no prompt	Gunakan `navigator.storage.persist()`
Edge	60% of disk	Same as Chrome (Chromium-based)	Same quota policy

2. Connection Detector

Sistem deteksi koneksi multi-layer yang cerdas:

Metode	Deskripsi	Akurasi	Latency
Navigator.onLine	Cek status koneksi browser	Basic	Instant
Heartbeat Ping	Ping server setiap 30 detik	High	~30s detection
API Response	Deteksi dari HTTP response code	Definitive	On-request
Event Listener	Listen `online`/`offline` DOM events	Instant	Real-time
WebSocket Health	Monitor koneksi WebSocket aktif	Very High	Real-time

Status Indikator Visual:

Status	Ikon	Warna	Deskripsi	Tindakan User
Online	☁️✅	Hijau	Terkoneksi ke server	Operasional normal
Syncing	🔄	Biru	Sedang sinkronisasi data	Tunggu hingga selesai
Offline	☁️❌	Merah	Tidak ada koneksi	Lanjut bekerja, data di-queue
Partial	⚠️	Kuning	Koneksi tidak stabil	Hati-hati, mungkin ada delay sync
Conflict	🔀	Oranye	Ada konflik data	Review dan resolve manual

3. Sync Queue & Engine

Antrian sinkronisasi yang mengelola data pending dengan mekanisme retry dan prioritas:

Field	Tipe	Deskripsi
Queue ID	`string`	Identifier unik untuk setiap item (UUID v4)
Entity Type	`string`	Jenis data: `CompanyPOSTransaction`, `StockMovement`, `StockTransfer`, `StockOpname`, dll
Operation	`string`	Operasi: `create`, `update`, `delete`
Payload	`object`	Data lengkap yang akan di-sync
Created At	`date-time`	Kapan item ditambahkan ke queue
Retry Count	`number`	Berapa kali sudah dicoba sync
Max Retries	`number`	Batas percobaan (default: 5)
Status	`enum`	`pending`, `syncing`, `success`, `failed`, `conflict`
Error Message	`string`	Pesan error jika gagal
Priority	`enum`	`high`, `normal`, `low`
Idempotency Key	`string`	Kunci idempotensi untuk mencegah duplikasi
Depends On	`string[]`	Queue ID dependency (order guarantee)

Urutan Prioritas Sync:

Prioritas	Jenis Data	Alasan	SLA
High	`CompanyPOSTransaction` (payment_method: cash/card/ewallet)	Mempengaruhi keuangan langsung	Immediate
High	`StockMovement` (movement_type: out, sale)	Stok berkurang, perlu sinkron segera	Immediate
Normal	`StockMovement` (movement_type: in, adjustment)	Stok bertambah, penting tapi tidak urgent	< 5 menit
Normal	`StockTransfer`	Perpindahan antar lokasi	< 5 menit
Normal	`StockOpname`	Hasil penghitungan fisik	< 10 menit
Low	`StockAlert` (status: acknowledged/dismissed)	Status alert non-kritis	< 30 menit
Low	`POSMember` (notes, discount updates)	Data pelengkap	Best effort

4. Conflict Resolution

Ketika data diubah di kedua sisi (offline & server) selama periode offline, sistem menerapkan strategi resolusi konflik berdasarkan jenis entitas dan konteks bisnis:

Strategi	Deskripsi	Kapan Digunakan	Entitas Terkait
Server Wins	Data server yang dipakai sebagai sumber kebenaran	Stok (`Inventory.quantity`), harga (`CompanyPOSProduct.price`)	`Inventory`, `CompanyPOSProduct`
Client Wins	Data lokal yang dipakai	Catatan personal, draft, preferensi user	`StockOpname.notes`, `StockMovement.notes`
Append/Merge	Gabungkan kedua perubahan (append entries)	Item independent dalam order, movement entries	`CompanyPOSTransaction.items`, `StockMovement`
Idempotency Check	Skip jika sudah ada (berdasarkan idempotency key)	Operasi dengan idempotency key	`StockMovement`, `StockTransfer`
Manual Review	User memilih mana yang dipakai	Konflik kompleks yang tidak bisa di-resolve otomatis	Semua entitas dengan konflik ganda

Flow Conflict Resolution:

Fitur Utama

Transaksi POS Offline

Transaksi POS (CompanyPOSTransaction) adalah entitas inti yang mendukung operasi offline penuh:

Kemampuan	Status Offline	Setelah Sync	Catatan Teknis
Buat transaksi baru	✅	Data terkirim ke server	Disimpan di IndexedDB, queue otomatis
Cetak receipt	✅	Tidak perlu sync	Template dari `CompanyPOSSettings.receipt_settings`
Hitung kembalian	✅	Kalkulasi lokal	`change_amount` dihitung di client
Scan barcode	✅	Lookup produk lokal	Cari di `CompanyPOSProduct` cache lokal
Apply diskon	✅	Validasi setelah sync	`discount_percentage` & `discount_amount`
Split payment	✅	Data terkirim setelah sync	Array `payments` dengan multi-tender
Lookup member	✅	Sync points setelah reconnect	Data `POSMember` dari cache lokal
Hitung poin	✅	Update `points_earned`/`points_used`	Kalkulasi lokal, validasi server
Cetak laporan shift	⚠️	Data terakhir yang di-sync	Snapshot last-synced data
Multi-channel pricing	⚠️	Harga terakhir dari server	`channel_pricing` cache lokal

Payment Methods yang Didukung Offline:

Metode	Enum Value	Offline Support	Catatan
Tunai	`cash`	✅ Penuh	Kalkulasi kembalian lokal
Kartu	`card`	✅ Penuh	Input manual, verifikasi nanti
Transfer	`transfer`	✅ Penuh	`payment_reference` disimpan lokal
E-Wallet	`ewallet`	✅ Penuh	Input manual
QRIS	`qris`	✅ Penuh	`payment_reference` disimpan lokal
Saldo Member	`saldo`	⚠️ Terbatas	Validasi saldo setelah sync
Mayar	`mayar`	❌ Butuh online	Gateway verification required
Midtrans	`midtrans`	❌ Butuh online	Payment gateway
Tripay	`tripay`	❌ Butuh online	Payment gateway
Stripe	`stripe`	❌ Butuh online	Payment gateway
PayPal	`paypal`	❌ Butuh online	Payment gateway

Inventory Offline

Operasi inventory yang didukung dalam mode offline melibatkan beberapa entitas:

Kemampuan	Entitas Terkait	Status Offline	Setelah Sync
Stock adjustment	`StockMovement` (type: `adjustment`)	✅	Movement tercatat di server
Stock opname input	`StockOpname`	✅	Hasil opname terkirim
Transfer stok	`StockTransfer`	✅	Movement terkirim, status `in_transit`
Terima barang	`StockMovement` (type: `in`)	✅	Movement tercatat
Barcode scan	`CompanyPOSProduct`	✅	Lookup produk lokal
Lihat stok real-time	`Inventory`	⚠️	Data terakhir sync (bisa stale)
Catat barang rusak	`StockMovement` (type: `damaged`)	✅	Movement tercatat
Hold stok untuk QC	`StockMovement` (type: `hold`)	✅	Informasional, tidak ubah on-hand
Release hold	`StockMovement` (type: `hold_release`)	✅	Informasional

Entity Relationship Diagram

Berikut adalah diagram relasi entitas yang terlibat dalam sistem Offline Mode. Setiap entitas memiliki peran penting dalam memastikan data tetap konsisten antara mode offline dan sinkronisasi ke server.

Entity Schema Reference

CompanyPOSTransaction

Entitas utama untuk transaksi POS yang dapat dibuat saat mode offline dan di-sinkronisasi ketika koneksi tersedia.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik transaksi
`location_id`	string	Tidak	ID lokasi gudang atau toko tempat transaksi terjadi
`location_name`	string	Tidak	Nama lokasi gudang atau toko
`transaction_number`	string	Ya	Nomor transaksi unik sebagai identifier bisnis
`invoice_number`	string	Tidak	Nomor invoice yang dicetak untuk pelanggan
`transaction_date`	datetime	Tidak	Tanggal dan waktu transaksi dilakukan
`items`	array	Ya	Daftar produk yang dibeli dalam transaksi
`subtotal`	number	Tidak	Subtotal total sebelum diskon dan pajak diterapkan
`discount_amount`	number	Tidak	Nominal diskon dalam rupiah (default: 0)
`discount_percentage`	number	Tidak	Persentase diskon yang diterapkan (default: 0)
`tax_amount`	number	Tidak	PPN atas transaksi; mode inclusive sudah termasuk, exclusive tambahan
`total`	number	Ya	Total akhir transaksi yang harus dibayar
`total_amount`	number	Tidak	Total akhir (alias dari total)
`payment_method`	string	Tidak	Metode pembayaran: cash, card, transfer, ewallet, qris, saldo, mayar, debt, manual_transfer, midtrans, tripay, stripe, paypal
`payment_amount`	number	Tidak	Jumlah uang yang dibayarkan oleh pelanggan
`payments`	array	Tidak	Detail pembayaran multi-tender untuk split payment
`payment_status`	string	Tidak	Status pembayaran: pending, pending_verification, partially_paid, paid, failed, refunded, rejected
`paid_amount`	number	Tidak	Nominal pembayaran aktual yang telah diverifikasi (default: 0)
`remaining_amount`	number	Tidak	Sisa kekurangan tagihan yang belum dibayar (default: 0)
`excess_amount`	number	Tidak	Kelebihan nominal transfer dari pelanggan (default: 0)
`change_amount`	number	Tidak	Kembalian yang diberikan kepada pelanggan (default: 0)
`payment_reference`	string	Tidak	Nomor referensi bukti transfer atau QRIS untuk pembayaran non-tunai
`payment_verified_by`	string	Tidak	Nama pengguna yang memverifikasi pembayaran non-tunai
`payment_verified_at`	datetime	Tidak	Waktu verifikasi pembayaran non-tunai
`customer_id`	string	Tidak	ID member atau pelanggan jika terdaftar
`customer_name`	string	Tidak	Nama pelanggan yang melakukan transaksi
`customer_phone`	string	Tidak	Nomor telepon pelanggan
`customer_address`	string	Tidak	Alamat lengkap pelanggan
`points_earned`	number	Tidak	Poin loyalitas yang didapat dari transaksi ini (default: 0)
`points_used`	number	Tidak	Poin loyalitas yang dipakai untuk membayar (default: 0)
`cashier_id`	string	Tidak	ID karyawan kasir yang memproses transaksi
`cashier_name`	string	Tidak	Nama kasir yang memproses transaksi
`assigned_to_id`	string	Tidak	ID pengguna yang ditugaskan menangani order
`assigned_to_name`	string	Tidak	Nama pengguna yang ditugaskan menangani order
`notes`	string	Tidak	Catatan tambahan terkait transaksi
`source`	string	Tidak	Sumber transaksi: pos, online_catalog, website, marketplace, landing_page, whatsapp, reseller, b2b, grab, social_media
`order_status`	string	Tidak	Status pesanan: pending, processing, shipped, delivered, completed, cancelled, rejected
`status`	string	Tidak	Status transaksi: pending, processing, shipped, delivered, completed, failed, refunded, cancelled
`tracking_number`	string	Tidak	Nomor resi pengiriman untuk order yang dikirim
`shipping_address`	string	Tidak	Alamat pengiriman untuk order online
`sales_channel`	string	Tidak	Sales channel ternormalisasi: offline_pos, offline, website, online_catalog, marketplace, landing_page, whatsapp, reseller, b2b, grab, social_media
`metadata`	object	Tidak	Data tambahan seperti informasi online order
`verified_at`	datetime	Tidak	Waktu transaksi diverifikasi
`verified_by`	string	Tidak	Pengguna yang memverifikasi transaksi
`processed_at`	datetime	Tidak	Waktu transaksi mulai diproses
`shipped_at`	datetime	Tidak	Waktu transaksi dikirim
`delivered_at`	datetime	Tidak	Waktu transaksi diterima pelanggan
`cancelled_at`	datetime	Tidak	Waktu transaksi dibatalkan

Inventory

Entitas inventory yang di-cache secara lokal saat offline dan di-sinkronisasi ketika koneksi tersedia.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik inventory
`product_id`	string	Ya	ID produk dari CompanyPOSProduct yang dilacak stoknya
`product_name`	string	Tidak	Nama produk untuk tampilan tanpa lookup
`product_sku`	string	Tidak	SKU produk untuk pencarian cepat
`category_key`	string	Tidak	Kunci kategori canonical produk
`category_name`	string	Tidak	Nama label kategori canonical
`variant_key`	string	Tidak	Kunci varian canonical produk
`variant_label`	string	Tidak	Label gabungan kategori dan varian untuk POS/inventory
`size_grams`	number	Tidak	Ukuran canonical produk dalam gram
`base_product_key`	string	Tidak	Kunci produk utama sebelum pemecahan kategori/varian
`location_id`	string	Ya	ID lokasi gudang atau toko tempat stok disimpan
`location_name`	string	Tidak	Nama lokasi gudang atau toko
`variant_id`	string	Tidak	ID varian produk jika tersedia
`variant_name`	string	Tidak	Nama varian seperti Merah-L, Biru-XL
`variant_attributes`	object	Tidak	Atribut varian: color, size, material
`quantity`	number	Tidak	Jumlah stok saat ini (default: 0)
`reserved_quantity`	number	Tidak	Stok yang sudah direserve untuk order yang belum selesai (default: 0)
`available_quantity`	number	Tidak	Stok tersedia: quantity - reserved_quantity - blocked_quantity (default: 0)
`in_transit_quantity`	number	Tidak	Kuantitas stok yang sedang dalam perjalanan transfer (default: 0)
`blocked_quantity`	number	Tidak	Kuantitas stok ditahan untuk QC, karantina, atau recall (default: 0)
`min_stock`	number	Tidak	Minimum stok untuk memicu alert (default: 5)
`max_stock`	number	Tidak	Maksimum kapasitas stok (default: 1000)
`reorder_point`	number	Tidak	Titik reorder otomatis untuk replenishment (default: 10)
`reorder_quantity`	number	Tidak	Jumlah reorder saat titik tercapai (default: 50)
`auto_reorder`	boolean	Tidak	Auto create purchase order saat low stock (default: false)
`unit_cost`	number	Tidak	Harga modal per unit untuk kalkulasi HPP (default: 0)
`total_value`	number	Tidak	Total nilai stok: quantity × unit_cost (default: 0)
`last_stock_in`	datetime	Tidak	Waktu terakhir stok masuk ke lokasi ini
`last_production_release_lot_id`	string	Tidak	Marker artefak rilis produksi terakhir untuk verifikasi replay idempotent
`last_stock_out`	datetime	Tidak	Waktu terakhir stok keluar dari lokasi ini
`stock_status`	string	Tidak	Status stok: in_stock, low_stock, out_of_stock, overstock
`channel_allocations`	object	Tidak	Alokasi stok per channel: offline, online, marketplace, b2b
`geographic_zones`	object	Tidak	Distribusi geografis: same_city, other_cities, export
`alert_sent`	boolean	Tidak	Apakah alert stok sudah dikirim (default: false)
`notes`	string	Tidak	Catatan tambahan terkait inventory
`rack`	string	Tidak	Lokasi rak penyimpanan seperti A1, B2
`metadata`	object	Tidak	Metadata teknis non-otoritatif seperti correlation/idempotency key

StockMovement

Entitas pergerakan stok yang dicatat saat offline dan di-sinkronisasi dengan validasi idempotency key.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik pergerakan stok
`inventory_id`	string	Ya	ID inventory yang mengalami perubahan stok
`product_id`	string	Tidak	ID produk yang bergerak
`product_sku`	string	Tidak	SKU produk untuk identifikasi cepat
`product_type`	string	Tidak	Tipe produk: finished_good, raw_material, dll
`identity_status`	string	Tidak	Status identitas: linked atau legacy_review
`source_material_id`	string	Tidak	ID material sumber jika applicable
`product_name`	string	Tidak	Nama produk untuk tampilan
`category_key`	string	Tidak	Kunci kategori canonical
`category_name`	string	Tidak	Nama label kategori
`variant_key`	string	Tidak	Kunci varian canonical
`variant_name`	string	Tidak	Nama label varian
`base_product_key`	string	Tidak	Kunci produk utama
`variant_label`	string	Tidak	Label gabungan kategori dan varian
`size_grams`	number	Tidak	Ukuran produk dalam gram
`location_id`	string	Tidak	ID lokasi gudang tempat pergerakan terjadi
`location_name`	string	Tidak	Nama lokasi gudang
`movement_type`	string	Ya	Tipe pergerakan: in, out, transfer, adjustment, return, damaged, hold, hold_release
`quantity`	number	Ya	Jumlah perubahan stok
`stock_before`	number	Tidak	Jumlah stok sebelum pergerakan
`stock_after`	number	Tidak	Jumlah stok setelah pergerakan
`reference_type`	string	Tidak	Sumber perubahan: purchase, sale, cashier_sale, production, raw_material_outbound, qc_release, transfer, adjustment, opname_adjustment, return, manual, distribution_shipment, quality_hold
`lot_id`	string	Tidak	ID Lot/Batch terkait untuk traceability
`lot_number`	string	Tidak	Nomor label Lot/Batch fisik
`reference_id`	string	Tidak	ID transaksi terkait seperti PO, SO, Transfer
`from_location_id`	string	Tidak	ID lokasi asal untuk transfer
`to_location_id`	string	Tidak	ID lokasi tujuan untuk transfer
`reason`	string	Tidak	Alasan perubahan stok
`override_reason`	string	Tidak	Alasan jika pilihan lot menyimpang dari FIFO standar
`allocation_strategy`	string	Tidak	Strategi alokasi: fifo, fefo, atau manual
`unit_cost`	number	Tidak	Harga modal per unit saat transaksi (default: 0)
`total_value`	number	Tidak	Nilai modal total: quantity × unit_cost (default: 0)
`sales_channel`	string	Tidak	Nama channel penjualan: Shopee, TikTok, WhatsApp, Indomaret, B2B
`channel_price_key`	string	Tidak	Key pricing channel dari CompanyPOSProduct.channel_pricing
`unit_price`	number	Tidak	Harga jual per unit untuk transaksi penjualan (default: 0)
`total_revenue`	number	Tidak	Pendapatan penjualan: quantity × unit_price (default: 0)
`total_cost`	number	Tidak	Total modal: quantity × unit_cost (default: 0)
`profit`	number	Tidak	Laba atau rugi: total_revenue - total_cost (default: 0)
`profit_margin`	number	Tidak	Margin laba persentase: profit / total_revenue × 100 (default: 0)
`performed_by`	string	Tidak	Email user yang melakukan pergerakan
`performed_by_name`	string	Tidak	Nama lengkap user yang melakukan pergerakan
`notes`	string	Tidak	Catatan tambahan terkait pergerakan
`idempotency_key`	string	Tidak	Kunci idempotensi untuk retry operasi yang aman
`created_by`	string	Tidak	ID aktor terautentikasi yang membuat record
`metadata`	object	Tidak	Metadata korelasi command untuk audit

StockOpname

Entitas sesi stock opname yang dapat diinput secara offline dan disubmit setelah sinkronisasi.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik sesi opname
`warehouse_id`	string	Tidak	Referensi ke WarehouseLocation tempat opname
`warehouse_name`	string	Tidak	Nama gudang tempat opname dilakukan
`opname_number`	string	Tidak	Nomor sesi opname yang unik
`opname_date`	date	Ya	Tanggal pelaksanaan stock opname
`status`	string	Tidak	Status sesi: draft, in_progress, counting, submitted, pending_approval, completed, approved, posted, rejected
`conducted_by_user_id`	string	Ya	ID pengguna yang melaksanakan opname
`conducted_by_name`	string	Tidak	Nama pengguna yang melaksanakan opname
`cutoff_at`	datetime	Tidak	Waktu pembekuan baseline stok sistem
`ledger_version`	string	Tidak	Penanda versi snapshot buku besar saat cutoff
`approved_by`	string	Tidak	Email atau ID approver yang menyetujui
`approved_at`	datetime	Tidak	Waktu persetujuan diberikan
`rejected_by`	string	Tidak	Email atau ID approver yang menolak
`rejected_at`	datetime	Tidak	Waktu penolakan diberikan
`rejection_reason`	string	Tidak	Alasan penolakan sesi stock opname
`items`	array	Tidak	Daftar item yang diopname dengan system_quantity vs physical_quantity
`total_items`	number	Tidak	Total item yang dihitung (default: 0)
`total_variance_items`	number	Tidak	Total item yang memiliki selisih (default: 0)
`total_variance_value`	number	Tidak	Total nilai rupiah selisih HPP (default: 0)
`adjustment_posted`	boolean	Tidak	Apakah penyesuaian sudah diposting ke inventory (default: false)
`finance_record_ids`	array	Tidak	ID FinancialRecord hasil posting selisih opname ke modul keuangan
`notes`	string	Tidak	Catatan tambahan sesi opname

StockTransfer

Entitas transfer stok antar lokasi yang dapat dibuat saat offline.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik transfer
`transfer_number`	string	Tidak	Nomor dokumen transfer unik (TRF-YYYYMMDD-XXXX)
`from_location_id`	string	Ya	ID lokasi gudang atau toko asal
`from_location_name`	string	Tidak	Nama lokasi asal
`to_location_id`	string	Ya	ID lokasi gudang atau toko tujuan
`to_location_name`	string	Tidak	Nama lokasi tujuan
`product_id`	string	Ya	ID produk CompanyPOSProduct yang ditransfer
`product_name`	string	Tidak	Nama produk yang ditransfer
`product_sku`	string	Tidak	SKU produk
`category_key`	string	Tidak	Kunci kategori canonical
`category_name`	string	Tidak	Nama label kategori
`variant_key`	string	Tidak	Kunci varian canonical
`variant_name`	string	Tidak	Nama label varian
`variant_label`	string	Tidak	Label gabungan kategori dan varian
`size_grams`	number	Tidak	Ukuran produk dalam gram
`base_product_key`	string	Tidak	Kunci produk utama
`lot_id`	string	Tidak	ID lot batch asal untuk traceability
`lot_number`	string	Tidak	Nomor label lot batch fisik
`quantity_sent`	number	Ya	Kuantitas yang dikirim dari lokasi asal
`quantity_received`	number	Tidak	Kuantitas riil yang diterima di lokasi tujuan (default: 0)
`discrepancy_quantity`	number	Tidak	Selisih kuantitas: quantity_sent - quantity_received (default: 0)
`discrepancy_reason`	string	Tidak	Alasan selisih jika barang rusak atau hilang di jalan
`transfer_mode`	string	Tidak	Mode transfer: in_transit (2-tahap) atau direct (instan)
`status`	string	Tidak	Status siklus hidup: draft, in_transit, completed, cancelled
`unit_cost`	number	Tidak	Harga modal atau HPP per unit produk (default: 0)
`total_value`	number	Tidak	Nilai total transfer: quantity_sent × unit_cost (default: 0)
`transfer_date`	string	Tidak	Tanggal transfer dalam format YYYY-MM-DD
`shipped_at`	datetime	Tidak	Waktu pengiriman berangkat
`shipped_by`	string	Tidak	Email atau identitas petugas yang mengirim
`received_at`	datetime	Tidak	Waktu barang diterima di tujuan
`received_by`	string	Tidak	Email atau identitas petugas yang menerima
`cancelled_at`	datetime	Tidak	Waktu transfer dibatalkan
`cancelled_by`	string	Tidak	Pengguna yang membatalkan transfer
`cancellation_reason`	string	Tidak	Alasan pembatalan transfer
`reason`	string	Tidak	Alasan pengiriman seperti restock atau pemerataan outlet
`notes`	string	Tidak	Catatan tambahan transfer
`idempotency_key`	string	Tidak	Kunci idempotensi operasi
`metadata`	object	Tidak	Metadata teknis audit dan korelasi
`cost_status`	string	Tidak	Status kelengkapan biaya: complete, provisional_zero_cost, unassigned

StockAlert

Entitas alert stok yang dapat terdeteksi saat offline dan di-sinkronisasi bersama data lainnya.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik alert
`inventory_id`	string	Tidak	ID inventory yang memicu alert
`product_id`	string	Tidak	ID produk yang terdampak
`product_name`	string	Tidak	Nama produk untuk tampilan
`location_id`	string	Tidak	ID lokasi gudang terdampak
`location_name`	string	Tidak	Nama lokasi gudang
`alert_type`	string	Ya	Tipe alert: low_stock, out_of_stock, overstock, expiring_soon, reconciliation_needed, negative_stock, rapid_depletion, orphaned_movement, duplicate_movement, futuristic_date, lot_negative
`current_quantity`	number	Tidak	Kuantitas stok saat ini ketika alert terpicu
`threshold_quantity`	number	Tidak	Kuantitas ambang batas yang memicu alert
`severity`	string	Tidak	Tingkat keparahan: low, medium, high, critical (default: medium)
`status`	string	Tidak	Status alert: active, acknowledged, dismissed, resolved
`title`	string	Tidak	Ringkasan alert untuk tampilan daftar
`description`	string	Tidak	Penjelasan detail anomali atau kondisi
`recommended_action`	string	Tidak	Tindakan yang disarankan oleh sistem
`fingerprint`	string	Tidak	Key stabil per anomali untuk mencegah notifikasi duplikat antar perangkat
`source`	string	Tidak	Asal deteksi alert, misal stock_anomaly_detector
`entity_ref_id`	string	Tidak	ID entitas terkait seperti LotBatch atau StockMovement
`movement_ids`	array	Tidak	ID StockMovement yang memicu anomali
`detected_at`	datetime	Tidak	Waktu anomali terdeteksi oleh scanner
`acknowledged_by`	string	Tidak	Pengguna yang mengakui alert
`acknowledged_at`	datetime	Tidak	Waktu alert diakui
`resolved_at`	datetime	Tidak	Waktu alert diselesaikan
`auto_reorder_triggered`	boolean	Tidak	Apakah reorder otomatis sudah dipicu (default: false)
`notes`	string	Tidak	Catatan tambahan terkait alert

AuditLog

Entitas audit trail yang mencatat setiap operasi sinkronisasi dan perubahan data.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan tempat aksi dilakukan
`user_id`	string	Ya	ID pengguna yang melakukan aksi
`user_email`	string	Tidak	Email pengguna untuk identifikasi
`action`	string	Ya	Aksi yang dilakukan: create, read, update, delete, approve, reject, lock, unlock, unlock_request
`entity_type`	string	Ya	Tipe entitas yang diakses seperti CompanyPOSTransaction, Inventory
`entity_id`	string	Tidak	ID entitas spesifik yang diakses
`old_value`	object	Tidak	Nilai lama sebelum perubahan (untuk update)
`new_value`	object	Tidak	Nilai baru setelah perubahan (untuk update)
`timestamp`	datetime	Ya	Waktu aksi dilakukan
`ip_address`	string	Tidak	Alamat IP dari mana aksi dilakukan
`device_info`	string	Tidak	User Agent atau informasi perangkat
`description`	string	Tidak	Deskripsi detail aksi yang dilakukan
`status`	string	Tidak	Status eksekusi: success atau failed (default: success)

WarehouseLocation

Entitas lokasi gudang yang di-cache secara lokal untuk referensi saat offline.

Field	Type	Required	Description
`company_id`	string	Ya	ID perusahaan pemilik lokasi
`location_name`	string	Ya	Nama lokasi seperti Gudang Utama atau Toko Cabang A
`location_code`	string	Ya	Kode unik lokasi untuk identifikasi
`location_type`	string	Tidak	Tipe lokasi: warehouse, store, transit, virtual (default: warehouse)
`description`	string	Tidak	Penjelasan mengenai lokasi gudang, kapasitas, dan jenis barang
`address`	string	Tidak	Alamat lengkap lokasi
`city`	string	Tidak	Kota lokasi gudang
`manager_name`	string	Tidak	Nama penanggung jawab lokasi
`manager_contact`	string	Tidak	Kontak penanggung jawab lokasi
`capacity`	number	Tidak	Kapasitas maksimal dalam unit atau meter persegi
`current_utilization`	number	Tidak	Utilisasi saat ini dalam persentase (default: 0)
`is_active`	boolean	Tidak	Status keaktifan lokasi (default: true)
`coordinates`	object	Tidak	Koordinat GPS: latitude dan longitude

POSProduct

Entitas katalog produk global yang di-sinkronisasi ke cache lokal untuk akses offline.

Field	Type	Required	Description
`name`	string	Ya	Nama produk
`sku`	string	Tidak	SKU atau Barcode produk
`category`	string	Tidak	Kategori produk
`description`	string	Tidak	Deskripsi lengkap produk
`price`	number	Ya	Harga jual produk
`cost`	number	Tidak	Harga modal atau beli produk
`stock`	number	Tidak	Stok saat ini (default: 0)
`min_stock`	number	Tidak	Minimum stok untuk alert (default: 5)
`image_url`	string	Tidak	URL gambar utama produk
`variants`	array	Tidak	Daftar varian produk: nama, sku, price, stock
`is_active`	boolean	Tidak	Status keaktifan produk (default: true)
`tax_rate`	number	Tidak	Persentase pajak 0-100 (default: 0)
`supplier`	string	Tidak	Nama supplier produk
`unit`	string	Tidak	Satuan produk (default: pcs)
`digital_product_id`	string	Tidak	ID dari DigitalProduct jika sinkronisasi
`is_synced_from_digital`	boolean	Tidak	Apakah produk disinkronkan dari DigitalProduct (default: false)
`last_synced`	datetime	Tidak	Waktu terakhir sinkronisasi dilakukan

Sinkronisasi Status Lifecycle

Diagram state berikut menggambarkan siklus hidup status sinkronisasi data dari pembuatan di mode offline hingga berhasil tersinkronisasi atau gagal.

Status Sync Queue — Detail Transisi

Status Asal	Status Tujuan	Pemicu	Deskripsi
`[*]`	`pending`	User membuat data baru saat offline	Data masuk ke antrian sinkronisasi lokal
`pending`	`syncing`	Connection detector mendeteksi online	Sync engine mulai memproses antrian
`syncing`	`synced`	Server mengembalikan 2xx	Data berhasil diterima dan divalidasi server
`syncing`	`conflict`	Server mengembalikan 409 Conflict	Data bentrok dengan versi di server
`syncing`	`failed`	Timeout atau error jaringan	Pengiriman gagal, akan di-retry
`conflict`	`manual_review`	Konflik memerlukan keputusan user	Ditampilkan di panel konflik untuk resolusi
`conflict`	`syncing`	Auto-resolve berhasil	Sistem otomatis memilih resolusi berdasarkan strategi
`manual_review`	`syncing`	User memilih resolusi	Data dikirim ulang dengan resolusi yang dipilih
`manual_review`	`discarded`	User memutuskan buang perubahan	Data lokal dihapus dari antrian
`failed`	`pending`	Retry timer habis	Antrian dijadwalkan ulang untuk percobaan berikutnya
`failed`	`discarded`	Max retries (5x) tercapai	Data ditandai gagal permanen
`failed`	`manual_review`	Gagal berulang tanpa perbaikan	Diperlukan investigasi manual oleh admin

Sequence Diagram — Flow Data Offline

1. Pembuatan Transaksi POS Offline

Diagram ini menggambarkan flow lengkap saat kasir membuat transaksi POS tanpa koneksi internet.

2. Proses Sinkronisasi Saat Koneksi Kembali

Diagram ini menggambarkan flow saat koneksi internet kembali dan sync engine memproses antrian.

3. Penanganan Konflik Data (Conflict Resolution)

Diagram ini menggambarkan flow saat terjadi konflik data antara versi offline dan server.

4. Stock Opname Offline — Input dan Sinkronisasi

Diagram ini menggambarkan flow saat staf gudang melakukan stock opname di area tanpa koneksi.

Referensi Enum & Status

payment_method — Metode Pembayaran Transaksi POS

Nilai	Deskripsi
`cash`	Pembayaran tunai langsung di kasir
`card`	Pembayaran menggunakan kartu debit atau kredit
`transfer`	Transfer bank manual atau otomatis
`ewallet`	Pembayaran via dompet elektronik (GoPay, OVO, Dana, dll)
`qris`	Pembayaran via QRIS (QR Code Indonesian Standard)
`saldo`	Pembayaran menggunakan saldo akun pelanggan
`mayar`	Pembayaran via gateway Mayar
`debt`	Transaksi hutang atau tempo
`manual_transfer`	Transfer bank manual yang perlu verifikasi
`midtrans`	Pembayaran via gateway Midtrans
`tripay`	Pembayaran via gateway Tripay
`stripe`	Pembayaran via gateway Stripe
`paypal`	Pembayaran via PayPal

payment_status — Status Pembayaran

Nilai	Deskripsi
`pending`	Pembayaran belum diterima atau dikonfirmasi
`pending_verification`	Pembayaran diterima, menunggu verifikasi manual
`partially_paid`	Pembayaran baru diterima sebagian dari total tagihan
`paid`	Pembayaran lunas dan terverifikasi penuh
`failed`	Pembayaran gagal diproses
`refunded`	Pembayaran sudah dikembalikan ke pelanggan
`rejected`	Pembayaran ditolak setelah review

order_status — Status Pesanan

Nilai	Deskripsi
`pending`	Pesanan baru diterima, belum diproses
`processing`	Pesanan sedang diproses atau dikemas
`shipped`	Pesanan sudah dikirim ke kurir
`delivered`	Pesanan sudah sampai ke pelanggan
`completed`	Pesanan selesai dan dikonfirmasi pelanggan
`cancelled`	Pesanan dibatalkan oleh pelanggan atau sistem
`rejected`	Pesanan ditolak oleh merchant

status (CompanyPOSTransaction) — Status Transaksi

Nilai	Deskripsi
`pending`	Transaksi baru dibuat, menunggu pemrosesan
`processing`	Transaksi sedang diproses lebih lanjut
`shipped`	Barang terkait transaksi sudah dikirim
`delivered`	Barang sudah diterima pelanggan
`completed`	Transaksi selesai sepenuhnya
`failed`	Transaksi gagal diproses
`refunded`	Dana transaksi sudah dikembalikan
`cancelled`	Transaksi dibatalkan

sales_channel — Channel Penjualan

Nilai	Deskripsi
`offline_pos`	Transaksi langsung di kasir menggunakan POS
`offline`	Transaksi offline non-POS
`website`	Pesanan dari website resmi
`online_catalog`	Pesanan dari katalog online
`marketplace`	Pesanan dari marketplace (Tokopedia, Shopee, dll)
`landing_page`	Pesanan dari landing page kampanye
`whatsapp`	Pesanan melalui WhatsApp
`reseller`	Pesanan dari channel reseller
`b2b`	Pesanan bisnis ke bisnis
`grab`	Pesanan dari platform Grab
`social_media`	Pesanan dari media sosial

source — Sumber Transaksi (Legacy)

Nilai	Deskripsi
`pos`	Transaksi dari sistem POS
`online_catalog`	Transaksi dari katalog online
`website`	Transaksi dari website
`marketplace`	Transaksi dari marketplace
`landing_page`	Transaksi dari landing page
`whatsapp`	Transaksi dari WhatsApp
`reseller`	Transaksi dari reseller
`b2b`	Transaksi B2B
`grab`	Transaksi dari Grab
`social_media`	Transaksi dari media sosial

movement_type — Tipe Pergerakan Stok

Nilai	Deskripsi
`in`	Stok masuk ke lokasi (dari pembelian, produksi, dll)
`out`	Stok keluar dari lokasi (penjualan, produksi, dll)
`transfer`	Perpindahan stok antar lokasi
`adjustment`	Penyesuaian stok manual atau dari stock opname
`return`	Pengembalian barang ke stok
`damaged`	Stok rusak dan dikeluarkan dari inventaris
`hold`	Stok ditahan untuk QC atau karantina (tidak mengubah on-hand)
`hold_release`	Stok dilepaskan dari status hold (tidak mengubah on-hand)

reference_type — Sumber Perubahan Stok

Nilai	Deskripsi
`purchase`	Pergerakan dari pembelian barang
`sale`	Pergerakan dari penjualan umum
`cashier_sale`	Pergerakan dari transaksi kasir POS
`production`	Pergerakan dari hasil produksi
`raw_material_outbound`	Pengeluaran bahan baku untuk produksi
`qc_release`	Pelepasan stok setelah lolos quality control
`transfer`	Pergerakan dari transfer antar lokasi
`adjustment`	Penyesuaian stok manual
`opname_adjustment`	Penyesuaian dari hasil stock opname
`return`	Pergerakan dari pengembalian barang
`manual`	Pergerakan manual tanpa referensi transaksi
`distribution_shipment`	Pergerakan dari pengiriman distribusi
`quality_hold`	Penahanan stok untuk quality check

stock_status — Status Ketersediaan Stok

Nilai	Deskripsi
`in_stock`	Stok tersedia dalam jumlah memadai
`low_stock`	Stok mendekati batas minimum, perlu reorder
`out_of_stock`	Stok habis, tidak tersedia
`overstock`	Stok melebihi kapasitas maksimum

status (StockOpname) — Status Sesi Stock Opname

Nilai	Deskripsi
`draft`	Sesi opname baru dibuat, belum dimulai
`in_progress`	Sesi opname sedang berjalan
`counting`	Proses penghitungan fisik sedang berlangsung
`submitted`	Hasil opname sudah disubmit untuk review
`pending_approval`	Menunggu persetujuan dari approver
`completed`	Sesi opname selesai diproses
`approved`	Sesi opname disetujui oleh approver
`posted`	Penyesuaian stok sudah diposting ke inventory
`rejected`	Sesi opname ditolak oleh approver

status (StockTransfer) — Status Transfer Stok

Nilai	Deskripsi
`draft`	Transfer baru dibuat, belum dikirim
`in_transit`	Barang sedang dalam perjalanan antar lokasi
`completed`	Transfer selesai, barang sudah diterima
`cancelled`	Transfer dibatalkan sebelum selesai

transfer_mode — Mode Transfer

Nilai	Deskripsi
`in_transit`	Alur 2-tahap: kirim → dalam perjalanan → terima
`direct`	Transfer instan: langsung tercatat di kedua lokasi

cost_status — Status Kelengkapan Biaya Transfer

Nilai	Deskripsi
`complete`	Biaya transfer sudah lengkap dan terverifikasi
`provisional_zero_cost`	Biaya sementara di-set nol, perlu konfirmasi
`unassigned`	Biaya belum diassign ke transfer ini

alert_type — Tipe Alert Stok

Nilai	Deskripsi
`low_stock`	Stok mendekati batas minimum
`out_of_stock`	Stok sudah habis
`overstock`	Stok melebihi batas maksimum
`expiring_soon`	Produk mendekati tanggal kedaluwarsa
`reconciliation_needed`	Diperlukan rekonsiliasi data stok
`negative_stock`	Stok bernilai negatif (anomali)
`rapid_depletion`	Stok berkurang sangat cepat secara tidak wajar
`orphaned_movement`	Pergerakan stok tanpa referensi yang valid
`duplicate_movement`	Pergerakan stok terdeteksi duplikat
`futuristic_date`	Tanggal pergerakan stok di masa depan (anomali)
`lot_negative`	Lot batch menunjukkan kuantitas negatif

severity — Tingkat Keparahan Alert

Nilai	Deskripsi
`low`	Keparahan rendah, tidak memerlukan tindakan segera
`medium`	Keparahan sedang, perlu diperhatikan dalam waktu dekat
`high`	Keparahan tinggi, perlu tindakan segera
`critical`	Keparahan kritis, memerlukan tindakan darurat

status (StockAlert) — Status Alert

Nilai	Deskripsi
`active`	Alert aktif dan belum ditindaklanjuti
`acknowledged`	Alert sudah diakui oleh pengguna
`dismissed`	Alert diabaikan karena tidak relevan
`resolved`	Alert sudah diselesaikan dan tidak lagi aktif

action (AuditLog) — Tipe Aksi Audit

Nilai	Deskripsi
`create`	Pengguna membuat record baru
`read`	Pengguna membaca atau mengakses record
`update`	Pengguna memperbarui data record
`delete`	Pengguna menghapus record
`approve`	Pengguna menyetujui approval request
`reject`	Pengguna menolak approval request
`lock`	Pengguna mengunci record dari perubahan
`unlock`	Pengguna membuka kunci record
`unlock_request`	Pengguna meminta pembukaan kunci record

status (AuditLog) — Status Eksekusi Audit

Nilai	Deskripsi
`success`	Aksi berhasil dieksekusi
`failed`	Aksi gagal dieksekusi

location_type — Tipe Lokasi Gudang

Nilai	Deskripsi
`warehouse`	Gudang utama untuk penyimpanan stok
`store`	Toko atau outlet penjualan
`transit`	Lokasi transit untuk perpindahan barang
`virtual`	Lokasi virtual untuk tracking stok non-fisik

product_type — Tipe Produk

Nilai	Deskripsi
`finished_good`	Produk jadi siap dijual
`raw_material`	Bahan baku untuk produksi
`semi_finished`	Produk setengah jadi
`packaging_material`	Material kemasan untuk produk
`bundle`	Paket bundle virtual dari beberapa SKU

storage_condition — Kondisi Penyimpanan

Nilai	Deskripsi
`room_temperature`	Penyimpanan pada suhu ruangan
`chilled`	Penyimpanan dalam kondisi dingin
`frozen`	Penyimpanan dalam kondisi beku

identity_status — Status Identitas Produk

Nilai	Deskripsi
`linked`	Identitas produk terhubung ke referensi canonical
`legacy_review`	Identitas produk lama perlu review manual

allocation_strategy — Strategi Alokasi Stok

Nilai	Deskripsi
`fifo`	First In First Out — stok tertua yang keluar duluan
`fefo`	First Expired First Out — stok yang segera kedaluwarsa keluar duluan
`manual`	Alokasi manual dipilih oleh pengguna	.

Teknis

Gunakan idempotency key pada setiap operasi stock mutation untuk mencegah duplikasi saat retry.
Selalu enqueue StockMovement bersama CompanyPOSTransaction untuk menjaga konsistensi stok antara client dan server.
Prioritaskan transaksi keuangan (payment_method: cash/card/ewallet) di atas operasi inventory non-kritis.
Implementasikan exponential backoff pada retry mechanism untuk menghindari membanjiri server saat reconnect.
Validasi data lokal sebelum enqueue — pastikan required fields (company_id, transaction_number, items, total) terisi.
Gunakan navigator.storage.persist() untuk meminta browser agar tidak meng-evict data IndexedDB secara otomatis.
Log semua sync events untuk debugging dan audit trail — termasuk timestamp, entity type, operation, dan result.

Rekomendasi Infrastruktur

Aspek	Rekomendasi	Alasan
Heartbeat interval	30 detik	Balance antara deteksi cepat dan overhead network
Max retries	5 kali	Cukup untuk gangguan sementara, tidak blocking terlalu lama
Retry backoff	Exponential (1s, 2s, 4s, 8s, 16s)	Hindari server overload saat reconnect
Queue batch size	20 items per batch	Balance antara throughput dan memory
IndexedDB versioning	Semantic versioning	Deteksi schema mismatch client-server
Data retention (local)	30 hari setelah sync	Balance antara debuggability dan storage
Conflict window	Last-write-wins untuk stok	Stok harus konsisten, bukan akurat secara historis

​title: “Offline Mode” description: “Sistem offline-first untuk POS dan inventory dengan auto-sync, conflict resolution, dan data persistence lokal.”

​Offline Mode

​Kasus Penggunaan Kritis

​Arsitektur Offline-First

​Diagram Arsitektur Umum

​Lapisan Data Persistence

​Komponen Sistem

​1. Local Storage Engine

​2. Connection Detector

​3. Sync Queue & Engine

​4. Conflict Resolution

​Fitur Utama

​Transaksi POS Offline

​Inventory Offline

​Entity Relationship Diagram

​Entity Schema Reference

​CompanyPOSTransaction

​Inventory

​StockMovement

​StockOpname

​StockTransfer

​StockAlert

​AuditLog

​WarehouseLocation

​POSProduct

​Sinkronisasi Status Lifecycle

​Status Sync Queue — Detail Transisi

​Sequence Diagram — Flow Data Offline

​1. Pembuatan Transaksi POS Offline

​2. Proses Sinkronisasi Saat Koneksi Kembali

​3. Penanganan Konflik Data (Conflict Resolution)

​4. Stock Opname Offline — Input dan Sinkronisasi

​Referensi Enum & Status

​payment_method — Metode Pembayaran Transaksi POS

​payment_status — Status Pembayaran

​order_status — Status Pesanan

​status (CompanyPOSTransaction) — Status Transaksi

​sales_channel — Channel Penjualan

​source — Sumber Transaksi (Legacy)

​movement_type — Tipe Pergerakan Stok

​reference_type — Sumber Perubahan Stok

​stock_status — Status Ketersediaan Stok

​status (StockOpname) — Status Sesi Stock Opname

​status (StockTransfer) — Status Transfer Stok

​transfer_mode — Mode Transfer

​cost_status — Status Kelengkapan Biaya Transfer

​alert_type — Tipe Alert Stok

​severity — Tingkat Keparahan Alert

​status (StockAlert) — Status Alert

​action (AuditLog) — Tipe Aksi Audit

​status (AuditLog) — Status Eksekusi Audit

​location_type — Tipe Lokasi Gudang

​product_type — Tipe Produk

​storage_condition — Kondisi Penyimpanan

​identity_status — Status Identitas Produk

​allocation_strategy — Strategi Alokasi Stok

​Teknis

​Rekomendasi Infrastruktur