title: “Distribution Tracking” description: “Sistem tracking distribusi, shipment management, batch recall, dan surat jalan di SNISHOP ERP.”

Distribution Tracking

Distribution Tracking adalah modul logistik end-to-end yang mengelola pengiriman dari gudang ke partner atau customer. Modul ini mencakup 8 status pengiriman, integrasi dengan 7 logistic provider, mesin recall batch untuk produk bermasalah, dan generate surat jalan untuk dokumentasi fisik. Sistem ini dirancang untuk bisnis F&B manufacturing yang membutuhkan visibilitas penuh atas setiap batch produk yang keluar dari gudang — mulai dari picking, packing, shipping, hingga delivery confirmation. Jika terjadi masalah kualitas pada batch tertentu, fitur batch recall memungkinkan identifikasi dan penarikan produk secara terstruktur.

Arsitektur Komponen

Entity Relationship Diagram

Entity & Model

DistributionShipment

Entitas utama yang merepresentasikan setiap pengiriman produk dari gudang ke customer/distributor. Setiap shipment terhubung dengan Sales Order, melacak batch produk untuk keperluan recall, dan terintegrasi dengan modul Finance melalui invoice_id dan finance_record_id.

Field	Tipe	Required	Deskripsi
`company_id`	String	Ya	ID perusahaan (multi-tenant scoping)
`shipment_number`	String	Ya	Nomor pengiriman unik (format: SHIP-YYYYMMDD-XXX)
`sales_order_id`	String	Tidak	ID Sales Order terkait
`so_number`	String	Tidak	Nomor Sales Order referensi
`customer_id`	String	Ya	ID customer/distributor tujuan
`customer_name`	String	Tidak	Nama customer/distributor
`customer_type`	Enum	Tidak	Tipe customer: `retail`, `reseller`, `distributor`, `modern_market` (default: `distributor`)
`destination_address`	String	Tidak	Alamat lengkap tujuan pengiriman
`destination_city`	String	Tidak	Kota tujuan pengiriman
`shipment_date`	Date	Ya	Tanggal barang dikirim
`estimated_arrival`	Date	Tidak	Estimasi waktu tiba di tujuan
`actual_arrival`	Date	Tidak	Tanggal aktual barang diterima
`items`	Array[Object]	Tidak	Daftar item produk yang dikirim dengan batch tracking
`items[].product_id`	String	-	ID produk yang dikirim
`items[].product_name`	String	-	Nama produk
`items[].batch_id`	String	-	Batch ID produk jadi untuk recall tracking
`items[].lot_number`	String	-	Nomor lot batch fisik
`items[].quantity`	Number	-	Jumlah produk yang dikirim
`items[].unit`	String	-	Satuan produk
`items[].unit_price`	Number	-	Harga satuan
`items[].total_price`	Number	-	Total harga per item
`total_quantity`	Number	Tidak	Total kuantitas seluruh item (default: 0)
`total_amount`	Number	Tidak	Total nilai pengiriman (default: 0)
`logistic_provider`	String	Tidak	Nama ekspedisi atau logistik
`tracking_number`	String	Tidak	Nomor resi dari logistik
`status`	Enum	Tidak	Status pengiriman (default: `pending`)
`received_by`	String	Tidak	Nama penerima saat konfirmasi
`received_date`	Date	Tidak	Tanggal penerimaan dikonfirmasi
`received_notes`	String	Tidak	Catatan saat penerimaan
`is_recalled`	Boolean	Tidak	Flag recall untuk batch bermasalah (default: `false`)
`recall_reason`	String	Tidak	Alasan recall batch
`recall_date`	Date	Tidak	Tanggal recall dilaksanakan
`prepared_by`	String	Tidak	User yang menyiapkan pengiriman
`prepared_by_name`	String	Tidak	Nama penyiap pengiriman
`notes`	String	Tidak	Catatan tambahan
`metadata`	Object	Tidak	Server-authoritative idempotency and traceability metadata
`invoice_id`	String	Tidak	ID Invoice sell-in yang diposting otomatis saat pengiriman dibuat
`finance_record_id`	String	Tidak	ID FinancialRecord piutang (receivable) terkait pengiriman

DistributionReturn

Entitas yang mengelola proses retur pengiriman dari customer/distributor. Setiap return terhubung dengan shipment asal, melalui proses QC, karantina, dan disposisi akhir.

Field	Tipe	Required	Deskripsi
`company_id`	String	Ya	ID perusahaan (multi-tenant)
`return_number`	String	Ya	Nomor dokumen return unik
`shipment_id`	String	Ya	ID DistributionShipment asal retur
`shipment_number`	String	Tidak	Nomor shipment referensi
`customer_id`	String	Ya	ID customer yang mengajukan return
`customer_name`	String	Tidak	Nama customer
`items`	Array[Object]	Tidak	Daftar item yang di-return
`items[].product_id`	String	-	ID produk yang di-return
`items[].product_name`	String	-	Nama produk
`items[].category_key`	String	-	Kunci kategori produk
`items[].category_name`	String	-	Nama kategori
`items[].variant_key`	String	-	Kunci varian
`items[].variant_name`	String	-	Nama varian
`items[].variant_label`	String	-	Label varian
`items[].size_grams`	Number	-	Ukuran dalam gram
`items[].base_product_key`	String	-	Kunci produk dasar
`items[].batch_id`	String	-	Batch ID produk
`items[].quantity`	Number	-	Jumlah yang di-return
`items[].unit`	String	-	Satuan
`items[].reason`	String	-	Alasan return per item
`items[].condition`	String	-	Kondisi barang saat return
`items[].historical_unit_price`	Number	-	Harga satuan historis saat pengiriman asli
`items[].historical_total_price`	Number	-	Total harga historis
`items[].price_source`	String	-	Sumber data harga historis
`total_quantity`	Number	Tidak	Total kuantitas return
`requested_date`	Date	Ya	Tanggal permintaan return diajukan
`status`	Enum	Ya	Status return (default: `requested`)
`received_date`	DateTime	Tidak	Tanggal barang return diterima di gudang
`received_by`	String	Tidak	User yang menerima barang return
`received_location_id`	String	Tidak	ID WarehouseLocation penerimaan return
`quarantine_lot_id`	String	Tidak	ID lot karantina untuk barang return
`quarantine_status`	Enum	Tidak	Status karantina barang return
`qc_status`	Enum	Tidak	Status quality control return
`approved_quantity`	Number	Tidak	Kuantitas yang disetujui
`rejected_quantity`	Number	Tidak	Kuantitas yang ditolak
`disposition_reason`	String	Tidak	Alasan disposisi akhir
`disposition_date`	DateTime	Tidak	Tanggal disposisi dilakukan
`disposition_by`	String	Tidak	User yang melakukan disposisi
`notes`	String	Tidak	Catatan tambahan
`metadata`	Object	Tidak	Metadata teknis
`requested_by`	String	Tidak	User yang meminta return
`requested_by_email`	String	Tidak	Email peminta return

LotBatch

Entitas yang merepresentasikan setiap batch/lot produksi atau penerimaan bahan baku. LotBatch merupakan tulang punggung traceability — setiap produk yang diproduksi, disimpan, dikirim, atau direcall dapat dilacak melalui nomor lot.

Field	Tipe	Required	Deskripsi
`company_id`	String	Ya	ID perusahaan (multi-tenant)
`lot_number`	String	Ya	Nomor lot/batch unik
`product_id`	String	Ya	ID produk terkait
`product_name`	String	Tidak	Nama produk
`product_sku`	String	Tidak	SKU produk
`product_type`	String	Tidak	Jenis produk
`identity_status`	Enum	Tidak	Status identitas: `linked`, `legacy_review`
`source_material_id`	String	Tidak	ID bahan baku sumber
`category_key`	String	Tidak	Key kategori produk
`category_name`	String	Tidak	Nama kategori
`variant_key`	String	Tidak	Key varian
`variant_name`	String	Tidak	Nama varian
`variant_label`	String	Tidak	Label varian
`size_grams`	Number	Tidak	Ukuran dalam gram
`base_product_key`	String	Tidak	Key produk dasar
`production_order_id`	String	Tidak	ID production order yang menghasilkan lot
`quantity`	Number	Ya	Jumlah awal dalam lot ini
`quantity_remaining`	Number	Tidak	Jumlah yang tersisa
`current_quantity`	Number	Tidak	Kuantitas lot saat ini (cermin dari quantity_remaining, ditulis oleh proses rilis QC)
`reserved_quantity`	Number	Tidak	Jumlah yang direservasi (default: 0)
`manufacture_date`	Date	Tidak	Tanggal produksi
`expiry_date`	Date	Tidak	Tanggal kadaluarsa
`location_id`	String	Tidak	ID WarehouseLocation penyimpanan
`location_name`	String	Tidak	Nama lokasi gudang
`cost_per_unit`	Number	Tidak	Biaya per unit untuk lot ini
`status`	Enum	Tidak	Status lot batch (default: `active`)
`quality_status`	Enum	Tidak	Status kualitas (default: `pending`)
`notes`	String	Tidak	Catatan tambahan
`warehouse_location_name`	String	Tidak	Nama gudang penyimpanan
`rack_location`	String	Tidak	Lokasi rak penyimpanan (misal: A1, B2)
`expiry_alert_status`	Enum	Tidak	Status peringatan kadaluarsa (default: `normal`)
`haccp_verified`	Boolean	Tidak	Apakah batch sudah diverifikasi HACCP (default: `false`)
`item_type`	Enum	Tidak	Tipe item lot batch (default: `finished_good`)
`input_lots`	Array[Object]	Tidak	Daftar lot bahan baku/intermediate yang menyuplai lot ini (genealogy many-to-many)
`input_lots[].lot_id`	String	-	ID lot bahan baku
`input_lots[].lot_number`	String	-	Nomor lot bahan baku
`input_lots[].material_id`	String	-	ID material
`input_lots[].material_name`	String	-	Nama material
`input_lots[].quantity_used`	Number	-	Jumlah yang digunakan
`input_lots[].unit`	String	-	Satuan
`input_lots[].allocation_strategy`	String	-	Strategi alokasi
`input_lots[].override_reason`	String	-	Alasan penyimpangan FIFO
`input_lots[].identity_snapshot`	Object	-	Snapshot identitas canonical bahan
`supplier_id`	String	Tidak	ID supplier pemasok
`supplier_name`	String	Tidak	Nama supplier
`purchase_order_id`	String	Tidak	ID Purchase Order asal penerimaan
`delivery_note_number`	String	Tidak	Nomor surat jalan supplier
`unit`	String	Tidak	Satuan bahan (kg, gr, pcs, liter)
`received_at`	DateTime	Tidak	Waktu penerimaan fisik di gudang
`claimed_quantity`	Number	Tidak	Kuantitas menurut surat jalan supplier
`weighed_quantity`	Number	Tidak	Kuantitas timbang ulang aktual
`accepted_quantity`	Number	Tidak	Kuantitas diterima lolos QC
`rejected_quantity`	Number	Tidak	Kuantitas sortasi reject
`cost_status`	Enum	Tidak	Status kelengkapan biaya modal (default: `complete`)
`rounding_residual`	Number	Tidak	Residual pembulatan alokasi HPP (default: 0)
`cost_snapshot`	Object	Tidak	Snapshot rincian komponen biaya

WarehouseLocation

Entitas yang mendefinisikan lokasi-lokasi gudang, toko, transit, dan virtual dalam sistem ERP. Setiap shipment memiliki origin dan destination yang merujuk ke WarehouseLocation.

Field	Tipe	Required	Deskripsi
`company_id`	String	Ya	ID perusahaan
`location_name`	String	Ya	Nama lokasi (Gudang Utama, Toko Cabang A, dll)
`location_code`	String	Ya	Kode unik lokasi
`location_type`	Enum	Tidak	Tipe lokasi (default: `warehouse`)
`description`	String	Tidak	Penjelasan lokasi, kapasitas, dan jenis barang (maks 1000 karakter)
`address`	String	Tidak	Alamat lengkap lokasi
`city`	String	Tidak	Kota lokasi
`manager_name`	String	Tidak	Nama penanggung jawab
`manager_contact`	String	Tidak	Kontak penanggung jawab
`capacity`	Number	Tidak	Kapasitas maksimal (unit atau m2)
`current_utilization`	Number	Tidak	Utilisasi saat ini dalam persen (default: 0)
`is_active`	Boolean	Tidak	Status aktif (default: `true`)
`coordinates`	Object	Tidak	Koordinat GPS (latitude, longitude)

QualityCase

Entitas yang menangani kasus kualitas yang menyebabkan penahanan (hold/quarantine) batch produk. QualityCase menjadi trigger utama untuk proses recall pada Distribution Tracking.

Field	Tipe	Required	Deskripsi
`company_id`	String	Ya	ID perusahaan pemilik quality case
`lot_batch_id`	String	Ya	ID LotBatch yang menjadi objek hold
`product_name`	String	Tidak	Nama produk lot (snapshot saat case dibuka)
`batch_number`	String	Tidak	Nomor lot/batch fisik (snapshot saat case dibuka)
`reason`	Enum	Tidak	Kategori alasan penahanan batch
`description`	String	Tidak	Deskripsi rinci temuan kualitas
`evidence_urls`	Array[String]	Tidak	Daftar URL bukti foto/dokumen
`reported_by`	String	Ya	Email/ID user pelapor
`reported_at`	DateTime	Ya	Waktu quality case dilaporkan
`status`	Enum	Tidak	Status penanganan (default: `open`)
`assigned_to`	String	Tidak	User/tim penangani
`resolution_notes`	String	Tidak	Catatan resolusi
`resolved_at`	DateTime	Tidak	Waktu case diselesaikan
`hold_requested`	Boolean	Tidak	Apakah quarantine diminta (default: `false`)
`hold_approved_by`	String	Tidak	User penyetujui hold
`hold_approved_at`	DateTime	Tidak	Waktu hold disetujui

Status Pipelines & Lifecycle Diagrams

Shipment Status Lifecycle

Distribution Return Lifecycle

Quarantine Status Lifecycle (DistributionReturn)

Lot Batch Status Lifecycle

Quality Case Lifecycle

QuinnOrder Fulfillment Lifecycle

Enum Reference Tables

DistributionShipment Status

Status	Kode	Deskripsi
Pending	`pending`	Shipment baru dibuat, belum diproses di gudang
Processing	`processing`	Barang sedang diproses (picking, packing) di gudang
Shipped	`shipped`	Barang sudah diserahkan ke logistik / surat jalan dicetak
In Transit	`in_transit`	Dalam perjalanan di logistik partner
Delivered	`delivered`	Barang sampai di tujuan pengiriman
Confirmed	`confirmed`	Penerima mengkonfirmasi penerimaan dengan tanda tangan
Returned	`returned`	Barang dikembalikan ke gudang (gagal kirim atau retur)
Recalled	`recalled`	Batch produk ditarik karena masalah kualitas setelah pengiriman

Customer Type

Tipe	Kode	Deskripsi
Retail	`retail`	Customer perorangan/ritel
Reseller	`reseller`	Penjual ulang produk
Distributor	`distributor`	Distributor regional/lokal (default)
Modern Market	`modern_market`	Pasar modern (supermarket, minimarket)

Logistic Providers

Provider	Tipe	Coverage
JNE	Kurir nasional	Seluruh Indonesia
J&T Express	Kurir nasional	Seluruh Indonesia
SiCepat	Kurir nasional	Seluruh Indonesia
Anteraja	Kurir nasional	Seluruh Indonesia
GoSend	Instant/same-day	Kota besar (Java)
GrabExpress	Instant/same-day	Kota besar (Java)
Internal Fleet	Internal	Area lokal gudang

Distribution Return Status

Status	Kode	Deskripsi
Requested	`requested`	Customer mengajukan permintaan retur
Received	`received`	Barang retur diterima di gudang
QC Pending	`qc_pending`	Menunggu inspeksi Quality Control
Approved	`approved`	Retur disetujui setelah QC
Rejected	`rejected`	Retur ditolak setelah QC
Closed	`closed`	Proses retur selesai (disposisi final)

Distribution Return Quarantine Status

Status	Kode	Deskripsi
Pending	`pending`	Menunggu keputusan karantina
Quarantined	`quarantined`	Barang dikarantina di lot terpisah
Released	`released`	Dilepas dari karantina ke stok normal
Write Off	`write_off`	Dihapus dari inventori (rusak/tidak layak)

Distribution Return QC Status

Status	Kode	Deskripsi
Pending	`pending`	Menunggu inspeksi QC
Approved	`approved`	Lolos inspeksi QC
Rejected	`rejected`	Tidak lolos inspeksi QC
Conditional	`conditional`	Diterima dengan syarat tertentu

Lot Batch Status

Status	Kode	Deskripsi
Active	`active`	Lot baru dibuat, menunggu proses QC
Released	`released`	Lolos QC, tersedia untuk produksi atau pengiriman
Quarantine	`quarantine`	Ditahan untuk investigasi kualitas
Expired	`expired`	Melebihi tanggal kadaluarsa
Depleted	`depleted`	Stok lot habis terpakai sepenuhnya
Recalled	`recalled`	Lot ditarik karena masalah kualitas

Lot Batch Quality Status

Status	Kode	Deskripsi
Passed	`passed`	Lolos inspeksi kualitas
Failed	`failed`	Tidak lolos inspeksi kualitas
Pending	`pending`	Menunggu inspeksi kualitas

Lot Batch Item Type

Tipe	Kode	Deskripsi
Finished Good	`finished_good`	Produk jadi siap jual (default)
Semi Finished	`semi_finished`	Produk setengah jadi (intermediate)
Raw Material	`raw_material`	Bahan baku mentah

Lot Batch Expiry Alert Status

Status	Kode	Deskripsi
Normal	`normal`	Jauh dari tanggal kadaluarsa
Near Expiry	`near_expiry`	Mendekati kadaluarsa (H-30 hari)
Critical Expiry	`critical_expiry`	Kritis mendekati kadaluarsa (H-7 hari)
Expired	`expired`	Sudah melewati tanggal kadaluarsa

Lot Batch Cost Status

Status	Kode	Deskripsi
Complete	`complete`	Seluruh biaya modal telah tercatat lengkap
Provisional Incomplete	`provisional_incomplete`	Biaya belum lengkap, masih provisional
Unassigned	`unassigned`	Biaya belum diassign ke lot

Lot Batch Identity Status

Status	Kode	Deskripsi
Linked	`linked`	Identitas lot terhubung ke canonical product master
Legacy Review	`legacy_review`	Identitas perlu review manual (data lama/migrasi)

Quality Case Reason

Alasan	Kode	Deskripsi
Contamination	`contamination`	Kontaminasi fisik, kimia, atau biologis
Labeling Error	`labeling_error`	Kesalahan label (informasi, expired date, komposisi)
Expired	`expired`	Produk ditemukan sudah kadaluarsa
Customer Complaint	`customer_complaint`	Keluhan dari customer terkait kualitas
Packaging Defect	`packaging_defect`	Cacat pada kemasan (segel rusak, bocor, dll)
Other	`other`	Alasan lainnya

Quality Case Status

Status	Kode	Deskripsi
Open	`open`	Case baru dilaporkan, belum ditangani
Investigating	`investigating`	Tim sedang melakukan investigasi
On Hold	`on_hold`	Lot dikarantina, investigasi ditunda sementara
Resolved	`resolved`	Temuan telah diselesaikan
Closed	`closed`	Case ditutup secara administratif

Warehouse Location Type

Tipe	Kode	Deskripsi
Warehouse	`warehouse`	Gudang penyimpanan utama
Store	`store`	Toko/cabang retail
Transit	`transit`	Gudang transit / hub distribusi
Virtual	`virtual`	Lokasi virtual (stok dalam perjalanan, quarantine, dll)

Quality Check Overall Status

Status	Kode	Deskripsi
Pending	`pending`	Menunggu hasil pemeriksaan
Approved	`approved`	Hasil pemeriksaan disetujui
Rejected	`rejected`	Hasil pemeriksaan ditolak
Conditional	`conditional`	Disetujui dengan syarat tertentu

Quality Check Expiry Date Check

Status	Kode	Deskripsi
Valid	`valid`	Tanggal expired masih valid
Expired	`expired`	Barang sudah kadaluarsa
Near Expiry	`near_expiry`	Mendekati tanggal kadaluarsa
No Date	`no_date`	Tidak ada tanggal expired pada barang

Quality Check Checklist Result

Hasil	Kode	Deskripsi
Pass	`pass`	Item pengecekan memenuhi standar
Fail	`fail`	Item pengecekan tidak memenuhi standar
Warning	`warning`	Item mendekati batas toleransi
N/A	`na`	Item tidak applicable atau tidak diperiksa

QuinnOrder Status

Status	Kode	Deskripsi
Pending	`pending`	Order baru diterima, menunggu verifikasi
Confirmed	`confirmed`	Order dikonfirmasi
Processing	`processing`	Order sedang diproses
Shipped	`shipped`	Order sudah dikirim
Completed	`completed`	Order selesai
Cancelled	`cancelled`	Order dibatalkan

QuinnOrder Payment Status

Status	Kode	Deskripsi
Unpaid	`unpaid`	Belum ada pembayaran
Pending Verification	`pending_verification`	Bukti transfer menunggu verifikasi
Partially Paid	`partially_paid`	Pembayaran sebagian
Paid	`paid`	Pembayaran lunas terverifikasi
Rejected	`rejected`	Bukti pembayaran ditolak
Refunded	`refunded`	Dana dikembalikan

QuinnOrder Fulfillment Status

Status	Kode	Deskripsi
Unprocessed	`unprocessed`	Order belum diproses
Processing	`processing`	Order sedang diproses
Ready	`ready`	Barang siap dikirim
Shipped	`shipped`	Barang sudah dikirim
Delivered	`delivered`	Barang sudah diterima
Returned	`returned`	Barang dikembalikan

QuinnOrder Reservation Status

Status	Kode	Deskripsi
Active	`active`	Reservasi stok aktif
Consumed	`consumed`	Reservasi sudah digunakan
Released	`released`	Reservasi dilepaskan
Expired	`expired`	Reservasi kedaluwarsa

Partnership Application Type

Tipe	Kode	Deskripsi
Reseller	`reseller`	Kemitraan jual ulang produk
Integration	`integration`	Integrasi sistem/API
Community	`community`	Kemitraan komunitas
Strategic	`strategic`	Kemitraan strategis

Partnership Application Status

Status	Kode	Deskripsi
Submitted	`submitted`	Aplikasi baru diajukan
Reviewing	`reviewing`	Sedang ditinjau
Negotiation	`negotiation`	Dalam tahap negosiasi
Approved	`approved`	Aplikasi disetujui
Rejected	`rejected`	Aplikasi ditolak

Sequence Diagrams

Flow Pembuatan Shipment (Create Shipment)

Flow Tracking & Status Update

Flow Batch Recall

Flow Distribution Return

Flow Surat Jalan Generation

Fitur Utama

1. Shipment Management

Sistem membuat shipment baru dengan langkah-langkah terstruktur: validasi stok, pemilihan batch FIFO, pengisian data penerima, pemilihan logistik, dan integrasi ke modul Finance. FIFO Batch Selection: Sistem secara otomatis memilih batch tertua (First In, First Out) untuk memastikan produk yang dikirim memiliki sisa shelf life maksimal. Ini kritis untuk bisnis F&B karena berkaitan langsung dengan keamanan pangan dan kepuasan customer. Idempotency & Data Integrity: Setiap shipment creation menggunakan idempotency key yang tersimpan di field metadata untuk mencegah duplikasi, terutama penting saat integrasi dengan API logistik pihak ketiga.

2. Surat Jalan (Delivery Order)

Surat Jalan adalah dokumen fisik yang menyertai pengiriman. Sistem menggenerate preview surat jalan yang bisa dicetak:

Informasi di Surat Jalan	Sumber
Company letterhead	Company profile
Shipment number	DistributionShipment.shipment_number
Date	DistributionShipment.shipment_date
Recipient name & address	customer_name, destination_address
Product list	items[].product_name + items[].quantity
Batch numbers	items[].batch_id / items[].lot_number
Total items	Sum of items[].quantity
Signature area	prepared_by + received_by

3. Batch Recall Engine

recallEngine.js (280 baris) adalah modul kritis yang menangani penarikan batch produk bermasalah. Sistem ini digunakan ketika ada laporan kualitas negatif pada batch tertentu dan terhubung langsung dengan entitas QualityCase. Risk Levels:

Level	Kode	Aksi
LOW	`LOW`	Monitor, investigasi internal
MEDIUM	`MEDIUM`	Notifikasi partner, siapkan replacement
HIGH	`HIGH`	Recall aktif, hubungi semua penerima batch
CRITICAL	`CRITICAL`	Immediate recall, stop semua pengiriman batch terkait

Recall Flow: CSV Manifest Export: Untuk risk level HIGH dan CRITICAL, sistem mengexport CSV manifest yang berisi:

Kolom	Isi
shipment_number	Nomor pengiriman
recipient_name	Nama penerima
recipient_phone	Nomor telepon
address	Alamat lengkap
batch_number	Nomor batch
product_name	Nama produk
quantity	Jumlah yang dikirim
shipment_date	Tanggal pengiriman
status	Status pengiriman saat ini

4. Tracking & ETA

Setiap shipment memiliki estimasi waktu tiba (ETA) yang bisa diupdate berdasarkan status:

Status Change	ETA Update
Pending → Processing	Persiapan di gudang dimulai
Processing → Shipped	ETA dihitung dari SLA logistik
Shipped → In Transit	ETA dikonfirmasi, bisa diupdate oleh logistik
In Transit → Delivered	actual_arrival dicatat
Delivered → Confirmed	Penerima mengkonfirmasi, proses selesai

5. Distribution Return Management

Modul retur mengelola proses pengembalian barang dari customer/distributor secara terstruktur:

Pengajuan Retur: Customer mengajukan retur dengan menyebutkan item, quantity, dan alasan
Penerimaan Fisik: Barang diterima di gudang, dicatat lokasi penerimaannya (received_location_id)
Inspeksi QC: Barang melalui inspeksi Quality Control (qc_status: pending)
Karantina: Barang dikarantina sementara menunggu hasil QC (quarantine_status: quarantined)
Disposisi: Keputusan akhir — approved (kembali ke stok), rejected (write-off), atau conditional

6. Multi-Tenant & Row-Level Security

Semua entitas Distribution Tracking menggunakan Row-Level Security (RLS) berbasis company_id. Akses data dibatasi berdasarkan:

Company scoping: User hanya melihat data dari active_company_id mereka
Creator access: User yang membuat record dapat mengakses record tersebut
Admin override: User dengan role admin memiliki akses penuh

Cara Akses

Dari sidebar, klik menu B2B > Distribution Tracking.

Flow Penggunaan

Admin / Gudang

Buka halaman Distribution Tracking dari sidebar
Klik “Buat Pengiriman” untuk shipment baru
Pilih produk dan jumlah yang akan dikirim
Sistem otomatis memilih batch tertua (FIFO)
Isi detail penerima dan alamat
Pilih logistic provider dan input tracking number
Print surat jalan untuk menyertai pengiriman
Update status secara berkala seiring progres pengiriman

Batch Recall (Quality Issue)

Terima laporan kualitas negatif pada batch tertentu
Aktifkan recallEngine dengan batch number
Sistem assess risk level (LOW/MEDIUM/HIGH/CRITICAL)
Untuk HIGH/CRITICAL: export CSV manifest penerima terdampak
Hubungi penerima untuk arrange return/pickup
Update status shipment ke returned atau recalled
Quarantine stock yang dikembalikan
Buat DistributionReturn untuk proses retur formal

Retur Barang

Customer/distributor mengajukan permintaan retur
Sistem membuat DistributionReturn dengan status requested
Jadwalkan penerimaan barang di gudang
Terima barang fisik, update status ke received
Inspeksi QC terhadap barang retur
Tentukan disposisi: approved, rejected, atau conditional
Update stok sesuai disposisi akhir
Tutup proses retur (status: closed)

Integrasi Cross-Module

Detail Integrasi

Modul Terintegrasi	Arah	Deskripsi
Inventory (LotBatch)	Bidirectional	Shipment mengambil stok dari LotBatch (FIFO), update quantity_remaining saat shipped
Finance	Outbound	Shipment membuat invoice otomatis (`invoice_id`) dan FinancialRecord piutang (`finance_record_id`)
Quality Control (QualityCase)	Bidirectional	QualityCase memicu recall pada shipment; QualityCheck memverifikasi barang retur
Manufacturing (ProductionOrder)	Inbound	ProductionOrder menghasilkan LotBatch yang kemudian dikirim via DistributionShipment
Warehouse (WarehouseLocation)	Inbound	WarehouseLocation menjadi origin (gudang asal) dan destination untuk retur
HACCP (HACCPVerification)	Inbound	HACCPVerification memastikan batch yang dikirim memenuhi standar keamanan pangan
QuinnOrder	Inbound	Order dari website (D2C) dapat dikonversi menjadi DistributionShipment
B2B Partner Portal	Outbound	Partner dapat melihat status shipment mereka secara real-time

RBAC Permission Matrix

Berdasarkan Row-Level Security (RLS) yang didefinisikan pada setiap entitas:

Entitas	Operasi	Admin	Owner (Creator)	Same Company
DistributionShipment	Create	Ya	Ya	Ya (validasi company_id)
DistributionShipment	Read	Ya	Ya	Ya (validasi company_id)
DistributionShipment	Update	Ya	Ya	Ya (validasi company_id)
DistributionShipment	Delete	Ya	Ya	Ya (validasi company_id)
DistributionReturn	Create	Ya	Ya	Ya (validasi company_id)
DistributionReturn	Read	Ya	Ya	Ya (validasi company_id)
DistributionReturn	Update	Ya	Ya	Ya (validasi company_id)
DistributionReturn	Delete	Ya	Ya	Ya (validasi company_id)
LotBatch	Create	Ya	-	Ya
LotBatch	Read	Ya	-	Ya
LotBatch	Update	Ya	-	Ya
LotBatch	Delete	Ya	-	Ya
WarehouseLocation	Create	Ya	-	Ya
WarehouseLocation	Read	Ya	-	Ya
WarehouseLocation	Update	Ya	-	Ya
WarehouseLocation	Delete	Ya	-	Ya
QualityCheck	Create	Ya	-	Ya
QualityCheck	Read	Ya	-	Ya
QualityCheck	Update	Ya	-	Ya
QualityCheck	Delete	Ya	-	Ya
QualityCase	Create	Ya	-	Ya
QualityCase	Read	Ya	-	Ya
QualityCase	Update	Ya	-	Ya
QualityCase	Delete	Ya	-	Ya

Catatan RBAC:

Admin: Akses penuh ke semua operasi CRUD pada semua entitas dalam perusahaan.
Owner (Creator): Khusus DistributionShipment dan DistributionReturn, user yang membuat record memiliki akses penuh terlepas dari company_id.
Same Company: User dalam company yang sama dapat mengakses data selama company_id pada data cocok dengan active_company_id user dan tidak null atau kosong.
Semua entitas menggunakan isolasi multi-tenant berdasarkan company_id untuk mencegah kebocoran data antar perusahaan.

Tips

Selalu gunakan FIFO batch selection untuk memastikan shelf life produk optimal di tangan partner
Update status shipment secara real-time — partner bergantung pada informasi ini untuk perencanaan penerimaan
Untuk batch recall, mulai dari risk assessment sebelum mengambil aksi — tidak semua isu memerlukan CRITICAL level
Export CSV manifest secara berkala untuk audit trail dan compliance
Gunakan internal fleet untuk area lokal guna mengontrol kualitas pengiriman langsung
Manfaatkan field metadata untuk menyimpan idempotency key saat integrasi dengan API pihak ketiga
Selalu verifikasi HACCP sebelum melepas batch untuk pengiriman — field haccp_verified pada LotBatch adalah gate utama
Untuk retur, pastikan proses QC dilakukan sebelum disposisi — gunakan quarantine_status untuk melacak status karantina
Monitor expiry_alert_status pada LotBatch secara proaktif untuk mencegah pengiriman produk mendekati kadaluarsa
Gunakan cost_status pada LotBatch untuk memastikan kelengkapan pencatatan HPP sebelum shipment diinvoice ke Finance

​title: “Distribution Tracking” description: “Sistem tracking distribusi, shipment management, batch recall, dan surat jalan di SNISHOP ERP.”

​Distribution Tracking

​Arsitektur Komponen

​Entity Relationship Diagram

​Entity & Model

​DistributionShipment

​DistributionReturn

​LotBatch

​WarehouseLocation

​QualityCase

​Status Pipelines & Lifecycle Diagrams

​Shipment Status Lifecycle

​Distribution Return Lifecycle

​Quarantine Status Lifecycle (DistributionReturn)

​Lot Batch Status Lifecycle

​Quality Case Lifecycle

​QuinnOrder Fulfillment Lifecycle

​Enum Reference Tables

​DistributionShipment Status

​Customer Type

​Logistic Providers

​Distribution Return Status

​Distribution Return Quarantine Status

​Distribution Return QC Status

​Lot Batch Status

​Lot Batch Quality Status

​Lot Batch Item Type

​Lot Batch Expiry Alert Status

​Lot Batch Cost Status

​Lot Batch Identity Status

​Quality Case Reason

​Quality Case Status

​Warehouse Location Type

​Quality Check Overall Status

​Quality Check Expiry Date Check

​Quality Check Checklist Result

​QuinnOrder Status

​QuinnOrder Payment Status

​QuinnOrder Fulfillment Status

​QuinnOrder Reservation Status

​Partnership Application Type

​Partnership Application Status

​Sequence Diagrams

​Flow Pembuatan Shipment (Create Shipment)

​Flow Tracking & Status Update

​Flow Batch Recall

​Flow Distribution Return

​Flow Surat Jalan Generation

​Fitur Utama

​1. Shipment Management

​2. Surat Jalan (Delivery Order)

​3. Batch Recall Engine

​4. Tracking & ETA

​5. Distribution Return Management

​6. Multi-Tenant & Row-Level Security

​Cara Akses

​Flow Penggunaan

​Admin / Gudang

​Batch Recall (Quality Issue)

​Retur Barang

​Integrasi Cross-Module

​Detail Integrasi

​RBAC Permission Matrix

​Tips