Lewati ke konten utama

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:​

  1. Draft (Penyusunan Rencana Pesanan):
    • Dokumen bebas disunting (menambah/menghapus barang atau mengubah kuantitas dan harga).
    • Belum memotong saldo fisik di gudang.
  2. Confirmed (Pesanan Sah & Penguncian Dokumen):
    • Header dan baris pesanan dikunci dari perubahan sembarangan.
    • Sistem menerbitkan dokumen pengeluaran logistik (StockPicking OUT) dengan status Ready yang menugaskan petugas gudang untuk mengambil barang di rak.
    • Faktur piutang pelanggan tercatat di modul keuangan.
  3. 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.
  4. Cancelled (Pembatalan Pesanan):
    • Jika dibatalkan saat masih Draft: Dokumen ditandai batal tanpa mutasi keuangan atau logistik.

    • Jika dibatalkan setelah Confirmed atau Done: 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 destinationLocationId eksplisit untuk dokumen yang tidak punya picking outbound tunggal. Perhatikan juga: void yang menyertakan retur fisik mewajibkan manualUnitCostBase dan idempotencyKey; 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 metode CASH tenant — hanya dari kandidat yang aktif dan valid. Bila tidak ada kandidat deterministik (mis. metode dokumen non-aktif dan tidak ada CASH aktif), 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.method tidak 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 FieldTipe DataWajib?Keterangan & Validasi
Nomor Pesanan (orderNumber)StringOtomatisDiterbitkan otomatis oleh generator sequence (misal: SO-202609-0012).
Pelanggan (customerId)Relasi (Customer)WajibMemilih mitra bisnis pelanggan. Menampilkan informasi plafon kredit dan alamat kirim.
Tanggal Pesanan (orderDate)DateWajibTanggal disepakatinya pesanan.
Jatuh Tempo (dueDate)DateWajibBatas akhir pembayaran piutang pelanggan. Validasi: dueDate >= orderDate.
Cabang Operasional (branchId)Relasi (Branch)WajibKantor cabang yang melayani pesanan. (Lihat aturan Branch Locking).
Catatan Pengiriman (notes)TextOpsionalInstruksi 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):

  1. 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.
  2. Gudang default produk (Product.defaultLocation) — dipakai bila dokumen belum/tidak memilih Cabang, atau cabangnya belum punya gudang. Baris pesanan ditelusuri urut id; lokasi pertama yang ditemukan dipakai. Untuk produk recipe/BOM, bila produk resepnya sendiri tanpa defaultLocation, sistem memakai defaultLocation komponen pertama yang memilikinya.
  3. Gudang tunggal tenant — bila langkah 1–2 tidak menghasilkan lokasi dan tenant hanya punya tepat satu lokasi locationType = WAREHOUSE.
  4. 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.

Atribusi cabang ≠ gudang pengirim

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 selalu dicatat di node gudang

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)​

  1. Tahap 1: Konfirmasi Pesanan (Confirmed) — Alokasi Dokumen (Stage Ready):
    • Saat dokumen Sales Order dialihkan dari Draft ke Confirmed, sistem secara otomatis membuat dokumen StockPicking OUTGOING (bertipe SALES) dengan stage Ready.
    • 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.
  2. Tahap 2: Pengiriman Barang (Deliver) — Eksekusi Fisik (Stage Done):
    • Ketika armada pengiriman siap berangkat atau barang diserahkan ke kurir ekspedisi, staf menekan tombol Deliver (Kirim Barang).
    • Sistem memajukan dokumen picking yang berstatus Ready tersebut menjadi Done (atau menerbitkan picking Done baru 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).
  3. 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.

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)​

Penguncian Cabang Transaksional

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.