Pemesanan Penjualan (Sales Order v2)
Formulir Sales Order v2 dirancang khusus untuk transaksi penjualan grosir B2B, penjualan termin kredit berjangka (Accounts Receivable), serta pesanan pengiriman terjadwal yang memerlukan koordinasi logistik gudang.
1. Diagram Alur Siklus Hidup Pesanan (Stage Stepper)
Setiap Sales Order bergerak melalui tahapan terstruktur yang dipantau melalui indikator visual Stage Stepper di bagian atas layar:
Rincian Perilaku Tiap Stage:
Draft(Penyusunan Rencana Pesanan):- Dokumen bebas disunting (menambah/menghapus barang atau mengubah kuantitas dan harga).
- Belum memotong saldo fisik di gudang.
Confirmed(Pesanan Sah & Penguncian Dokumen):- Header dan baris pesanan dikunci dari perubahan sembarangan.
- Sistem menerbitkan dokumen pengeluaran logistik (
StockPicking OUT) dengan statusReadyyang menugaskan petugas gudang untuk mengambil barang di rak. - Faktur piutang pelanggan tercatat di modul keuangan.
Done(Barang Telah Diserahkan / Selesai):- Petugas logistik menekan tombol Kirim Barang (Deliver) saat armada keluar dari gerbang gudang.
- Saldo stok fisik resmi terpotong di kartu stok (
StockLedger). - Jurnal akuntansi Harga Pokok Penjualan (HPP) dan Pendapatan Penjualan diposting ke buku besar.
Cancelled(Pembatalan Pesanan):-
Jika dibatalkan saat masih
Draft: Dokumen ditandai batal tanpa mutasi keuangan atau logistik. -
Jika dibatalkan setelah
ConfirmedatauDone: Sistem secara otomatis menerbitkan dokumen pengembalian barang (Picking Reversal) dan pembatalan piutang. -
Gudang tujuan retur saat void: bila pemanggil tidak mengirim
destinationLocationId, sistem memakai lokasi picking outbound dokumen itu — dan hanya bila lokasi itu benar-benar tunggal serta boleh diakses pemanggil. Kalau tidak (picking tidak ada / lokasinya berbeda-beda / di luar akses cabang), permintaan ditolak dengan galat:"RETURN_DESTINATION_REQUIRED: gudang tujuan retur tidak dapat ditentukan dari dokumen ini (tidak ada lokasi picking outbound tunggal yang dapat diakses) — kirim destinationLocationId"
Sistem tidak pernah memilih gudang secara acak. Karena itu pemanggil non-UI (API/mobile) wajib mengirim
destinationLocationIdeksplisit untuk dokumen yang tidak punya picking outbound tunggal. Perhatikan juga: void yang menyertakan retur fisik mewajibkanmanualUnitCostBasedanidempotencyKey; dari UI web jalur ini sengaja tidak dibuka — web mengarahkan ke menu Retur Penjualan (lihat Retur Penjualan). -
Metode refund void: bila pemanggil tidak mengirim
refundMethodId, sistem memakai metode pembayaran dokumen, lalu metodeCASHtenant — hanya dari kandidat yang aktif dan valid. Bila tidak ada kandidat deterministik (mis. metode dokumen non-aktif dan tidak adaCASHaktif), permintaan ditolak 400 dengan galat:"RETURN_REFUND_METHOD_REQUIRED: void Sales Order ... — kirim refundMethodId"
Sistem tidak memilih metode aktif lain secara acak, supaya jurnal/
Payment.methodtidak mencatat metode refund yang salah. -
Hak retur void: kuantitas yang dikembalikan dihitung dari riwayat mutasi stok
Done; menonaktifkan lokasi atau menghapus header picking setelah pengiriman tidak membatalkan hak retur tersebut.
-
2. Struktur Formulir Sales Order v2
Formulir Sales Order v2 menggunakan arsitektur antarmuka tingkat lanjut dengan pembagian area yang ergonomis:
A. Bagian Header Dokumen
| Nama Field | Tipe Data | Wajib? | Keterangan & Validasi |
|---|---|---|---|
Nomor Pesanan (orderNumber) | String | Otomatis | Diterbitkan otomatis oleh generator sequence (misal: SO-202609-0012). |
Pelanggan (customerId) | Relasi (Customer) | Wajib | Memilih mitra bisnis pelanggan. Menampilkan informasi plafon kredit dan alamat kirim. |
Tanggal Pesanan (orderDate) | Date | Wajib | Tanggal disepakatinya pesanan. |
Jatuh Tempo (dueDate) | Date | Wajib | Batas akhir pembayaran piutang pelanggan. Validasi: dueDate >= orderDate. |
Cabang Operasional (branchId) | Relasi (Branch) | Wajib | Kantor cabang yang melayani pesanan. (Lihat aturan Branch Locking). |
Catatan Pengiriman (notes) | Text | Opsional | Instruksi khusus untuk sopir atau kurir ekspedisi. |
B. Bagian Baris Barang (Lines Dialog)
Pengguna menekan tombol + Tambah Baris Barang untuk memunculkan modal dialog input produk yang detail:
- Produk (
productId): Memilih barang yang dijual. - Pilihan Satuan / Kemasan: Memilih apakah barang dijual per Satuan Dasar (
Pcs) atau Kemasan Pabrik Grosir (Dus isi 24). - Kuantitas (
qty): Jumlah yang dipesan. - Harga Satuan (
unitPrice): Harga per unit sebelum diskon (otomatis terisi dari master produk, dapat disesuaikan). - Diskon Baris (
discountPercent/discountAmount): Potongan harga promosi. - Kalkulasi PPN (
taxAmount): Dihitung otomatis sesuai tarif PPN produk (misal: 11%).
3. Mekanisme Penentuan Gudang Asal & Alur Pemotongan Stok (Two-Phase Fulfillment)
Berbeda dengan transaksi ritel POS yang memotong stok kasir secara instan/atomik, transaksi grosir atau distribusi pada Sales Order (SO) menggunakan pendekatan dua tahap (Two-Phase Fulfillment). Pendekatan ini memisahkan antara komitmen komersial dan serah terima logistik fisik.
A. Hierarki Penentuan Gudang Asal Persediaan
Satu dokumen Sales Order menghasilkan satu dokumen StockPicking dengan satu lokasi sumber
(StockMove tidak menyimpan kolom lokasi; lokasi hanya ada di header picking). Karena itu seluruh
baris pesanan memakai lokasi sumber yang sama, dan urutan penentuannya tetap (deterministik):
- Gudang cabang dokumen (
Branch.warehouse) — bila dokumen memilih Cabang (branchId) dan cabang itu sudah ditautkan ke gudang. Ini jalur utama dan paling mudah ditebak: satu dokumen, satu cabang, satu gudang. Wajib diisi bila tenant punya lebih dari satu gudang agar tidak ambigu. - Gudang default produk (
Product.defaultLocation) — dipakai bila dokumen belum/tidak memilih Cabang, atau cabangnya belum punya gudang. Baris pesanan ditelusuri urutid; lokasi pertama yang ditemukan dipakai. Untuk produkrecipe/BOM, bila produk resepnya sendiri tanpadefaultLocation, sistem memakaidefaultLocationkomponen pertama yang memilikinya. - Gudang tunggal tenant — bila langkah 1–2 tidak menghasilkan lokasi dan tenant hanya punya
tepat satu lokasi
locationType = WAREHOUSE. - Ditolak — dokumen tanpa acuan di atas pada tenant multi-gudang ditolak dengan pesan:
"SO_SOURCE_WAREHOUSE_AMBIGUOUS: dokumen belum punya Cabang bergudang dan produk tidak punya gudang default; tenant punya N gudang — isi Cabang pada dokumen atau gudang default produk"
Setiap kandidat lokasi divalidasi: milik tenant dokumen, tidak dihapus, aktif, dan bukan lokasi
VIRTUAL. Kode galat yang mungkin muncul: SO_SOURCE_LOCATION_TENANT_MISMATCH,
SO_SOURCE_LOCATION_DELETED, SO_SOURCE_LOCATION_INACTIVE, SO_SOURCE_LOCATION_VIRTUAL,
SO_SOURCE_WAREHOUSE_MISSING, SO_SOURCE_WAREHOUSE_AMBIGUOUS.
SalesOrder.branch adalah dimensi atribusi (laporan dan HPP mengikuti cabang penjual), sedangkan
gudang sumber adalah dimensi logistik. Keduanya boleh berbeda: cabang penjual A yang belum punya
gudang tetap sah mengirim dari gudang pusat tanpa cabang (lokasi tanpa branchId). Sistem sengaja
tidak memaksa StockPicking.location.branch == SalesOrder.branch.
Mutasi outbound dicatat pada lokasi sumber di atas, bukan pada rak anak (RACK). Validasi saldo
memakai roll-up subtree (OnHandService), sehingga total gudang + rak tetap benar, tetapi bila stok
fisik disimpan di rak, saldo node gudang bisa tampak negatif sementara raknya tetap positif. Simpan
di node gudang barang yang dijual langsung dari gudang, atau pindahkan dulu dengan transfer internal.
B. Siklus Pemotongan Stok Dua Tahap (Two-Phase Flow)
- Tahap 1: Konfirmasi Pesanan (
Confirmed) — Alokasi Dokumen (StageReady):- Saat dokumen Sales Order dialihkan dari
DraftkeConfirmed, sistem secara otomatis membuat dokumenStockPickingOUTGOING (bertipeSALES) dengan stageReady. - Rute picking: dari lokasi sumber hasil hierarki §3.A menuju
VIRTUAL-CUSTOMER. - Pada tahap ini, picking berfungsi sebagai Daftar Ambil Barang (Pick List) dan Surat Jalan Pengiriman.
- Saldo fisik di gudang belum dipotong pada
StockLedger, namun pesanan telah tercatat sebagai komitmen pengeluaran logistik.
- Saat dokumen Sales Order dialihkan dari
- Tahap 2: Pengiriman Barang (
Deliver) — Eksekusi Fisik (StageDone):- Ketika armada pengiriman siap berangkat atau barang diserahkan ke kurir ekspedisi, staf menekan tombol Deliver (Kirim Barang).
- Sistem memajukan dokumen picking yang berstatus
Readytersebut menjadiDone(atau menerbitkan pickingDonebaru memakai hierarki lokasi sumber §3.A — aturan yang sama dengan jalur Confirm, tanpa pemilihan acak). - Pada momen inilah saldo fisik persediaan di gudang asal resmi terpotong dan tercatat di kartu stok (
StockLedger).
- Validasi Saldo Outbound Ketat (
validateOutboundBalance):- Tepat sebelum picking dimajukan ke
Done, sistem menjalankan validasi saldo keluar secara komprehensif (validateOutboundBalance). - Apabila stok riil di lokasi gudang sumber tidak mencukupi dan produk tidak mengizinkan stok minus (
allowNegativeStock = false), proses Deliver langsung digagalkan demi menjaga integritas stok fisik.
- Tepat sebelum picking dimajukan ke
4. Hal-Hal Kritis yang Wajib Diperhatikan (Why)
A. Pengecekan Ketersediaan Stok Sebelum Menjanjikan Pengiriman
Sebelum mengklik Confirm, selalu periksa kolom ketersediaan stok fisik gudang cabang. Jika stok fisik kurang dari jumlah yang dipesan dan produk disetel allowNegativeStock = false, konfirmasi pengiriman akan gagal saat petugas gudang mencoba memproses dokumen pengeluaran barang.
B. Ketelitian Memilih Satuan vs Kemasan Grosir
Perhatikan perbedaan mendasar antara menginput:
- 10
Pcs= Total 10 unit barang fisik. - 10
Dus isi 24= Total 240 unit barang fisik! Kekeliruan memilih kemasan pada baris pesanan dapat mengakibatkan selisih pengiriman barang dalam jumlah yang sangat masif.
C. Penguncian Cabang (Branch Locking)
Setelah Sales Order berstatus Confirmed atau menghasilkan pergerakan stok/jurnal, kolom Cabang (branchId) akan dikunci secara permanen. Anda tidak dapat memindahkan transaksi ke cabang lain karena nomor faktur, gudang asal persediaan, dan rekening buku besar cabang telah terikat erat di basis data.