Hierarki Lokasi Gudang & Kartu Stok (Stock Ledger)

Manajemen inventaris dalam Git Demo ERP dirancang menggunakan prinsip dasar pergerakan fisik riil dan integritas akuntansi berpasangan (Double-Entry Inventory). Tidak ada barang yang masuk atau keluar tanpa titik asal dan titik tujuan yang jelas.

---

1. Struktur Hierarki Lokasi (StockLocation)

Setiap area penyimpanan dipetakan ke dalam pohon hierarki bertingkat (Tree Structure) menggunakan kolom parentId.

Tingkatan Tipe Lokasi:

1. WAREHOUSE (Gudang Utama / Gedung): Level teratas dari suatu fasilitas fisik. Biasanya diasosiasikan langsung dengan sebuah Kantor Cabang (Branch).
2. RACK (Rak / Lorong / Aisle): Sub-lokasi di dalam gudang untuk membedakan deretan rak penyimpanan barang.
3. BIN (Sekat / Kotak Penyimpanan): Level penyimpanan terkecil dan paling spesifik di dalam rak.

Mekanisme Kalkulasi Saldo Otomatis (Roll-Up Subtree)

Saat kasir atau modul penjualan memeriksa ketersediaan saldo produk di level gudang WAREHOUSE, sistem backend secara cerdas menjalankan kueri rekursif (Recursive Subtree Roll-up). Sistem akan menjumlahkan seluruh persediaan fisik yang tersimpan di seluruh rak (RACK) dan sekat (BIN) di bawah naungan gudang tersebut.

---

2. Lokasi Virtual Sistem (Virtual System Locations)

Selain lokasi fisik yang dapat disentuh di dunia nyata, sistem menyediakan lokasi perantara khusus berjenis VIRTUAL. Lokasi virtual ini digunakan sebagai pasangan transaksi debet-kredit dalam pergerakan barang:

Kode Lokasi Virtual	Peruntukan Bisnis	Contoh Transaksi
VIRTUAL-SUPPLIER	Sumber asal barang luar saat pembelian	Dokumen Goods Receipt dari Purchase Order
VIRTUAL-CUSTOMER	Tujuan akhir barang saat pengiriman ke pembeli	Dokumen Delivery Order dari Sales Order atau Struk POS
VIRTUAL-PRODUCTION	Penampung sementara bahan baku rakitan	Alur perakitan Bundle Assembly
INV-ADJ-GAIN	Penyeimbang surplus fisik saat audit stok	Penemuan barang berlebih pada Stock Opname
INV-ADJ-LOSS	Penyeimbang defisit fisik saat audit stok	Barang hilang / rusak pada Stock Opname
VIRTUAL-TRANSIT	Penampungan barang selama pengiriman antar cabang	Alur pengiriman transfer 2 langkah (Two-Step Transfer)

Kenapa Menggunakan Lokasi Virtual?

Dengan adanya lokasi virtual, sistem tidak pernah melakukan operasi berbahaya seperti UPDATE stock SET qty = qty - 5. Seluruh mutasi dicatat sebagai perpindahan barang:

• Beli: Dari VIRTUAL-SUPPLIER → Ke Gudang Utama.
• Jual: Dari Gudang Utama → Ke VIRTUAL-CUSTOMER. Hal ini menjamin hukum kekekalan materi dan keabsahan audit jejak rekam transaksi!

---

3. Kartu Stok (StockLedger): Read-Only SQL View

Kartu Stok di Git Demo ERP dapat diakses melalui menu Gudang > Kartu Stok (Stock Ledger).

Sifat Desain Kartu Stok:

1. Read-Only Database View: Data kartu stok adalah materialized/dynamic SQL view yang ditarik langsung dari tabel riwayat mutasi perpindahan barang (stock_move). Tidak ada pengguna maupun administrator yang dapat memanipulasi, menyunting, atau menghapus baris kartu stok secara manual.
2. Jaminan Zero-Drift: Saldo akhir (On-Hand Balance) produk di suatu lokasi adalah hasil kalkulasi agregat mutasi masuk dikurangi mutasi keluar. Karena saldo ditarik dari pergerakan riil, tidak mungkin terjadi diskrepansi angka antara kartu stok dan saldo siap jual di aplikasi.
3. Format Akuntansi Berpasangan: Setiap baris mencatat:
   • Tanggal & Jam Transaksi.
   • Dokumen Referensi (Nomor SO, PO, Opname, Transfer, atau POS Receipt).
   • Lokasi Asal (Source Location) & Lokasi Tujuan (Destination Location).
   • Kuantitas Masuk / Keluar dalam Satuan Dasar (qty_base).
   • Saldo Kumulatif Berjalan (Running Balance).

---

4. Matriks Komparatif Alur & Sumber Stok Antar Modul ERP

Untuk memahami bagaimana setiap modul di dalam sistem berinteraksi dengan hierarki gudang dan lokasi virtual, perhatikan matriks komparatif Single Source of Truth (SSOT) berikut:

Modul Transaksi	Penentuan Lokasi Sumber (Source)	Penentuan Lokasi Tujuan (Destination)	Titik Eksekusi Pemotongan / Penambahan Fisik	Perilaku Khusus & Validasi
POS Kasir (Ritel Toko)	CashRegister.stockLocation (Fisik WAREHOUSE/RACK milik mesin kasir)	VIRTUAL-CUSTOMER	Seketika (Atomik) saat bayar lunas / checkout (Done instan)	Dilarang lokasi virtual (POS_INVALID_ISSUE_LOCATION). Resep/BOM otomatis memotong bahan baku dari lokasi kasir yang sama. Cek saldo via OnHandService.
Sales Order (SO Grosir / B2B)	Product.defaultLocation (Master produk / bahan baku resep)	VIRTUAL-CUSTOMER	Dua Tahap: Confirmed buat picking Ready, tombol Deliver majukan ke Done	Wajib isi defaultLocation saat Confirmed. Validasi outbound ketat (validateOutboundBalance) sebelum Done.
Purchase Order (PO Pengadaan)	VIRTUAL-SUPPLIER	Gudang Fisik Penerimaan (StockLocation tujuan cabang)	Saat dokumen Penerimaan Barang (Goods Receipt) mencapai Done	Menambah saldo fisik di kartu stok dan membukukan persediaan di akuntansi.
Transfer 1-Step (Internal Langsung)	Gudang Asal (sourceLocationId)	Gudang Tujuan (destLocationId)	Seketika saat transfer disahkan ke Done	Cocok untuk perpindahan barang dalam 1 gedung atau rak tanpa waktu tempuh kurir.
Transfer 2-Step (Ekspedisi Cabang)	Kirim: Gudang Asal Terima: VIRTUAL-TRANSIT	Kirim: VIRTUAL-TRANSIT Terima: Gudang Tujuan	Kirim: Memotong asal saat Done Terima: Menambah tujuan saat Done	Mencegah selisih barang selama perjalanan antar-kota. Saldo transit terpantau transparan.
Stock Opname (Audit Stok)	Surplus: INV-ADJ-GAIN Defisit: Gudang Fisik	Surplus: Gudang Fisik Defisit: INV-ADJ-LOSS	Saat dokumen Opname disetujui / disahkan ke Done	Menyelaraskan catatan komputer agar sama persis dengan hasil hitung fisik di gudang.
Perakitan Bundle (Assembly)	Komponen: Gudang Bahan Baku (sourceLocationId)	Komponen: VIRTUAL-PRODUCTION Hasil Jadi: Gudang Jadi (destLocationId)	Saat dokumen Perakitan disahkan ke Done	Bahan baku terpotong dan barang jadi bertambah secara simultan menjaga HPP rakitan.
Retur Penjualan (Sales Return)	VIRTUAL-CUSTOMER	Gudang Karantina / Retur Cabang (destLocationId)	Saat penerimaan barang retur disahkan ke Done	Memisahkan barang rusak/kembali dari stok siap jual di rak kasir atau gudang utama.